schrodinger.analysis.enrichment.plotter module

Functions and classes for plotting enrichment job outputs. e.g. basic Sensitivity v 1-Specificity plots, etc.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.analysis.enrichment.plotter.calc_sensitivity_with_rank(total_actives, active_ranks, rank)
Calculates sensitivity at a particular rank, defined as:

Se(rank) = found_actives / total_actives

Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

  • rank (int) – Active rank at which to calculate the specificity.

Returns

Sensitivity of the screen at a given rank.

Return type

float

schrodinger.analysis.enrichment.plotter.calc_specificity_with_rank(total_actives, total_ligands, active_ranks, rank)
Calculates specificity at a particular rank, defined as:

Sp(rank) = discarded_decoys / total_decoys

Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • total_ligands (int) – The number of the total number of ligands (actives and unknowns/decoys) used in the screen.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

  • rank (int) – Active rank at which to calculate the specificity.

Returns

Specificity of the screen at a given rank.

Return type

float

schrodinger.analysis.enrichment.plotter.get_percent_screen_curve_points(total_actives, total_ligands, active_ranks)
Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • total_ligands (int) – The number of the total number of ligands (actives and unknowns/decoys) used in the screen.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

Returns

List of (%Screen, %Actives Found) tuples for the active ranks.

schrodinger.analysis.enrichment.plotter.get_plot_data(total_actives, total_ligands, active_ranks, title_ranks)
Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • total_ligands (int) – The number of the total number of ligands (actives and unknowns/decoys) used in the screen.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

Returns

A list of active Title, Rank, Sensitivity, Specificity, %Actives Found, %Screen tuples.

Return type

list

Note

This function should only be accessed via Calculator unless we figured how to get title_ranks without an additional O(n) work.

Note

This list may grow, but the relative order of the columns should remain fixed.

schrodinger.analysis.enrichment.plotter.get_roc_curve_points(total_actives, total_ligands, active_ranks)

Calculates set of points in ROC curve along each active rank.

Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • total_ligands (int) – The number of the total number of ligands (actives and unknowns/decoys) used in the screen.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

Returns

List of (1 - specificity, sensitivity, rank) tuples.

Return type

list of tuples

schrodinger.analysis.enrichment.plotter.save_plot(total_actives, total_ligands, active_ranks, adjusted_active_ranks, total_ranked, png_file='plot.png', title='Screen Results', xlabel='1-Specificity', ylabel='Sensitivity')

Saves an image of the ROC plot, Sensitivity v 1-Specificity, to a png file.

Parameters
  • total_actives (int) – The number of all active ligands in the screen, ranked and unranked.

  • total_ligands (int) – The number of the total number of ligands (actives and unknowns/decoys) used in the screen.

  • active_ranks (list(int)) – List of unadjusted integer ranks for the actives found in the screen. For example, a screen result that placed three actives as the first three ranks has an active_ranks list of = [1, 2, 3].

  • adjusted_active_ranks (list(int)) – Modified active ranks; each rank is improved by the number of preceding actives. For example, a screen result that placed three actives as the first three ranks, [1, 2, 3], has adjusted ranks of [1, 1, 1]. In this way, actives are not penalized by being outranked by other actives.

  • total_ranked (int) – The number of unique ranked ligands. Deduced from results_file or merged_file.

  • png_file (str) – Path to output file, default is ‘plot.png’.

  • title (str) – Plot title, default is ‘Screen Results’.

  • xlabel (str) – x-axis label, default is ‘1-Specificity’.

  • ylabel (str) – y-axis label, default is ‘Sensitivity’.

class schrodinger.analysis.enrichment.plotter.Plotter(calculators, title='Screen Results', xlabel='1-Specificity', ylabel='Sensitivity', legend_label='Screen Results')

Bases: schrodinger.analysis.enrichment.plotter._BasePlotter

A class to plot multiple series of Calculator instances.

API example where enrich_calc1 and enrich_calc2 are instances of Calculator:

enrich_plotter = plotter.Plotter([enrich_calc1, enrich_calc2])
enrich_plotter.plot() # Launch interactive plot window.
enrich_plotter.savePlot('my_plot.png') # Save plot to file.

There are six line styles defined by default. Plotting more than six results cycles through the styles.

__init__(calculators, title='Screen Results', xlabel='1-Specificity', ylabel='Sensitivity', legend_label='Screen Results')
Parameters
  • calculators (list(calculator.Calculator)) – List of Calculator instances.

  • title (string) – The plot title.

  • xlabel (str) – The x-axis label.

  • ylabel (str) – The y-axis label.

  • legend_label (str) – The legend label.

getPointsFromCalc(calculator)

Returns points for this metric from the given Calculator instance.

Parameters

calculator (calculator.Calculator) – Calculator instance.

:return List of (x, y) points :rtype: list

addReferenceSeries(style=None, plot_figure=None)

Adds a diagonal representing random performance.

Parameters
  • style (string) – The matplotlib linestyle. If style is None then ‘k-’ is used.

  • plot_figure (pyplot.Figure) – A pyplot figure. If None then the current figure is used.

Returns

None

addSeries(calculator, style=None, plot_figure=None)
Parameters
  • calculator (calculator.Calculator) – Calculator instance.

  • style (string) – The matplotlib linestyle. If style is None then a style is selected by fetching the next element from self.styles.

  • plot_figure (plt.Figure) – A pyplot figure. If None then the current figure is used.

Returns

None

getPlotFigure(indexes=None)

Returns a new pyplot figure the plot.

Parameters

indexes (list) – List of indexes into self.calcs to include in the plot. If the argument is None then all series are plotted.

Returns

a pyplot figure.

plot(indexes=None)

Launch interactive matplotlib viewer loaded with the plot.

Parameters

indexes (list) – List of indexes into self.calcs to include in the plot. If the argument is None then all series are plotted.

savePlot(png_file='plot.png')

Serialized figure to a png format file.

Parameters

png_file (string) – Path to output png file.

Returns

None

showPlotWindow(win_title)

Open a window with this plot.

Parameters

win_title (str) – Title for the plot window.

class schrodinger.analysis.enrichment.plotter.PercentScreenPlotter(calculators, title='Screen Results', xlabel='Percent Screen', ylabel='Percent Actives Found', legend_label='Screen Results')

Bases: schrodinger.analysis.enrichment.plotter._BasePlotter

A class to plot multiple series of Calculator data as %Actives Found vs %Screen.

API example where enrich_calc1 and enrich_calc2 are instances of Calculator:

enrich_plotter = plotter.PercentScreenPlotter([enrich_calc1,
                                               enrich_calc2])
enrich_plotter.plot() # Launch interactive plot window.
enrich_plotter.savePlot('my_plot.png') # Save plot to file.

There are six line styles defined by default. Plotting more than six results cycles through the styles.

__init__(calculators, title='Screen Results', xlabel='Percent Screen', ylabel='Percent Actives Found', legend_label='Screen Results')
Parameters
  • calculators (list(calculator.Calculator)) – List of Calculator instances.

  • title (string) – The plot title.

  • xlabel (str) – The x-axis label.

  • ylabel (str) – The y-axis label.

  • legend_label (str) – The legend label.

getPointsFromCalc(calculator)

Returns points for this metric from the given Calculator instance.

Parameters

calculator (calculator.Calculator) – Calculator instance.

:return List of (x, y) points :rtype: list

addReferenceSeries(style=None, plot_figure=None)

Adds a diagonal representing random performance.

Parameters
  • style (string) – The matplotlib linestyle. If style is None then ‘k-’ is used.

  • plot_figure (pyplot.Figure) – A pyplot figure. If None then the current figure is used.

Returns

None

addSeries(calculator, style=None, plot_figure=None)
Parameters
  • calculator (calculator.Calculator) – Calculator instance.

  • style (string) – The matplotlib linestyle. If style is None then a style is selected by fetching the next element from self.styles.

  • plot_figure (plt.Figure) – A pyplot figure. If None then the current figure is used.

Returns

None

getPlotFigure(indexes=None)

Returns a new pyplot figure the plot.

Parameters

indexes (list) – List of indexes into self.calcs to include in the plot. If the argument is None then all series are plotted.

Returns

a pyplot figure.

plot(indexes=None)

Launch interactive matplotlib viewer loaded with the plot.

Parameters

indexes (list) – List of indexes into self.calcs to include in the plot. If the argument is None then all series are plotted.

savePlot(png_file='plot.png')

Serialized figure to a png format file.

Parameters

png_file (string) – Path to output png file.

Returns

None

showPlotWindow(win_title)

Open a window with this plot.

Parameters

win_title (str) – Title for the plot window.