Update MAF documentation

doc/source/index.rst

@@ -12,7 +12,8 @@ Contents:
    :maxdepth: 2
 
    overview.rst
-   metricsRun.rst
+   metricsRunAll.rst
+   metricsRunMoving.rst
    metricList.rst
    stackerList.rst
    modules.rst

doc/source/metricList.rst

@@ -24,8 +24,6 @@ Core LSST MAF metrics
  	 Count fraction of object period we could identify activity for an SSobject.
 - `ActivityOverTimeMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.ActivityOverTimeMetric>`_ 
  	 Count fraction of survey we could identify activity for an SSobject.
-- `AveGapMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.cadenceMetrics.AveGapMetric>`_ 
- 	 Calculate the gap between any consecutive observations, in hours, regardless of night boundaries.
 - `AveSlewFracMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.slewMetrics.AveSlewFracMetric>`_ 
  	 Base class for the metrics.
 - `BaseMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.baseMetric.BaseMetric>`_ 
@@ -97,7 +95,7 @@ Core LSST MAF metrics
 - `IdentityMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.summaryMetrics.IdentityMetric>`_ 
  	 Return the metric value itself .. this is primarily useful as a summary statistic for UniSlicer metrics.
 - `InterNightGapsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.cadenceMetrics.InterNightGapsMetric>`_ 
- 	 Calculate the gap between consecutive observations between nights, in days.
+ 	 Calculate the gap between consecutive observations in different nights, in days.
 - `IntraNightGapsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.cadenceMetrics.IntraNightGapsMetric>`_ 
  	 Calculate the gap between consecutive observations within a night, in hours.
 - `KnownObjectsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.KnownObjectsMetric>`_ 
@@ -192,6 +190,8 @@ Core LSST MAF metrics
  	 Calculate the standard deviation of a simData column slice.
 - `RobustRmsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.simpleMetrics.RobustRmsMetric>`_ 
  	 Use the inter-quartile range of the data to estimate the RMS.  
+- `SeasonLengthMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.cadenceMetrics.SeasonLengthMetric>`_ 
+ 	 Calculate the length of LSST seasons, in days.
 - `SlewContributionMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.slewMetrics.SlewContributionMetric>`_ 
  	 Base class for the metrics.
 - `StarDensityMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.starDensity.StarDensityMetric>`_ 
@@ -218,6 +218,8 @@ Core LSST MAF metrics
  	 Return the number of unique values divided by the total number of values.
 - `ValueAtHMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moSummaryMetrics.ValueAtHMetric>`_ 
  	 Return the metric value at a given H value.
+- `VisitGapMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.cadenceMetrics.VisitGapMetric>`_ 
+ 	 Calculate the gap between any consecutive observations, in hours, regardless of night boundaries.
 - `VisitGroupsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.visitGroupsMetric.VisitGroupsMetric>`_ 
  	 Count the number of visits per night within deltaTmin and deltaTmax.
 - `ZeropointMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.summaryMetrics.ZeropointMetric>`_ 
@@ -227,47 +229,3 @@ Core LSST MAF metrics
 - `fONv <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.summaryMetrics.fONv>`_ 
  	 Metrics based on a specified area, but returning NVISITS related to area:
 
-Contributed mafContrib metrics
-==============================
-
-- `AngularSpreadMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/angularSpread.py>`_ 
-  	 Compute the angular spread statistic which measures uniformity of a distribution angles accounting for 2pi periodicity.
-- `CampaignLengthMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/campaignLengthMetric.py>`_ 
-  	 The campaign length, in seasons. 
-- `GRBTransientMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/GRBTransientMetric.py>`_ 
-  	 Detections for on-axis GRB afterglows decaying as 
-- `GalaxyCountsMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/lssMetrics.py>`_ 
-  	 Estimate the number of galaxies expected at a particular coadded depth.
-- `MeanNightSeparationMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/meanNightSeparationMetric.py>`_ 
-  	 The mean separation between nights within a season, and then the mean over the campaign. 
-- `NumObsMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/numObsMetric.py>`_ 
-  	 Calculate the number of observations per data slice.
-- `PeriodDeviationMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/varMetrics.py>`_ 
-  	 Measure the percentage deviation of recovered periods for pure sine wave variability (in magnitude).
-- `PeriodicMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/PeriodicMetric.py>`_ 
-  	 From a set of observation times, uses code provided by Robert Siverd (LCOGT) to calculate the spectral window function.
-- `PeriodicStarMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/periodicStarMetric.py>`_ 
-  	 At each slicePoint, run a Monte Carlo simulation to see how well a periodic source can be fit.
-- `RelRmsMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/photPrecMetrics.py>`_ 
-  	 Relative scatter metric (RMS over median).
-- `SEDSNMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/photPrecMetrics.py>`_ 
-  	 Computes the S/Ns for a given SED.
-- `SNMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/photPrecMetrics.py>`_ 
-  	 Calculate the signal to noise metric in a given filter for an object of a given magnitude.
-- `SeasonLengthMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/seasonLengthMetric.py>`_ 
-  	 The mean season length, in months.
-- `StarCountMassMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/StarCountMassMetric.py>`_ 
-  	 Find the number of stars in a given field in the mass range fainter than magnitude 16 and bright enough to have noise less than 0.03 in a given band. M1 and M2 are the upper and lower limits of the mass range. 'band' is the band to be observed.
-- `StarCountMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/StarCountMetric.py>`_ 
-  	 Find the number of stars in a given field between D1 and D2 in parsecs.
-- `TdcMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/tdcMetric.py>`_ 
-  	 Combine campaign length, season length, and mean night speartion into a single metric.
-- `ThreshSEDSNMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/photPrecMetrics.py>`_ 
-  	 Computes the metric whether the S/N is bigger than the threshold in all the bands for a given SED
-- `TransientAsciiMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/transientAsciiMetric.py>`_ 
-  	 Based on the transientMetric, but uses an ascii input file and provides option to write out lightcurve.
-- `TripletBandMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/TripletMetric.py>`_ 
-  	 Find the number of 'triplets' of three images taken in the same band, based on user-selected minimum and maximum intervals (in hours),
-- `TripletMetric <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/TripletMetric.py>`_ 
-  	 Find the number of 'triplets' of three images taken in any band, based on user-selected minimum and maximum intervals (in hours),
-

doc/source/metricsRun.rst → doc/source/metricsRunAll.rst

@@ -1,11 +1,9 @@
-============================
+================================================
 Metrics in run_all.py script
-============================
+================================================
 The `run_all.py` script included in MAF runs a very large number of useful
 metrics covering metadata about observing history, survey performance, and
-those from the LSST SRD. Here we will list and summarize the metics included
-in this script.
-
+those from the LSST SRD. These metrics are listed below.
 
 
 `SRD metrics <lsst.sims.maf.batches.html#module-lsst.sims.maf.batches.srdBatch>`_

doc/source/metricsRunMoving.rst

@@ -0,0 +1,79 @@
+================================================
+Metrics in run_moving.py script
+================================================
+The `run_moving.py` script runs a number of solar system object oriented metrics,
+and requires an input SSO observation file to run (e.g. you must generate this
+observation file using something like sims_movingObjects `makeLSSTobs.py` first).
+
+
+`QuickDiscoveryBatch <lsst.sims.maf.batches.html#module-lsst.sims.maf.batches.quickDiscoveryBatch>`_
+=====================================================================================================
+
+    The QuickDiscoveryBatch is intended to provide a short but sweet set of discovery metric options.
+    It just runs the
+    `Discovery Metric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.DiscoveryMetric>`_
+    for SNR=5, with discovery criteria of 2 visits / night x 3 nights in a 15 (or 30)
+    day window, using whichever version of trailing losses (detection = dmagDetect or trailing =
+    dmagTrail) are specified. Please see lsst.sims.movingObjects for more information on detection vs
+    trailing losses.
+
+    This will also produce differential and cumulative completeness estimates for the input population,
+    both as a function of H magnitude and as a function of time.
+
+    Example of main output files:
+        baseline2018b_Discovery_2x3in15_MBAs_3_pairs_in_15_nights_SNReq5_detection_loss_MOOB.npz
+        baseline2018b_Discovery_2x3in30_MBAs_3_pairs_in_30_nights_SNReq5_detection_loss_MOOB.npz
+
+
+    with additional 'child' (or derived) metric output files of:
+        baseline2018b_Discovery_N_Chances_MBAs_3_pairs_in_15_nights_SNReq5_detection_loss_MOOB.npz
+        baseline2018b_Discovery_N_Chances_MBAs_3_pairs_in_30_nights_SNReq5_detection_loss_MOOB.npz
+        baseline2018b_Discovery_Time_MBAs_3_pairs_in_15_nights_SNReq5_detection_loss_MOOB.npz
+        baseline2018b_Discovery_Time_MBAs_3_pairs_in_30_nights_SNReq5_detection_loss_MOOB.npz
+
+    and summary metric files of:
+      xxxx
+
+
+`DiscoveryBatch <lsst.sims.maf.batches.html#module-lsst.sims.maf.batches.DiscoveryBatch>`_
+============================================================================================
+
+    The DiscoveryBatch runs many more discovery metric options, exploring a wide range of discovery criteria.
+    It runs the `Discovery Metric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.DiscoveryMetric>`_ looking for:
+        * Using a probablistic SNR limit, around SNR=5 (but with a gentle falloff around this value):
+            * 2 visits/night, 3 nights within a 15 day window
+            * 2 visits/night, 3 nights within a 12 day window
+            * 2 visits/night, 3 nights within a 20 day window
+            * 2 visits/night, 3 nights within a 25 day window
+            * 2 visits/night, 3 nights within a 30 day window
+            * 2 visits/night, 4 nights within a 20 day window
+            * 3 visits/night, 3 nights within a 30 day window
+            * 4 visits/night, 3 nights within a 30 day window
+        * Using a SNR=4 cutoff:
+            * 2 visits/night, 3 nights within a 15 day window
+            * 2 visits/night, 3 nights within a 30 day window
+        * Using a SNR=3 cutoff:
+            * 2 visits/night, 3 nights within a 15 day window
+        * Using a SNR=0 cutoff:
+            * 2 visits/night, 3 nights within a 15 day window
+        * Using a probabilistic SNR limit, around SNR=5 (with a gentle falloff around that value):
+            * Single detections
+            * Just a single pair
+
+    Then there are some other discovery metrics, using a probabilistic SNR cutoff (around SNR=5):
+        * Detection via trailing (two detections in a night)(`HighVelocityNightsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.HighVelocityNightsMetric>`_)
+        * 6 individual detections within a 60 day window (`MagicDiscoveryMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.MagicDiscoveryMetric>`_)
+
+
+`CharacterizationBatch <lsst.sims.maf.batches.html#module-lsst.sims.maf.batches.CharacterizationBatch>`_
+==========================================================================================================
+
+    The characterization batch runs a few metrics intended to shed light on characterization possibilities
+    with LSST. These metrics and their rationale are described in more depth in the COSEP.
+
+    * `NObsMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.NObsMetric>`_
+    * `ObsArcMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.ObsArcMetric>`_
+    * The `ActivityOverTimeMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.ActivityOverTimeMetric>`_ and the `ActivityOverPeriodMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.ActivityOverPeriodMetric>`_ are run with a variety of times/periods to identify the likelihood of detecting activity lasting various amounts of time.
+    * `LightcurveInversionMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.LightcurveInversionMetric>`_
+    * `ColorDeterminationMetric <lsst.sims.maf.metrics.html#lsst.sims.maf.metrics.moMetrics.ColorDeterminationMetric>`_
+

doc/source/stackerList.rst

@@ -129,51 +129,3 @@ Core LSST MAF stackers
 
 	 Adds columns: ['zenithDistance']
 
-Contributed mafContrib stackers
-===============================
-
-- `FermatSpiralDitherFieldPerNightStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither.
-
-	 Adds columns: []
-- `FermatSpiralDitherFieldPerVisitStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither.
-
-	 Adds columns: []
-- `FermatSpiralDitherPerNightStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither.
-
-	 Adds columns: []
-- `PentagonDiamondDitherFieldPerSeasonStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along a diamond circumscribed by a pentagon.
-
-	 Adds columns: []
-- `PentagonDiamondDitherPerSeasonStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along a diamond circumscribed by a pentagon.
-
-	 Adds columns: []
-- `PentagonDitherFieldPerSeasonStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along two pentagons, one inverted and inside the other.
-
-	 Adds columns: []
-- `PentagonDitherPerSeasonStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offset along two pentagons, one inverted and inside the other.
-
-	 Adds columns: []
-- `RepulsiveRandomDitherFieldPerNightStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, one dither offset 
-
-	 Adds columns: []
-- `RepulsiveRandomDitherFieldPerVisitStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, 
-
-	 Adds columns: []
-- `RepulsiveRandomDitherPerNightStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, one dither offset 
-
-	 Adds columns: []
-- `SpiralDitherPerSeasonStacker <http://github.com/lsst-nonproject/sims_maf_contrib/tree/master/mafContrib/newDitherStackers.py>`_ 
-  	 Offsets along a 10pt spiral. Sequential offset for all fields every seaso along a 10pt spiral.
-
-	 Adds columns: ['spiralDitherFieldPerVisitRa', 'spiralDitherFieldPerVisitDec']
-

python/lsst/sims/maf/batches/movingObjectsBatch.py

@@ -475,8 +475,8 @@ def _configure_child_bundles(parentBundle):
 
 def addMoCompletenessBundles(bdict, Hmark, outDir, resultsDb):
     """
-    Generate completeness bundles from all N_Chances child metrics of the (discovery) bundles in bdict,
-    and write completeness at Hmark to resultsDb, save bundle to disk.
+    Generate completeness bundles from all N_Chances and Time child metrics of the (discovery) bundles in
+    bdict, and write completeness at Hmark to resultsDb, save bundle to disk.
 
     Parameters
     ----------

python/lsst/sims/maf/runComparison/runComparison.py

@@ -359,7 +359,7 @@ def addSummaryStats(self, metricDict):
             parameters given in paramName like and a column for each of the
             dictionary keys in the metricDict. The resulting dataframe is
             indexed the name of the opsim runs.
-              index      metric1         metric2
+            index      metric1         metric2
             <run_123>    <metricValue1>  <metricValue2>
             <run_124>    <metricValue1>  <metricValue2>
         """