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_fraction(total_actives, total_ligands, active_ranks, fraction_of_screen)

Calculates sensitivity at a particular fraction of screen.

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].
  • fraction_of_screen (float) – Fraction of screen at which to calculate the specificity.
Returns:

Sensitivity of the screen at a given fraction of screen.

Return type:

float

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.get_roc_area_romberg(lower_limit=0.0, upper_limit=1.0)
Returns:Receiver Operator Characteristic area under the curve as defined by a Romberg integration between arbitrary points along 1-Sp (domain: 0-1).
Return type:float
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 (pylab.Figure) – A pylab 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 (pylab.Figure) – A pylab figure. If None then the current figure is used.
Returns:

None

getPlotFigure(indexes=None)

Returns a new pylab 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 pylab 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 (pylab.Figure) – A pylab 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 (pylab.Figure) – A pylab figure. If None then the current figure is used.
Returns:

None

getPlotFigure(indexes=None)

Returns a new pylab 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 pylab 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.