Merge pull request #425 from lsst/tickets/SP-1601

SP-1601: clean up rubin-sim developer guide issues

.github/workflows/build_docs.yaml

@@ -18,7 +18,7 @@ jobs:
       - uses: conda-incubator/setup-miniconda@v3
         with:
           auto-update-conda: true
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.11"
           miniforge-variant: Miniforge3
           channels: conda-forge,defaults
           use-mamba: true
@@ -28,8 +28,8 @@ jobs:
       - name: configure conda and install requirements
         shell: bash -l {0}
         run: |
-          mamba install --quiet --file=requirements.txt
           mamba install --quiet pip
+          mamba install --quiet --file=requirements.txt
           pip install "documenteer[guide]"
 
       - name: install rubin_sim

docs/data-download.rst

@@ -33,8 +33,8 @@ for more details on setting up $RUBIN_SIM_DATA_DIR (which is
 shared between ``rubin_scheduler``, ``rubin_sim`` and ``schedview``).
 
 Using either the default path to $RUBIN_SIM_DATA_DIR, or after setting it
-explicitly, first download the necessary data for `rubin_scheduler` and
-then add the (larger) data set for `rubin_sim`:
+explicitly, first download the necessary data for ``rubin_scheduler`` and
+then add the (larger) data set for ``rubin_sim``:
 
 .. code-block:: bash
 

docs/installation.rst

@@ -45,14 +45,14 @@ Create a conda environment for it:
 
 ::
 
- conda create --channel conda-forge --name rubin_sim --file requirements.txt python=3.11
+ conda create --channel conda-forge --name rubin-sim --file requirements.txt python=3.11
 
 
 If you want to run tests (please do), install the test requirements as well:
 
 ::
 
- conda activate rubin_scheduler
+ conda activate rubin-sim
  conda install -c conda-forge --file=test-requirements.txt
 
 

docs/introduction.rst

@@ -8,7 +8,7 @@ Introduction
 
 The `Legacy Survey of Space and Time <http://www.lsst.org>`_ (LSST)
 is anticipated to encompass around 2 million observations spanning a decade,
-averaging 800 visits per night. The `rubin_sim` package was built to help
+averaging 800 visits per night. The ``rubin_sim`` package was built to help
 understand the predicted performance of the LSST.
 
 The :ref:`Phot Utils<phot-utils>` module provides synthetic photometry
@@ -18,14 +18,14 @@ The :ref:`skybrightness<skybrightness>` module incorporates the ESO
 sky model, modified to match measured sky conditions at the LSST site,
 including an addition of a model for twilight skybrightness. This is used
 to generate the pre-calculated skybrightness data used in
-`rubin_scheduler<rubin-scheduler.lsst.io/skybrightness-pre.html>`_.
+`rubin_scheduler <rubin-scheduler.lsst.io/skybrightness-pre.html>`_.
 
 The :ref:`Moving Objects<moving-objects>` module provides a way to create
 synthetic observations of moving objects, based on how they would appear in
 pointing databases ("opsims") created by
 `rubin_scheduler <rubin-scheduler.lsst.io>`_.
 
-One of the major goals for `rubin_sim` is to enable efficient and
+One of the major goals for ``rubin_sim`` is to enable efficient and
 scientifically varied evaluation of the LSST survey strategy and progress,
 by providing a framework to enable these metrics to run in a
 standardized way on opsim outputs.

docs/skybrightness.rst

@@ -6,7 +6,7 @@
 Skybrightness
 #############
 
-The `rubin_sim.skybrightness` module generates
+The ``rubin_sim.skybrightness`` module generates
 predicted skybrightness values (in either magnitudes per
 square arcsecond for any LSST bandpass or
 as a SED over the relevant wavelengths).

requirements.txt

@@ -21,5 +21,7 @@ scikit-learn
 shapely
 skyfield
 skyproj
+tornado
+jinja2
 tqdm
 rubin-scheduler

rubin_sim/data/rs_download_data.py

@@ -8,7 +8,7 @@
 from rubin_scheduler.data import get_data_dir as gdd
 
 
-def get_data_dir():
+def get_data_dir() -> str:
     """Wraps rubin_scheduler.data.get_data_dir().
     Provided here for backwards compatibility.
 
@@ -20,7 +20,7 @@ def get_data_dir():
     return gdd()
 
 
-def get_baseline():
+def get_baseline() -> str:
     """Get the path to the baseline cadence simulation sqlite file.
 
     Returns
@@ -34,7 +34,7 @@ def get_baseline():
     return file
 
 
-def data_dict():
+def data_dict() -> dict:
     """
     Dictionary containing expected version information for rubin_sim_data
     data sets, for this version of rubin_sim.
@@ -44,9 +44,9 @@ def data_dict():
     file_dict : `dict`
         Data bucket filenames dictionary with keys:
         ``"name"``
-            Data bucket name (`str`).
+        Data bucket name (`str`).
         ``"version"``
-            Versioned file name (`str`).
+        Versioned file name (`str`).
     """
     # Note for developers:
     # to create tar files and follow any sym links, run: e.g.
@@ -65,7 +65,7 @@ def data_dict():
     return file_dict
 
 
-def rs_download_testing():
+def rs_download_testing() -> None:
     """Convenience function for github actions, to download only a subset
     of data.
 
@@ -89,7 +89,7 @@ def rs_download_testing():
     )
 
 
-def rs_download_data():
+def rs_download_data() -> None:
     """Utility to download necessary data for rubin_sim.
 
     Wrapper around rubin_scheduler.scheduler_download_data,

rubin_sim/maf/batches/ddf_batch.py

@@ -50,7 +50,8 @@ def ddfBatch(
     extra_info_label : `str`, optional
         Additional description information to add (alongside the extra_sql)
     old_coords : `bool`
-        Use the default locations for the DDFs from pre-July 2024. Default False.
+        Use the default locations for the DDFs from pre-July 2024.
+        Default False.
 
     Returns
     -------

rubin_sim/maf/batches/metadata_batch.py

@@ -39,15 +39,15 @@ def metadataBasics(
     Calculates this around the sky (HealpixSlicer),
     makes histograms of all visits (OneDSlicer),
     and calculates statistics on all visits (UniSlicer) for the quantity,
-     in all visits and per filter.
+    in all visits and per filter.
 
     Currently have a hack for HA & normairmass.
 
     Parameters
     ----------
     value : `str`
         The column name for the quantity to evaluate.
-         (column name in the database or created by a stacker).
+        (column name in the database or created by a stacker).
     colmap : `dict` or None, optional
         A dictionary with a mapping of column names.
     runName : `str`, optional

rubin_sim/maf/batches/moving_objects_batch.py

@@ -36,7 +36,9 @@
 
 
 def ss_population_defaults(objtype):
-    "Provide useful default ranges for H, based on objtype of population type."
+    """Provide useful default ranges for H,
+    based on objtype of population type.
+    """
     defaults = {}
     defaults["Vatira"] = {
         "h_range": [16, 28, 0.2],
@@ -135,6 +137,9 @@ def quick_discovery_batch(
     constraint=None,
     magtype="asteroid",
 ):
+    """A subset of discovery metrics, using only the default discovery
+    criteria of 3 pairs in 15 or 30 nights.
+    """
     if colmap is None:
         colmap = col_map_dict()
     bundleList = []
@@ -276,6 +281,9 @@ def discovery_batch(
     constraint=None,
     magtype="asteroid",
 ):
+    """A comprehensive set of discovery metrics, using a wide range
+    of discovery criteria.
+    """
     if colmap is None:
         colmap = col_map_dict()
     bundleList = []
@@ -648,8 +656,7 @@ def _configure_child_bundles(parentBundle):
 
 
 def run_completeness_summary(bdict, h_mark, times, out_dir, results_db):
-    """
-    Calculate completeness and create completeness bundles from all
+    """Calculate completeness and create completeness bundles from all
     N_Chances and Time (child) metrics of the (discovery) bundles in bdict,
     and write completeness at h_mark to results_db, save bundle to disk.
 
@@ -665,7 +672,7 @@ def run_completeness_summary(bdict, h_mark, times, out_dir, results_db):
         If not defined (None), then the h_mark from the plotdict from the
         metric bundle will be used if available.
         If None and h_mark not in plot_dict, then median of h_range values
-         will be used.
+        will be used.
     times : `np.ndarray`
         The times at which to calculate completeness (over time).
     out_dir : `str`

rubin_sim/maf/maf_contrib/kne_metrics.py

@@ -24,10 +24,8 @@ def get_kne_filename(inj_params_list=None):
         mass of the dynamical ejecta (mej_dyn), mass of the disk wind ejecta
         (mej_wind), semi opening angle of the cylindrically-symmetric ejecta
         fan ('phi'), and viewing angle ('theta'). For example
-        inj_params_list = [{'mej_dyn': 0.005,
-              'mej_wind': 0.050,
-              'phi': 30,
-              'theta': 25.8}]
+        inj_params_list =
+        [{'mej_dyn': 0.005, 'mej_wind': 0.050, 'phi': 30, 'theta': 25.8}]
     """
     # Get files, model grid developed by M. Bulla
     datadir = get_data_dir()
@@ -162,6 +160,7 @@ def __init__(
         self.output_lc = output_lc
 
         self.lightcurves = KnLc(file_list=file_list)
+
         self.mjd0 = mjd0
 
         dust_properties = DustValues()

rubin_sim/maf/maf_contrib/presto_color_kne_pop_metric.py

@@ -81,6 +81,7 @@ def generate_presto_pop_slicer(
 ):
     """Generate a population of KNe events, and put the info about them
     into a UserPointSlicer object
+
     Parameters
     ----------
     skyregion : `str`
@@ -100,6 +101,10 @@ def generate_presto_pop_slicer(
         Minimum luminosity distance (Mpc)
     d_max : `float` or `int`
         Maximum luminosity distance (Mpc)
+
+    Returns
+    -------
+    kne_slicer : `~.maf.UserPointsSlicer`
     """
 
     def rndm(a, b, g, size=1):
@@ -182,6 +187,7 @@ def __init__(
         self.skyregion = skyregion
         # read in file as light curve object;
         self.lightcurves = KnLc(file_list=file_list)
+
         self.mjd0 = mjd0
 
         dust_properties = DustValues()
@@ -190,6 +196,9 @@ def __init__(
         cols = [self.mjd_col, self.m5_col, self.filter_col, self.night_col]
         super().__init__(col=cols, units="Detected, 0 or 1", metric_name=metric_name, maps=maps, **kwargs)
 
+        # Unused ..
+        self.pts_needed = pts_needed
+
     def _presto_color_detect(self, around_peak, filters):
         """Detection criteria of presto cadence:
         at least three detections at two filters;

rubin_sim/maf/maps/galactic_plane_priority_maps.py

@@ -18,7 +18,8 @@
 
 def gp_priority_map_components_to_keys(filtername, science_map):
     """A convenience function to help keep the map key
-    formats in sync in various places"""
+    formats in sync in various places.
+    """
     return f"galplane_priority_{science_map}:{filtername}"
 
 
@@ -71,7 +72,6 @@ def galplane_priority_map(
         Use the priority_GalPlane_footprint_alt_map_data_{ugrizysum}.fits
         files instead of the default
         priority_galPlane_footprint_map_data_{ugrizysum}.fits files.
-         Default False.
     """
     # This is a function that will read the galactic plane priority map data
     # and hold onto it indefinitely

rubin_sim/maf/metrics/color_slope_metrics.py

@@ -67,7 +67,8 @@ def __call__(self, data_slice):
 
 class ColorSlopeMetric(BaseMetric):
     """How many times do we get a color and slope in a night
-    A proxie metric for seeing how many times
+
+    A proxy metric for seeing how many times
     there would be the possibility of identifying and
     classifying a transient.
 
@@ -81,7 +82,8 @@ class ColorSlopeMetric(BaseMetric):
         to still count as a color (hours). Default 1 hour.
     slope_length : `float`
         The length of time to demand observations in the
-        same filter be greater than (hours). Default 3 hours."""
+        same filter be greater than (hours). Default 3 hours.
+    """
 
     def __init__(
         self,
@@ -128,7 +130,7 @@ def run(self, data_slice, slice_point=None):
 class ColorSlope2NightMetric(ColorSlopeMetric):
     """Like ColorSlopeMetric, but span over 2 nights
 
-     Parameters
+    Parameters
     ----------
     mag : `dict`
         Dictionary with filternames as keys and minimum depth m5
@@ -138,7 +140,8 @@ class ColorSlope2NightMetric(ColorSlopeMetric):
         to still count as a color (hours). Default 1 hour.
     slope_length : `float`
         The length of time to demand observations in the
-        same filter be greater than (hours). Default 15 hours."""
+        same filter be greater than (hours). Default 15 hours.
+    """
 
     def __init__(
         self,

rubin_sim/maf/metrics/mo_metrics.py

@@ -1115,7 +1115,7 @@ class ColorAsteroidMetric(BaseMoMetric):
         1 = g and (r or i) and (z or y).
         i.e. obtain colors g-r or g-i PLUS g-z or g-y
         2 = Any 4 different filters (from grizy).
-         i.e. colors = g-r, r-i, i-z, OR r-i, i-z, z-y..
+        i.e. colors = g-r, r-i, i-z, OR r-i, i-z, z-y..
         3 = All 5 from grizy. i.e. colors g-r, r-i, i-z, z-y.
         4 = All 6 filters (ugrizy) -- best possible! add u-g.
 

rubin_sim/maf/plots/two_d_plotters.py

@@ -44,16 +44,16 @@ def __call__(self, metric_value, slicer, user_plot_dict, fig=None):
             The metric values from the bundle.
         slicer : `rubin_sim.maf.slicers.TwoDSlicer`
             The slicer.
-        user_plot_dict: `dict`
+        user_plot_dict : `dict`
             Dictionary of plot parameters set by user
             (overrides default values).
         fig : `matplotlib.figure.Figure`
             Matplotlib figure number to use. Default = None, starts new figure.
 
         Returns
         -------
-        fig : `matplotlib.figure.Figure
-           Figure with the plot.
+        fig : `matplotlib.figure.Figure`
+            Figure with the plot.
         """
         if "Healpix" in slicer.slicer_name:
             self.default_plot_dict["ylabel"] = "Healpix ID"
@@ -124,7 +124,7 @@ class VisitPairsHist(BasePlotter):
         The metric values from the bundle.
     slicer : `rubin_sim.maf.slicers.TwoDSlicer`
         The slicer.
-    user_plot_dict: `dict`
+    user_plot_dict : `dict`
         Dictionary of plot parameters set by user
         (overrides default values).
     fig : `matplotlib.figure.Figure`
@@ -133,7 +133,7 @@ class VisitPairsHist(BasePlotter):
     Returns
     -------
     fig : `matplotlib.figure.Figure`
-       Figure with the plot.
+        Figure with the plot.
     """
 
     def __init__(self):

rubin_sim/maf/run_comparison/archive.py

@@ -221,7 +221,9 @@ def get_metric_summaries(
     ----
     The entire summary statistic values for all of the runs and metrics can
     be downloaded from the default sources first, by simply calling
+
     .. code-block:: python
+
         summary = get_metric_summaries()
 
     Then, you can use `get_metric_summaries` to get a subset without