lsst.sims.maf.metricBundles package

Submodules

lsst.sims.maf.metricBundles.metricBundle module

class lsst.sims.maf.metricBundles.metricBundle.MetricBundle(metric, slicer, constraint=None, sqlconstraint=None, stackerList=None, runName='opsim', metadata=None, plotDict=None, displayDict=None, summaryMetrics=None, mapsList=None, fileRoot=None, plotFuncs=None)

Bases: object

The MetricBundle is defined by a combination of a (single) metric, slicer and constraint - together these define a unique combination of an opsim benchmark. An example would be: a CountMetric, a HealpixSlicer, and a sqlconstraint ‘filter=”r”’.

After the metric is evaluated over the slicePoints of the slicer, the resulting metric values are saved in the MetricBundle.

The MetricBundle also saves the summary metrics to be used to generate summary statistics over those metric values, as well as the resulting summary statistic values.

Plotting parameters and display parameters (for showMaf) are saved in the MetricBundle, as well as additional metadata such as the opsim run name, and relevant stackers and maps to apply when calculating the metric values.

colInfo

computeSummaryStats(resultsDb=None)

Compute summary statistics on metricValues, using summaryMetrics (metricbundle list).

Parameters

resultsDb (Optional[ResultsDb]) – ResultsDb object to use to store the summary statistic values on disk.

outputJSON()

Set up and call the baseSlicer outputJSON method, to output to IO string.

Returns

IO object containing JSON data representing the metric bundle data.

Return type

io

plot(plotHandler=None, plotFunc=None, outfileSuffix=None, savefig=False)

Create all plots available from the slicer. plotHandler holds the output directory info, etc.

Parameters

• plotHandler (Optional[PlotHandler]) – The plotHandler saves the output location and resultsDb connection for a set of plots.

• plotFunc (Optional[BasePlotter]) – Any plotter function. If not specified, the plotters in self.plotFuncs will be used.

• outfileSuffix (Optional[str]) – Optional string to append to the end of the plot output files. Useful when creating sequences of images for movies.

• savefig (Optional[bool]) – Flag indicating whether or not to save the figure to disk. Default is False.

Returns

Dictionary of plotType:figure number key/value pairs, indicating what plots were created and what matplotlib figure numbers were used.

Return type

dict

read(filename)

Read metricValues and associated metadata from disk. Overwrites any data currently in metricbundle.

Parameters

filename (str) – The file from which to read the metric bundle data.

reduceMetric(reduceFunc, reducePlotDict=None, reduceDisplayDict=None)

Run ‘reduceFunc’ (any function that operates on self.metricValues). Typically reduceFunc will be the metric reduce functions, as they are tailored to expect the metricValues format. reduceDisplayDict and reducePlotDicts are displayDicts and plotDicts to be applied to the new metricBundle.

Parameters

• reduceFunc (Func) – Any function that will operate on self.metricValues (typically metric.reduce* function).

• reducePlotDict (Optional[dict]) – Plot dictionary for the results of the reduce function.

• reduceDisplayDict (Optional[dict]) – Display dictionary for the results of the reduce function.

Returns

New metric bundle, inheriting metadata from this metric bundle, but containing the new metric values calculated with the ‘reduceFunc’.

Return type

MetricBundle

setDisplayDict(displayDict=None, resultsDb=None)

Set or update any property of displayDict.

Parameters

• displayDict (Optional[dict]) – Dictionary of display parameters for showMaf. Expected keywords: ‘group’, ‘subgroup’, ‘order’, ‘caption’. ‘group’, ‘subgroup’, and ‘order’ control where the metric results are shown on the showMaf page. ‘caption’ provides a caption to use with the metric results. These values are saved in the results database.

• resultsDb (Optional[ResultsDb]) – A MAF results database, used to save the display parameters.

setPlotDict(plotDict)

Set or update any property of plotDict.

Parameters

plotDict (dict) – A dictionary of plotting parameters. The usable keywords vary with each lsst.sims.maf.plots Plotter.

setPlotFuncs(plotFuncs)

Set or reset the plotting functions.

The default is to use all the plotFuncs associated with the slicer, which is what happens in self.plot if setPlotFuncs is not used to override self.plotFuncs.

Parameters

plotFuncs (List[BasePlotter]) – The plotter or plotters to use to generate visuals for this metric.

setRunName(runName, updateFileRoot=True)

Set (or reset) the runName. FileRoot will be updated accordingly if desired.

Parameters

• runName (str) – Run Name, which will become part of the fileRoot.

• fileRoot (bool, opt) – Flag to update the fileRoot with the runName. Default True.

setSummaryMetrics(summaryMetrics)

Set (or reset) the summary metrics for the metricbundle.

Parameters

summaryMetrics (List[BaseMetric]) – Instantiated summary metrics to use to calculate summary statistics for this metric.

write(comment='', outDir='.', outfileSuffix=None, resultsDb=None)

Write metricValues (and associated metadata) to disk.

Parameters

• comment (Optional[str]) – Any additional comments to add to the output file

• outDir (Optional[str]) – The output directory

• outfileSuffix (Optional[str]) – Additional suffix to add to the output files (typically a numerical suffix for movies)

• resultsD (Optional[ResultsDb]) – Results database to store information on the file output

writeDb(resultsDb=None, outfileSuffix=None)

Write the metricValues to the database

lsst.sims.maf.metricBundles.metricBundle.createEmptyMetricBundle()

Create an empty metric bundle.

Returns

An empty metric bundle, configured with just the BaseMetric and BaseSlicer.

Return type

MetricBundle

lsst.sims.maf.metricBundles.metricBundleGroup module

class lsst.sims.maf.metricBundles.metricBundleGroup.MetricBundleGroup(bundleDict, dbObj, outDir='.', resultsDb=None, verbose=True, saveEarly=True, dbTable=None)

Bases: object

The MetricBundleGroup exists to calculate the metric values for a group of MetricBundles.

The MetricBundleGroup will query data from a single database table (for multiple constraints), use that data to calculate metric values for multiple slicers, and calculate summary statistics and generate plots for all metrics included in the dictionary passed to the MetricBundleGroup.

We calculate the metric values here, rather than in the individual MetricBundles, because it is much more efficient to step through a slicer once (and calculate all the relevant metric values at each point) than it is to repeat this process multiple times.

The MetricBundleGroup also determines how to efficiently group the MetricBundles to reduce the number of sql queries of the database, grabbing larger chunks of data at once.

Parameters

• bundleDict (dict or list of MetricBundles) – Individual MetricBundles should be placed into a dictionary, and then passed to the MetricBundleGroup. The dictionary keys can then be used to identify MetricBundles if needed – and to identify new MetricBundles which could be created if ‘reduce’ functions are run on a particular MetricBundle. A bundleDict can be conveniently created from a list of MetricBundles using makeBundlesDictFromList (done automatically if a list is passed in)

• dbObj (Database) – The database object (typically an OpsimDatabase) connected to the data to be used to calculate metrics. Advanced use: It is possible to set this to None, in which case data should be passed directly to the runCurrent method (and runAll should not be used).

• outDir (str, opt) – Directory to save the metric results. Default is the current directory.

• resultsDb (ResultsDb, opt) – A results database. If not specified, one will be created in the outDir. This database saves information about the metrics calculated, including their summary statistics.

• verbose (bool, opt) – Flag to turn on/off verbose feedback.

• saveEarly (bool, opt) – If True, metric values will be saved immediately after they are first calculated (to prevent data loss) as well as after summary statistics are calculated. If False, metric values will only be saved after summary statistics are calculated.

• dbTable (str, opt) – The name of the table in the dbObj to query for data.

getData(constraint)

Query the data from the database.

The currently bundleDict should generally be set before calling getData (using setCurrent).

Parameters

constraint (str) – The constraint for the currently active set of MetricBundles.

plotAll(savefig=True, outfileSuffix=None, figformat='pdf', dpi=600, trimWhitespace=True, thumbnail=True, closefigs=True)

Generate all the plots for all the metricBundles in bundleDict.

Generating all ploots, for all MetricBundles, at this point, assumes that clearMemory was False.

Parameters

• savefig (bool, opt) – If True, save figures to disk, to self.outDir directory.

• outfileSuffix (bool, opt) – Append outfileSuffix to the end of every plot file generated. Useful for generating sequential series of images for movies.

• figformat (str, opt) – Matplotlib figure format to use to save to disk. Default pdf.

• dpi (int, opt) – DPI for matplotlib figure. Default 600.

• trimWhitespace (bool, opt) – If True, trim additional whitespace from final figures. Default True.

• thumbnail (bool, opt) – If True, save a small thumbnail jpg version of the output file to disk as well. This is useful for showMaf web pages. Default True.

• closefigs (bool, opt) – Close the matplotlib figures after they are saved to disk. If many figures are generated, closing the figures saves significant memory. Default True.

plotCurrent(savefig=True, outfileSuffix=None, figformat='pdf', dpi=600, trimWhitespace=True, thumbnail=True, closefigs=True)

Generate the plots for the currently active set of MetricBundles.

Parameters

• savefig (bool, opt) – If True, save figures to disk, to self.outDir directory.

• outfileSuffix (str, opt) – Append outfileSuffix to the end of every plot file generated. Useful for generating sequential series of images for movies.

• figformat (str, opt) – Matplotlib figure format to use to save to disk. Default pdf.

• dpi (int, opt) – DPI for matplotlib figure. Default 600.

• trimWhitespace (bool, opt) – If True, trim additional whitespace from final figures. Default True.

• thumbnail (bool, opt) – If True, save a small thumbnail jpg version of the output file to disk as well. This is useful for showMaf web pages. Default True.

• closefigs (bool, opt) – Close the matplotlib figures after they are saved to disk. If many figures are generated, closing the figures saves significant memory. Default True.

readAll()

Attempt to read all MetricBundles from disk.

You must set the metrics/slicer/constraint/runName for a metricBundle appropriately; then this method will search for files in the location self.outDir/metricBundle.fileRoot. Reads all the files associated with all metricbundles in self.bundleDict.

reduceAll(updateSummaries=True)

Run the reduce methods for all metrics in bundleDict.

Running this method, for all MetricBundles at once, assumes that clearMemory was False.

Parameters

updateSummaries (bool, opt) – If True, summary metrics are removed from the top-level (non-reduced) MetricBundle. Usually this should be True, as summary metrics are generally intended to run on the simpler data produced by reduce metrics.

reduceCurrent(updateSummaries=True)

Run all reduce functions for the metricbundle in the currently active set of MetricBundles.

Parameters

updateSummaries (bool, opt) – If True, summary metrics are removed from the top-level (non-reduced) MetricBundle. Usually this should be True, as summary metrics are generally intended to run on the simpler data produced by reduce metrics.

runAll(clearMemory=False, plotNow=False, plotKwargs=None)

Runs all the metricBundles in the metricBundleGroup, over all constraints.

Calculates metric values, then runs reduce functions and summary statistics for all MetricBundles.

Parameters

• clearMemory (bool, opt) – If True, deletes metric values from memory after running each constraint group.

• plotNow (bool, opt) – If True, plots the metric values immediately after calculation.

• plotKwargs (bool, opt) – kwargs to pass to plotCurrent.

runCurrent(constraint, simData=None, clearMemory=False, plotNow=False, plotKwargs=None)

Run all the metricBundles which match this constraint in the metricBundleGroup.

Calculates the metric values, then runs reduce functions and summary statistics for metrics in the current set only (see self.setCurrent).

Parameters

• constraint (str) – constraint to use to set the currently active metrics

• simData (numpy.ndarray, opt) – If simData is not None, then this numpy structured array is used instead of querying data from the dbObj.

• clearMemory (bool, opt) – If True, metric values are deleted from memory after they are calculated (and saved to disk).

• plotNow (bool, opt) – Plot immediately after calculating metric values (instead of the usual procedure, which is to plot after metric values are calculated for all constraints).

• plotKwargs (kwargs, opt) – Plotting kwargs to pass to plotCurrent.

setCurrent(constraint)

Utility to set the currentBundleDict (i.e. a set of metricBundles with the same SQL constraint).

Parameters

constraint (str) – The subset of MetricBundles with metricBundle.constraint == constraint will be included in a subset identified as the currentBundleDict. These are the active metrics to be calculated and plotted, etc.

summaryAll()

Run the summary statistics for all metrics in bundleDict.

Calculating all summary statistics, for all MetricBundles, at this point assumes that clearMemory was False.

summaryCurrent()

Run summary statistics on all the metricBundles in the currently active set of MetricBundles.

writeAll()

Save all the MetricBundles to disk.

Saving all MetricBundles to disk at this point assumes that clearMemory was False.

writeCurrent()

Save all the MetricBundles in the currently active set to disk.

lsst.sims.maf.metricBundles.metricBundleGroup.makeBundlesDictFromList(bundleList)

Utility to convert a list of MetricBundles into a dictionary, keyed by the fileRoot names.

Raises an exception if the fileroot duplicates another metricBundle. (Note this should alert to potential cases of filename duplication).

Parameters

bundleList (list of MetricBundles) –

lsst.sims.maf.metricBundles.moMetricBundle module

class lsst.sims.maf.metricBundles.moMetricBundle.MoMetricBundle(metric, slicer, constraint=None, stackerList=None, runName='opsim', metadata=None, fileRoot=None, plotDict=None, plotFuncs=None, displayDict=None, childMetrics=None, summaryMetrics=None)

Bases: lsst.sims.maf.metricBundles.metricBundle.MetricBundle

computeSummaryStats(resultsDb=None)

Compute summary statistics on metricValues, using summaryMetrics, for self and child bundles.

reduceMetric(reduceFunc, reducePlotDict=None, reduceDisplayDict=None)

Run ‘reduceFunc’ (any function that operates on self.metricValues). Typically reduceFunc will be the metric reduce functions, as they are tailored to expect the metricValues format. reduceDisplayDict and reducePlotDicts are displayDicts and plotDicts to be applied to the new metricBundle.

Parameters

• reduceFunc (Func) – Any function that will operate on self.metricValues (typically metric.reduce* function).

• reducePlotDict (Optional[dict]) – Plot dictionary for the results of the reduce function.

• reduceDisplayDict (Optional[dict]) – Display dictionary for the results of the reduce function.

Returns

New metric bundle, inheriting metadata from this metric bundle, but containing the new metric values calculated with the ‘reduceFunc’.

Return type

MetricBundle

setChildBundles(childMetrics=None)

Identify any child metrics to be run on this (parent) bundle. and create the new metric bundles that will hold the child values, linking to this bundle. Remove the summaryMetrics from self afterwards.

class lsst.sims.maf.metricBundles.moMetricBundle.MoMetricBundleGroup(bundleDict, outDir='.', resultsDb=None, verbose=True)

Bases: object

plotAll(savefig=True, outfileSuffix=None, figformat='pdf', dpi=600, thumbnail=True, closefigs=True)

Make a few generically desired plots. This needs more flexibility in the future.

runAll()

Run all constraints and metrics for these moMetricBundles.

runConstraint(constraint)

Calculate the metric values for all the metricBundles which match this constraint in the metricBundleGroup. Also calculates child metrics and summary statistics, and writes all to disk. (work is actually done in _runCompatible, so that only completely compatible sets of metricBundles run at the same time).

Parameters

constraint (str) – SQL-where or pandas constraint for the metricBundles.

lsst.sims.maf.metricBundles.moMetricBundle.createEmptyMoMetricBundle()

Create an empty metric bundle.

Returns

An empty metric bundle, configured with just the BaseMetric and BaseSlicer.

Return type

MoMetricBundle

lsst.sims.maf.metricBundles.moMetricBundle.makeCompletenessBundle(bundle, completenessMetric, Hmark=None, resultsDb=None)

Make a mock metric bundle from a bundle which had MoCompleteness or MoCumulativeCompleteness summary metrics run. This lets us use the plotHandler + plots.MetricVsH to generate plots. Will also work with completeness metric run in order to calculate fraction of the population, or with MoCompletenessAtTime metric.

Parameters

• bundle (MetricBundle) – The metric bundle with a completeness summary statistic.

• completenessMetric (metric) – The summary (completeness) metric to run on the bundle.

• Hmark (float, opt) – The Hmark value to add to the plotting dictionary of the new mock bundle. Default None.

• resultsDb (ResultsDb, opt) – The resultsDb in which to record the summary statistic value at Hmark. Default None.

Returns

Return type

MoMetricBundle

Module contents