DM-38962: Update docs to new API

doc/lsst.analysis.tools/detailed-package-layout.rst

@@ -0,0 +1,6 @@
+.. _analysis-tools-detailed-package-layout:
+
+Detailed Package Layout
+=======================
+
+Eventually this page will have more details about the package layout and the ethos behind analysis tools.

doc/lsst.analysis.tools/faqs.rst

@@ -0,0 +1,50 @@
+.. _analysis-tools-faqs:
+
+FAQs
+====
+
+What Order are Configs Applied In?
+----------------------------------
+
+In analysis tools there are a number of ways to set config options which are applied in a certain order. If 
+you get this order wrong you might be suprised by what your action is doing. In order from first applied to
+last applied:
+
+1. The action defaults
+2. The config file in the obs package
+3. The camera specific config in the obs package
+4. The pipeline file configs
+5. The command line --config and --config-file options
+
+Due to this configs that are obs package specific should not be specified in the pipeline file because they 
+overwrite the obs specific configs. For example the bands option, if that is set in the pipeline file it will 
+overwrite the obs package which means that if you try to apply the same pipeline to HSC and DC2 data (for
+example) it will not work for both as each survey has different band coverage.
+
+How flag bands work
+-------------------
+
+The various flag selectors allow you to specify which bands the flags are applied in. If you want the selector
+to be applied in the bands that the plot is being made in then the flag config option should be set to [].
+
+Where is the line between python and YAML?
+------------------------------------------
+
+This can be a bit of a blurry line and in the end is up to the individual developer. A rough guideline is that 
+if the code is reusable either for variants of the original action or useful for other actions then it belongs
+in its own python class. If it is single use or a specific instance of a class then it should be done through
+the YAML config. An example of this is the photometric repeatability metrics. Here there is a base action
+called PhotometricRepeatability, defined in python, which is then configured for each individual application
+in the pipeline YAML. 
+
+.. code-block:: yaml
+
+   atools.modelPhotRepGalSn5to10: PhotometricRepeatability
+   atools.modelPhotRepGalSn5to10.fluxType: cModelFlux
+   atools.modelPhotRepGalSn5to10.process.filterActions.perGroupStdevFiltered.selectors.extendedness.op: gt
+   atools.modelPhotRepGalSn5to10.process.filterActions.perGroupStdevFiltered.selectors.sn.minimum: 5
+   atools.modelPhotRepGalSn5to10.process.filterActions.perGroupStdevFiltered.selectors.sn.maximum: 10
+
+The first line calls the action defined in python, after that the specific configuration is set in the
+pipeline YAML. This is a good balance between defining the entire action in YAML and having duplicate actions 
+defined in the python with only very mild differences.

doc/lsst.analysis.tools/getting-started.rst

@@ -51,89 +51,86 @@ Package Layout
 ==============
 There are a bunch of files in analysis_tools but we are going to focus on two directories, 
 ``python/lsst/analysis/tools/`` and ``pipelines``, which contain the python code and the 
-pipelines that run it respecitvely.
+pipelines that run it respecitvely. Below is a brief overview of the layout, for more details 
+please see the :doc:`package layout guide<detailed-package-layout>`.
 
 Pipelines
 ---------
 **visitQualityCore.yaml**
 
-| The core plots for analysing the quality of the visit level data. The core pipeline is run as standard as part of the regular reprocessing. The most helpful plots go into this pipeline.
+    The core plots for analysing the quality of the visit level data. The core pipeline is run as standard as part of the regular reprocessing. The most helpful plots go into this pipeline.
 
 **visitQualityExtended.yaml**
 
-| An extended pipeline of plots and metrics to study the visit level data. The extended pipeline is run when a problem comes up or we need to look deeper into the data quality. Useful plots that address specific issues but don't need to be run on a regular basis get added to this pipeline.
+    An extended pipeline of plots and metrics to study the visit level data. The extended pipeline is run when a problem comes up or we need to look deeper into the data quality. Useful plots that address specific issues but don't need to be run on a regular basis get added to this pipeline.
 
 **coaddQualityCore.yaml**
 
-| The core plots for analysing the quality of the coadd level data.
+    The core plots for analysing the quality of the coadd level data.
 
 **coaddQualityExtended.yaml**
 
-| The extended plots for analysing the coadd data.
+    The extended plots for analysing the coadd data.
 
 **matchedVisitQualityCore.yaml**
 
-| Plots and metrics that assess the repeatability of sources per tract by matching them between visits.
+    Plots and metrics that assess the repeatability of sources per tract by matching them between visits.
 
 **apCcdVisitQualityCore.yaml**
 
-| The core plots to assess the quality of the ccd visit dataset.
+    The core plots to assess the quality of the ccd visit dataset.
 
 python/lsst/analysis/tools
 --------------------------
 **actions**
 
-| This contains the actions that plot things and calculate things.
-| Check here before adding new actions to avoid duplication.
+    This contains the actions that plot things and calculate things.
+    Check here before adding new actions to avoid duplication.
 
     **scalar**
 
-    Contains a lot of useful actions that return scalar values.
-    E.g. median or sigma MAD.
+        Contains a lot of useful actions that return scalar values.
+        E.g. median or sigma MAD.
 
     **vector**
 
-    These actions run on vectors and return vectors.
-    E.g. the S/N selector which returns an array of bools.
+        These actions run on vectors and return vectors.
+        E.g. the S/N selector which returns an array of bools.
 
     **keyedData**
 
-    These actions are base classes for other actions. You 
-    shouldn't need to add stuff here. Use the scalar or 
-    vector actions.
+        These actions are base classes for other actions. You 
+        shouldn't need to add stuff here. Use the scalar or 
+        vector actions.
 
     **plots**
 
-    The plotting code lives in here. You shouldn't need to touch 
-    this unless you have to add a new plot type. Try to use one of 
-    the existing ones first rather than duplicating things.
+        The plotting code lives in here. You shouldn't need to touch 
+        this unless you have to add a new plot type. Try to use one of 
+        the existing ones first rather than duplicating things.
 
-**analysisMetrics**
+**atools**
 
-| Metric classes go in here. One off metrics and very simple metrics go into analysisMetrics.py. Sets of metrics go into their own file, i.e. psfResidualMetrics.py
+    Metrics and plots go in here. Similar plots and metrics should be grouped together into the same file, i.e. skyObject.py which contains various plots and metrics that use sky objects.
 
-**analysisParts**
-
-| Shared code between plots and metric goes in here. Try to have as much of this as possible so that nothing changes between the plots and their associated metrics.
-| I.e. shapeSizeFractionalDiff.py.
+**contexts**
 
-**analysisPlots**
+    Generic settings to be applied in a given circumstance. For example overrides that are specific to a coadd or visit level plot/metric such as the default flag selector which is different between coadd and visit analysis.
 
-| Plotting classes go in here. One off plots and very simple plots go into analysisPlots.py Sets of plots go into their own file, i.e. skyObject.py.
+**interfaces**
 
-**contexts**
-
-| Generic settings to be applied in a given circumstance. For example overrides that are specific to a coadd or visit level plot/metric such as the default flag selector which is different between coadd and visit analysis.
+    Interfaces are the framework level code which is used as a basis to build/interact with analysis tools package. You should not have to modify anything in here to be able to add new metrics or plots.
 
 **tasks**
 
-| Each different dataset type requires its own task to handle the reading of the inputs.
-| For example: objectTableTractAnalysis.py which handles the reading in of object tables.
+    Each different dataset type requires its own task to handle the reading of the inputs.
+    For example: objectTableTractAnalysis.py which handles the reading in of object tables.
 
 -------------------------
 
-A Simple Plotting Example
-=========================
+A Simple Plotting And Metric Example
+====================================
+
 The first example we are going to look at is a very simple one and then we can build 
 up from there. We're going to start by adapting an existing plot to our needs, we'll use a 
 sky plot to show the on sky distribution of the values of a column in the table.
@@ -183,6 +180,15 @@ the plot type as well.
            self.process.buildActions.zStars.magDiff.col1 = "{band}_ap12Flux"
            self.process.buildActions.zStars.magDiff.col2 = "{band}_psfFlux"
 
+           self.process.calculateActions.median = MedianAction()
+           self.process.calculateActions.median.vectorKey = "zStars"
+
+           self.process.calculateActions.mean = MeanAction()
+           self.process.calculateActions.mean.vectorKey = "zStars"
+
+           self.process.calculateActions.sigmaMad = SigmaMadAction()
+           self.process.calculateActions.sigmaMad.vectorKey = "xStars"
+
            self.produce = SkyPlot()
            self.produce.plotTypes = ["stars"]
            self.produce.plotName = "ap12-psf_{band}"
@@ -191,6 +197,18 @@ the plot type as well.
            self.produce.zAxisLabel = "Ap 12 - PSF [mag]"
            self.produce.plotOutlines = False
 
+           self.produce.metric.units = {
+               "median": "mmag",
+               "sigmaMad": "mmag",
+               "mean": "mmag"
+           }
+
+           self.produce.metric.newNames = {
+               "median": "{band}_ap12-psf_median",
+               "mean": "{band}_ap12-psf_mean",
+               "sigmaMad": "{band}_ap12-psf_sigmaMad",
+           }
+
 Let's look at what the bits do in more detail.
 
 .. code-block:: python
@@ -256,6 +274,22 @@ the ExtinctionCorrectedMagDiff, which calculates the magnitude from each of the
 col2 and then applies extinction corrections and subtracts them. If there is no extinction corrections for the
 data then it defaults to a straight difference between them.
 
+.. code-block:: python
+
+           self.process.calculateActions.median = MedianAction()
+           self.process.calculateActions.median.vectorKey = "zStars"
+
+           self.process.calculateActions.mean = MeanAction()
+           self.process.calculateActions.mean.vectorKey = "zStars"
+
+           self.process.calculateActions.sigmaMad = SigmaMadAction()
+           self.process.calculateActions.sigmaMad.vectorKey = "zStars"
+
+Next we want to set some metrics, we are going to use the pre calculated zStars values and then calculate
+their median, mean and sigma MAD as metric values. Later we will rename these so that the names are specific
+to each band and more informative when displayed.
+
+
 .. code-block:: python
 
            self.produce = SkyPlot()
@@ -270,9 +304,28 @@ This final section declares the plot type and adds labels and things. We declare
 plot, that plots only objects of type star. Next we give the plot a name that is informative for later
 identification and add axis labels. The final option specifies if we want patch outlines plotted. The plot 
 
+.. code-block:: python
+
+           self.produce.metric.units = {
+               "median": "mmag",
+               "sigmaMad": "mmag",
+               "mean": "mmag"
+           }
+
+We have to set some units for the metrics, these ones are in milli mags.
+
+.. code-block:: python
+
+           self.produce.metric.newNames = {
+               "median": "{band}_ap12-psf_median",
+               "mean": "{band}_ap12-psf_mean",
+               "sigmaMad": "{band}_ap12-psf_sigmaMad",
+           }
 
-This new class then needs to be added to a file in analysisPlots, one off and simple plots go into the
-analysisPlots file directly and the others are filed by category. For example all sky object related plots are
+Finally we name the metrics so that the names are specific per band and informative when re-read later.
+
+This new class then needs to be added to a file in atools, where they go into a file by category, if there
+isn't one that suits the tool you are making then start a new file. For example all sky object related plots are
 in the skyObjects.py file.
 
 Once we have added the class to the relevant file we can now run it from the command line. To do this we need
@@ -349,24 +402,17 @@ This example data id tells the processing that the instrument being used is HSC,
 in the g, r, i, z and y bands, that the skymap used is the hsc_rings_v1 map, that the tract is 9813 and that
 we only want to process data from patch 68 rather than all the data.
 
-Making A New Metric
--------------------
-Metrics work in a very similar way to plots and we won't go through another full example of them. They can be
-added to the same pipelines as the plots and the pipeline is run as detailled above. Metrics follow the same
-structure and have a prep, process and produce step. If a plot and metric are going to be made of the same
-quantity then the shared code should be factored out into a shared class in ``analysisParts``, see
-the `stelllar locus base class <https://github.com/lsst/analysis_tools/blob/main/python/lsst/analysis/tools/analysisParts/stellarLocus.py>`__ for examples on how to do this. The shared code
-is in ``analysisParts`` with very little code in ``analysisPlots.py`` and ``analysisMetrics.py``. The plots
-and metrics from these files are then called in `pipelines/coaddQualityCore.yaml <https://github.com/lsst/analysis_tools/blob/main/pipelines/coaddQualityCore.yaml>`__ and make a good reference
-for how to make new plots/metrics/combinations of plots and metrics.
-
-------------
+-----------
 
 Adding an Action
 ================
 
 Actions go in one of the sub folders of the actions directory depending on what type they are, this is covered in the package layout section. Before you add a new action check if it is already included before adding a duplicate. Sometimes it will probably be better to generalise an exisiting action rather than making a new one that is very similar to something that already exists. If the new action is long or specific to a given circumatance then add it to a new file, for example the ellipticity actions in `python/lsst/analysis/tools/actions/vector/ellipticity.py <https://github.com/lsst/analysis_tools/blob/main/python/lsst/analysis/tools/actions/vector/ellipticity.py>`__.
 
+The current actions that are available are detailed :doc:`here<action-types>`. Most common requests are already coded up and
+please try to reuse actions that already exist before making your own. Please also try to make actions as
+reusable as possible so that other people can also use them.
+
 Let's look at some examples of actions. The first one is a scalar action.
 
 .. code-block:: python
@@ -472,19 +518,7 @@ should be enough information that anyone can recreate the plot and access the fu
 investigation. See the other plots for more information on how to do this. Also please add doc strings to the
 plot and then add documentation here for other users so that they can easily see what already exists.
 
-------------------
-
-Plot Types
-==========
 The current plot types that are available are detailed :doc:`here<plot-types>`. Most common plots are
 already coded up and please try to reuse them before making your own. Before adding a new plot type please
 think about if some of the already coded ones can be adapted to your needs rather than making multiple plots
 that are basically identical.
-
----------------
-
-Actions Types
-=============
-The current actions that are available are detailed :doc:`here<action-types>`. Most common requests are already coded up and
-please try to reuse actions that already exist before making your own. Please also try to make actions as
-reusable as possible so that other people can also use them.

doc/lsst.analysis.tools/index.rst

@@ -25,13 +25,21 @@ For a tutorial on working with
    getting-started
    action-types
    plot-types
+   faqs
+   detailed-package-layout
 
 .. _lsst.analysis.tools-help:
 
 Need Help?
 ==========
+If you have access to slack, project members and in kind contributers should have and get stuck with ``analysis_tools`` then feel free to reach out to the ``#rubinobs-analysis-tools``
+channel on slack and hopefully someone will help you!
 
-If you have any questions regarding ``analysis_tools`` it is recommended that you post your question on `The Community Forum <https://community.lsst.org/>`_.
+Another way to get help is to write a post on `The Community Forum <https://community.lsst.org/>`_.
+
+A first place for more information is the :ref:`FAQs <analysis-tools-faqs>` page which
+contains some helpful hints. More will be added to this page over time, if you find something that you think
+should be added here then please do!
 
 .. _lsst.analysis_tools-pyapi:
 
@@ -52,6 +60,40 @@ Contributing
 The ``lsst.analysis.tools`` package is developed at
 `github.com/lsst/analysis_tools <https://github.com/lsst/analysis_tools>`_.
 
+<<<<<<< HEAD
 Jira issues relating to this package can be found using the
 `analysis_tools <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20analysis_tools>`_
 component.
+=======
+.. If there are topics related to developing this module (rather than using it), link to this from a toctree placed here.
+
+.. .. toctree::
+..    :maxdepth: 1
+
+.. .. _lsst.analysis.tools-scripts:
+
+.. Script reference
+.. ================
+
+.. .. TODO: Add an item to this toctree for each script reference topic in the scripts subdirectory.
+
+.. .. toctree::
+..    :maxdepth: 1
+
+.. .. _lsst.analysis.tools-pyapi:
+
+Python API reference
+====================
+
+.. NOTE: Skip the type definitions that cause the pipelines docs build to fail.
+.. automodapi:: lsst.analysis.tools
+   :no-main-docstr:
+   :no-inheritance-diagram:
+   :include-all-objects:
+.. automodapi:: lsst.analysis.tools.actions.plot
+   :no-inheritance-diagram:
+.. automodapi:: lsst.analysis.tools.actions.vector
+   :no-inheritance-diagram:
+.. automodapi:: lsst.analysis.tools.actions.scalar
+   :no-inheritance-diagram:
+>>>>>>> 2de19a1 (Add more pages to the docs)

doc/lsst.analysis.tools/plot-types.rst

@@ -9,7 +9,6 @@ can all be found on `GitHub <https://github.com/lsst/analysis_tools/blob/main/py
 
 .. automodapi:: lsst.analysis.tools.actions.plot
    :no-inherited-members:
-   :noindex:
    :skip: BarPanel
    :skip: DiaSkyPanel
    :skip: HistPanel