diff --git a/tutorials/Getting_MAF_Help.ipynb b/tutorials/Getting_MAF_Help.ipynb new file mode 100644 index 00000000..c54eba5d --- /dev/null +++ b/tutorials/Getting_MAF_Help.ipynb @@ -0,0 +1,801 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Getting Help in MAF\n", + "\n", + "This notebook is a collection of snippets of how to get help on the various bits of the **MAF** ecosystem. It shows some of the **MAF** provided help functions. It also uses the `help` function. The `help` function used below is a Python standard library function. It can be used on any module, class or function. Using `help` should give clarity to the parameters used in associated functions. It will also list functions associated with modules and classes. The notebook also uses the `dir` command which is another Python standard library function. This is useful for getting a list of names from the target object (module/class/function). " + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "WARNING: AstropyDeprecationWarning: Config parameter 'default_cosmology' in section [astropy.cosmology.core] is deprecated. Use science state astropy.cosmology.core.default_cosmology instead. [astropy.utils.state]\n", + "WARNING:astropy:AstropyDeprecationWarning: Config parameter 'default_cosmology' in section [astropy.cosmology.core] is deprecated. Use science state astropy.cosmology.core.default_cosmology instead.\n" + ] + } + ], + "source": [ + "# Need to import everything before getting help!\n", + "import lsst.sims.maf\n", + "import lsst.sims.maf.metrics as metrics\n", + "import lsst.sims.maf.slicers as slicers\n", + "import lsst.sims.maf.stackers as stackers\n", + "import lsst.sims.maf.plots as plots" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "---- AveSlewFracMetric ----\n", + "None\n", + "---- BinaryMetric ----\n", + "Return 1 if there is data. \n", + "---- Coaddm5Metric ----\n", + "Calculate the coadded m5 value at this gridpoint.\n", + "---- CompletenessMetric ----\n", + "Compute the completeness and joint completeness \n", + "---- CountMetric ----\n", + "Count the length of a simData column slice. \n", + "---- CountRatioMetric ----\n", + "Count the length of a simData column slice, then divide by 'normVal'. \n", + "---- CountSubsetMetric ----\n", + "Count the length of a simData column slice which matches 'subset'. \n", + "---- CountUniqueMetric ----\n", + "Return the number of unique values \n", + "---- ExgalM5 ----\n", + "Calculate co-added five-sigma limiting depth after dust extinction.\n", + "---- FftMetric ----\n", + "Calculate a truncated FFT of the exposure times.\n", + "---- FilterColorsMetric ----\n", + "Calculate an RGBA value that accounts for the filters used up to time t0.\n", + "---- FracAboveMetric ----\n", + "None\n", + "---- FracBelowMetric ----\n", + "None\n", + "---- FullRangeAngleMetric ----\n", + "Calculate the full range of an angular (radians) simData column slice.\n", + "\n", + "'FullRangeAngle' differs from 'FullRange' in that it accounts for wraparound at 2pi.\n", + "---- FullRangeMetric ----\n", + "Calculate the range of a simData column slice.\n", + "---- HourglassMetric ----\n", + "Plot the filters used as a function of time. Must be used with the Hourglass Slicer.\n", + "---- IdentityMetric ----\n", + "Return the metric value itself .. this is primarily useful as a summary statistic for UniSlicer metrics.\n", + "---- LinkedMetric ----\n", + "Calculate how many other healpixels a given observation is linked to. This is a fairly crude measure of how well the observations are linked for self-calibration pruposes. An even better metric would look at the chip level since that's how large calibration patches will be.\n", + "\n", + "Maybe even better would be to find the common co-added depth of a pixel with all it's neighboring healpixels! Maybe a complex metric with min and max reduce functions...Do I grab the 4 nearest pixels or 8?\n", + "---- LongGapAGNMetric ----\n", + "max delta-t and average of the top-10 longest gaps.\n", + " \n", + "---- MaxMetric ----\n", + "Calculate the maximum of a simData column slice.\n", + "---- MaxPercentMetric ----\n", + "Return the percent of the data which has the maximum value.\n", + "---- MaxStateChangesWithinMetric ----\n", + "Compute the maximum number of changes of state that occur within a given timespan.\n", + "(useful for calculating time between filter changes in particular).\n", + "'timespan' should be in minutes.\n", + "---- MeanAngleMetric ----\n", + "Calculate the mean of an angular (radians) simData column slice.\n", + "\n", + "'MeanAngle' differs from 'Mean' in that it accounts for wraparound at 2pi.\n", + "---- MeanMetric ----\n", + "Calculate the mean of a simData column slice.\n", + "---- MedianAbsMetric ----\n", + "Calculate the median of the absolute value of a simData column slice.\n", + "---- MedianMetric ----\n", + "Calculate the median of a simData column slice.\n", + "---- MinMetric ----\n", + "Calculate the minimum of a simData column slice.\n", + "---- MinTimeBetweenStatesMetric ----\n", + "Compute the minimum time between changes of state in a column value.\n", + "(useful for calculating fastest time between filter changes in particular).\n", + "Returns delta time in minutes!\n", + "---- NChangesMetric ----\n", + "Compute the number of times a column value changes.\n", + "(useful for filter changes in particular).\n", + "---- NRevisitsMetric ----\n", + "Calculate the number of (consecutive) visits with time differences less than dT.\n", + "---- NStateChangesFasterThanMetric ----\n", + "Compute the number of changes of state that happen faster than 'cutoff'.\n", + "(useful for calculating time between filter changes in particular).\n", + "'cutoff' should be in minutes.\n", + "---- NormalizeMetric ----\n", + "Return a metric values divided by 'normVal'. Useful for turning summary statistics into fractions.\n", + "---- NoutliersNsigmaMetric ----\n", + "Calculate the # of visits less than nSigma below the mean (nSigma<0) or\n", + "more than nSigma above the mean of 'col'.\n", + "---- OpenShutterFractionMetric ----\n", + "Compute the fraction of time the shutter is open compared to the total time spent observing.\n", + "---- ParallaxMetric ----\n", + "Calculate the uncertainty in a parallax measures given a serries of observations.\n", + " \n", + "---- PassMetric ----\n", + "Just pass the entire array through\n", + "---- PercentileMetric ----\n", + "None\n", + "---- ProperMotionMetric ----\n", + "Calculate the uncertainty in the returned proper motion. Assuming Gaussian errors.\n", + " \n", + "---- RadiusObsMetric ----\n", + "find the radius in the focal plane. \n", + "---- RapidRevisitMetric ----\n", + "Calculate uniformity of time between consecutive visits on short timescales (for RAV1).\n", + "---- RmsAngleMetric ----\n", + "Calculate the standard deviation of an angular (radians) simData column slice.\n", + "\n", + "'RmsAngle' differs from 'Rms' in that it accounts for wraparound at 2pi.\n", + "---- RmsMetric ----\n", + "Calculate the standard deviation of a simData column slice.\n", + "---- RobustRmsMetric ----\n", + "Use the inter-quartile range of the data to estimate the RMS. Robust since this calculation\n", + "does not include outliers in the distribution\n", + "---- SlewContributionMetric ----\n", + "None\n", + "---- SumMetric ----\n", + "Calculate the sum of a simData column slice.\n", + "---- SupernovaMetric ----\n", + "Measure how many time series meet a given time and filter distribution requirement.\n", + "---- TableFractionMetric ----\n", + "Count the completeness (for many fields) and summarize how many fields have given completeness levels\n", + "(within a series of bins). Works with completenessMetric only.\n", + "\n", + "This metric is meant to be used as a summary statistic on something like the completeness metric.\n", + "The output is DIFFERENT FROM SSTAR and is:\n", + " element matching values\n", + " 0 0 == P\n", + " 1 0 < P < .1\n", + " 2 .1 <= P < .2\n", + " 3 .2 <= P < .3\n", + " ...\n", + " 10 .9 <= P < 1\n", + " 11 1 == P\n", + " 12 1 < P\n", + " Note the 1st and last elements do NOT obey the numpy histogram conventions.\n", + "---- TeffMetric ----\n", + "Effective time equivalent for a given set of visits.\n", + "---- TemplateExistsMetric ----\n", + "Calculate the fraction of images with a previous template image of desired quality.\n", + "---- TgapsMetric ----\n", + "Histogram up all the time gaps \n", + "---- TotalPowerMetric ----\n", + "Calculate the total power in the angular power spectrum between lmin/lmax.\n", + "---- TransientMetric ----\n", + "Calculate what fraction of the transients would be detected. Best paired with a spatial slicer.\n", + "We are assuming simple light curves with no color evolution.\n", + "---- UniformityMetric ----\n", + "Calculate how uniformly the observations are spaced in time. Returns a value between -1 and 1.\n", + "A value of zero means the observations are perfectly uniform.\n", + "---- VisitGroupsMetric ----\n", + "Count the number of visits per night within deltaTmin and deltaTmax.\n", + "---- ZeropointMetric ----\n", + "Return a metric values with the addition of 'zp'. Useful for altering the zeropoint for summary statistics.\n", + "---- fOArea ----\n", + "Metric to calculate the FO Area; works with FO slicer only.\n", + "---- fONv ----\n", + "Metric to calculate the FO_Nv; works with FO slicer only.\n" + ] + } + ], + "source": [ + "# Show the list of metrics with a little bit of documentation\n", + "metrics.BaseMetric.list(doc=True)" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Help on class MaxMetric in module lsst.sims.maf.metrics.simpleMetrics:\n", + "\n", + "class MaxMetric(lsst.sims.maf.metrics.baseMetric.BaseMetric)\n", + " | Calculate the maximum of a simData column slice.\n", + " | \n", + " | Method resolution order:\n", + " | MaxMetric\n", + " | lsst.sims.maf.metrics.baseMetric.BaseMetric\n", + " | __builtin__.object\n", + " | \n", + " | Methods defined here:\n", + " | \n", + " | run(self, dataSlice, slicePoint=None)\n", + " | \n", + " | ----------------------------------------------------------------------\n", + " | Methods inherited from lsst.sims.maf.metrics.baseMetric.BaseMetric:\n", + " | \n", + " | __init__(self, col=None, metricName=None, maps=None, units=None, metricDtype=None, badval=-666)\n", + " | Instantiate metric.\n", + " | \n", + " | 'col' is a kwarg for purposes of the MAF driver; when actually using a metric, it must be set to\n", + " | the names of the data columns that the metric will operate on. This can be a single string or a list.\n", + " | \n", + " | 'maps' is a list of any maps that the metric will need, accessed via slicePoint that is passed from the slicer.\n", + " | \n", + " | After inheriting from this base metric :\n", + " | * every metric object will have metricDtype (the type of data it calculates) set according to:\n", + " | -- kwarg (metricDtype='float', 'int', etc)\n", + " | -- 'float' (assumes float if not specified in kwarg)\n", + " | -- 'object' (if reduce functions are present and value not set in kwarg)\n", + " | * every metric object will have the data columns it requires added to the column registry\n", + " | (so the driver can know which columns to pull from the database)\n", + " | \n", + " | ----------------------------------------------------------------------\n", + " | Data descriptors inherited from lsst.sims.maf.metrics.baseMetric.BaseMetric:\n", + " | \n", + " | __dict__\n", + " | dictionary for instance variables (if defined)\n", + " | \n", + " | __weakref__\n", + " | list of weak references to the object (if defined)\n", + " | \n", + " | ----------------------------------------------------------------------\n", + " | Data and other attributes inherited from lsst.sims.maf.metrics.baseMetric.BaseMetric:\n", + " | \n", + " | __metaclass__ = \n", + " | \n", + " | colRegistry = \n", + " | \n", + " | registry = {'AveSlewFracMetric': \n", + " | \n", + " | colRegistry = \n", + " | \n", + " | registry = {'AveSlewFracMetric':