From 80722dc70f3d423b867df25ba5a34109b35ec3c8 Mon Sep 17 00:00:00 2001 From: Lynne Jones Date: Thu, 11 Oct 2018 15:15:38 -0700 Subject: [PATCH] Update MAF documentation --- doc/source/index.rst | 3 +- doc/source/metricList.rst | 52 ++---------- .../{metricsRun.rst => metricsRunAll.rst} | 8 +- doc/source/metricsRunMoving.rst | 79 +++++++++++++++++++ doc/source/stackerList.rst | 48 ----------- .../sims/maf/batches/movingObjectsBatch.py | 4 +- .../sims/maf/runComparison/runComparison.py | 2 +- 7 files changed, 92 insertions(+), 104 deletions(-) rename doc/source/{metricsRun.rst => metricsRunAll.rst} (98%) create mode 100644 doc/source/metricsRunMoving.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 5a95ffd6f..48a5be045 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/doc/source/metricList.rst b/doc/source/metricList.rst index eb95c3c48..aa4757f1d 100644 --- a/doc/source/metricList.rst +++ b/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 `_ Count fraction of survey we could identify activity for an SSobject. -- `AveGapMetric `_ - Calculate the gap between any consecutive observations, in hours, regardless of night boundaries. - `AveSlewFracMetric `_ Base class for the metrics. - `BaseMetric `_ @@ -97,7 +95,7 @@ Core LSST MAF metrics - `IdentityMetric `_ Return the metric value itself .. this is primarily useful as a summary statistic for UniSlicer metrics. - `InterNightGapsMetric `_ - Calculate the gap between consecutive observations between nights, in days. + Calculate the gap between consecutive observations in different nights, in days. - `IntraNightGapsMetric `_ Calculate the gap between consecutive observations within a night, in hours. - `KnownObjectsMetric `_ @@ -192,6 +190,8 @@ Core LSST MAF metrics Calculate the standard deviation of a simData column slice. - `RobustRmsMetric `_ Use the inter-quartile range of the data to estimate the RMS. +- `SeasonLengthMetric `_ + Calculate the length of LSST seasons, in days. - `SlewContributionMetric `_ Base class for the metrics. - `StarDensityMetric `_ @@ -218,6 +218,8 @@ Core LSST MAF metrics Return the number of unique values divided by the total number of values. - `ValueAtHMetric `_ Return the metric value at a given H value. +- `VisitGapMetric `_ + Calculate the gap between any consecutive observations, in hours, regardless of night boundaries. - `VisitGroupsMetric `_ Count the number of visits per night within deltaTmin and deltaTmax. - `ZeropointMetric `_ @@ -227,47 +229,3 @@ Core LSST MAF metrics - `fONv `_ Metrics based on a specified area, but returning NVISITS related to area: -Contributed mafContrib metrics -============================== - -- `AngularSpreadMetric `_ - Compute the angular spread statistic which measures uniformity of a distribution angles accounting for 2pi periodicity. -- `CampaignLengthMetric `_ - The campaign length, in seasons. -- `GRBTransientMetric `_ - Detections for on-axis GRB afterglows decaying as -- `GalaxyCountsMetric `_ - Estimate the number of galaxies expected at a particular coadded depth. -- `MeanNightSeparationMetric `_ - The mean separation between nights within a season, and then the mean over the campaign. -- `NumObsMetric `_ - Calculate the number of observations per data slice. -- `PeriodDeviationMetric `_ - Measure the percentage deviation of recovered periods for pure sine wave variability (in magnitude). -- `PeriodicMetric `_ - From a set of observation times, uses code provided by Robert Siverd (LCOGT) to calculate the spectral window function. -- `PeriodicStarMetric `_ - At each slicePoint, run a Monte Carlo simulation to see how well a periodic source can be fit. -- `RelRmsMetric `_ - Relative scatter metric (RMS over median). -- `SEDSNMetric `_ - Computes the S/Ns for a given SED. -- `SNMetric `_ - Calculate the signal to noise metric in a given filter for an object of a given magnitude. -- `SeasonLengthMetric `_ - The mean season length, in months. -- `StarCountMassMetric `_ - 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 `_ - Find the number of stars in a given field between D1 and D2 in parsecs. -- `TdcMetric `_ - Combine campaign length, season length, and mean night speartion into a single metric. -- `ThreshSEDSNMetric `_ - Computes the metric whether the S/N is bigger than the threshold in all the bands for a given SED -- `TransientAsciiMetric `_ - Based on the transientMetric, but uses an ascii input file and provides option to write out lightcurve. -- `TripletBandMetric `_ - Find the number of 'triplets' of three images taken in the same band, based on user-selected minimum and maximum intervals (in hours), -- `TripletMetric `_ - Find the number of 'triplets' of three images taken in any band, based on user-selected minimum and maximum intervals (in hours), - diff --git a/doc/source/metricsRun.rst b/doc/source/metricsRunAll.rst similarity index 98% rename from doc/source/metricsRun.rst rename to doc/source/metricsRunAll.rst index 5df83c89b..3a13a7737 100644 --- a/doc/source/metricsRun.rst +++ b/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 `_ diff --git a/doc/source/metricsRunMoving.rst b/doc/source/metricsRunMoving.rst new file mode 100644 index 000000000..4c0f4d809 --- /dev/null +++ b/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 `_ +===================================================================================================== + + The QuickDiscoveryBatch is intended to provide a short but sweet set of discovery metric options. + It just runs the + `Discovery Metric `_ + 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 `_ +============================================================================================ + + The DiscoveryBatch runs many more discovery metric options, exploring a wide range of discovery criteria. + It runs the `Discovery Metric `_ 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 `_) + * 6 individual detections within a 60 day window (`MagicDiscoveryMetric `_) + + +`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 `_ + * `ObsArcMetric `_ + * The `ActivityOverTimeMetric `_ and the `ActivityOverPeriodMetric `_ are run with a variety of times/periods to identify the likelihood of detecting activity lasting various amounts of time. + * `LightcurveInversionMetric `_ + * `ColorDeterminationMetric `_ + diff --git a/doc/source/stackerList.rst b/doc/source/stackerList.rst index 5b5df81cc..424df37d4 100644 --- a/doc/source/stackerList.rst +++ b/doc/source/stackerList.rst @@ -129,51 +129,3 @@ Core LSST MAF stackers Adds columns: ['zenithDistance'] -Contributed mafContrib stackers -=============================== - -- `FermatSpiralDitherFieldPerNightStacker `_ - Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither. - - Adds columns: [] -- `FermatSpiralDitherFieldPerVisitStacker `_ - Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither. - - Adds columns: [] -- `FermatSpiralDitherPerNightStacker `_ - Offset along a Fermat's spiral with numPoints, out to a maximum radius of maxDither. - - Adds columns: [] -- `PentagonDiamondDitherFieldPerSeasonStacker `_ - Offset along a diamond circumscribed by a pentagon. - - Adds columns: [] -- `PentagonDiamondDitherPerSeasonStacker `_ - Offset along a diamond circumscribed by a pentagon. - - Adds columns: [] -- `PentagonDitherFieldPerSeasonStacker `_ - Offset along two pentagons, one inverted and inside the other. - - Adds columns: [] -- `PentagonDitherPerSeasonStacker `_ - Offset along two pentagons, one inverted and inside the other. - - Adds columns: [] -- `RepulsiveRandomDitherFieldPerNightStacker `_ - Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, one dither offset - - Adds columns: [] -- `RepulsiveRandomDitherFieldPerVisitStacker `_ - Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, - - Adds columns: [] -- `RepulsiveRandomDitherPerNightStacker `_ - Repulsive-randomly dither the RA and Dec pointings up to maxDither degrees from center, one dither offset - - Adds columns: [] -- `SpiralDitherPerSeasonStacker `_ - Offsets along a 10pt spiral. Sequential offset for all fields every seaso along a 10pt spiral. - - Adds columns: ['spiralDitherFieldPerVisitRa', 'spiralDitherFieldPerVisitDec'] - diff --git a/python/lsst/sims/maf/batches/movingObjectsBatch.py b/python/lsst/sims/maf/batches/movingObjectsBatch.py index 7edd5e113..d0ff5882d 100644 --- a/python/lsst/sims/maf/batches/movingObjectsBatch.py +++ b/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 ---------- diff --git a/python/lsst/sims/maf/runComparison/runComparison.py b/python/lsst/sims/maf/runComparison/runComparison.py index 83af865be..99c8de748 100644 --- a/python/lsst/sims/maf/runComparison/runComparison.py +++ b/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 """