Issue/288/standardize naming

docs/source/citing.rst

@@ -2,32 +2,13 @@
 Citing RAIL
 ***********
 
-This code, while public on GitHub, has not yet been released by
-DESC and is still under active development.  Our release of v1.0 will
-be accompanied by a journal paper describing the development and
-validation of `RAIL`.
+RAIL is open source and may be used according to the terms of its `LICENSE <https://github.com/LSSTDESC/RAIL/blob/main/LICENSE>`_ `(BSD 3-Clause) <https://opensource.org/licenses/BSD-3-Clause>`_.
+If you make use of the ideas or software here in any publication, you must cite this repository <https://github.com/LSSTDESC/RAIL> as "LSST-DESC PZ WG (in prep)" with the `Zenodo DOI <https://doi.org/10.5281/zenodo.7017551>`_.
+Please consider also inviting the developers as co-authors on publications resulting from your use of RAIL by `making an issue <https://github.com/LSSTDESC/RAIL/issues/new/choose>`_.
 
-If you make use of the ideas or software here, please cite this
-repository ``https://github.com/LSSTDESC/RAIL``. You are welcome to
-re-use the code, which is open source and available under terms
-consistent with our `LICENSE
-<https://github.com/LSSTDESC/RAIL/blob/master/LICENSE>`_ (`BSD 3-Clause
-<https://opensource.org/licenses/BSD-3-Clause>`_).
+The following list provides the necessary references for external codes accessible through the RAIL ecosystem, which must be cited as follows if those methods are used in a publication:
 
-External contributors and DESC members wishing to use RAIL for non-DESC projects
-should consult with the Photometric Redshifts (PZ) Working Group conveners,
-ideally before the work has started, but definitely before any publication or
-posting of the work to the arXiv.
-
-***********************************
-Citing individual codes within RAIL
-***********************************
-
-Several of the codes included in RAIL are pre-existing codes written by external developers,
-if these codes are used in an analysis they should be cited individually in addition to the
-citation to RAIL.
-
-Code references:
+| Astropy: 
 
 | Bayesian Photometric Redshifts (BPZ/BPZ_lite):
 | `Benitez (2000) <https://ui.adsabs.harvard.edu/abs/2000ApJ...536..571B/abstract>`_
@@ -36,14 +17,28 @@ Code references:
 | Delight:
 | `Leistedt & Hogg (2017) <https://ui.adsabs.harvard.edu/abs/2017ApJ...838....5L/abstract>`_
 
+| DSPS:
+
 | FlexZBoost:
-| `Izbicki & Lee (2017)
-<https://projecteuclid.org/journals/electronic-journal-of-statistics/volume-11/issue-2/Converting-high-dimensional-regression-to-high-dimensional-conditional-density-estimation/10.1214/17-EJS1302.full>`_
+| `Izbicki & Lee (2017) <https://projecteuclid.org/journals/electronic-journal-of-statistics/volume-11/issue-2/Converting-high-dimensional-regression-to-high-dimensional-conditional-density-estimation/10.1214/17-EJS1302.full>`_
 | `Dalmasso et al (2020) <https://ui.adsabs.harvard.edu/abs/2020A%26C....3000362D/abstract>`_
 
+| FSPS:
+
+| GPz: 
+
 | PZFlowPDF:
-| J. F. Crenshaw (in prep)
+| J. F. Crenshaw et al (in prep)
 | `Zenodo link <https://zenodo.org/record/6369625#.Ylcpjy-cYW8>`_
 
+| Scikit-learn:
+
+| SOM(oclu):
+
 | trainZ:
 | `Schmidt, Malz et al (2020) <https://ui.adsabs.harvard.edu/abs/2020MNRAS.499.1587S/abstract>`_
+
+| varInference: 
+
+*fill in more of these*
+

docs/source/contributing.rst

@@ -2,14 +2,21 @@
 Contributing
 ************
 
+RAIL is developed publicly on GitHub and welcomes all interested developers, regardless of DESC membership or LSST data rights.
+The best way to get involved is to comment on `Issues <https://github.com/LSSTDESC/RAIL/issues?q=>`_ and `make Pull Requests <https://github.com/LSSTDESC/RAIL/compare>`_ for your contributions.
+
+Professional astronomers (including students!) based in the US, Chile, or a French IN2P3 institution are encouraged to `join the LSST-DESC <https://lsstdesc.org/pages/apply.html>`_ to gain access to the `\#desc-pz-rail <https://lsstc.slack.com/archives/CQGKM0WKD>`_ channel on the LSSTC Slack workspace.
+Those without data rights who wish to gain access to the Slack channel should `create an Issue <https://github.com/LSSTDESC/RAIL/issues/new/choose>`_ to request that the team leads initiate the process for adding a DESC External Collaborator.
+
 Where to contribute: RAIL packages
 ==================================
 
-Similar to the installation process, depending on how you want to contribute to RAIL you will be contributing to one or more of the RAIL packages.  Given the package structure we imagine three main use cases for contributions:
+Similar to the installation process, depending on how you want to contribute to RAIL, you will be contributing to one or more of the RAIL packages.  
+Given the package structure we imagine three main use cases for contributions:
 
-1. If you are contributing to the core code base, or developing an algorithm that has minimal dependencies, you will probably only be contributing to RAIL, and only need to install the source code for RAIL.
-2. If you are contritubing a new algorithm that does depend on a number of other packages beyond numpy, scipy and sklearn, you will probably be making a new rail_<algorithm> package, and eventually adding to the dependencies in rail_hub.
-3. If you are using existing algorithms to do studies and build analysis pipelines to do those studies, you will probably only be contriubting to rail_pipelines.
+1. To contribute to the core codebase, including algorithms with no special dependencies, install RAIL from source, indicate what you aim to do in an Issue, and follow the Contribution workflow below.
+2. To contribute a new algorithm or engine that depends on packages beyond numpy and scipy, you will probably be making a new rail_<algorithm> repository, and eventually rail_hub.
+3. To contribute analysis pipelines you built with RAIL Stages, clone `rail_pipelines` from source and follow the Contribution workflow instructions below.
 
 
 
@@ -21,8 +28,7 @@ When you identify something that should be done, `make an issue <https://github.
 for it.   
 We ask that if applicable and you are comfortable doing so, you add labels to the issue to
 mark what part of the code base it relates to, its priority level, and if it's well-suited to newcomers, as opposed to requiring more familiarity with the code or technical expertise.   
-Also, if you intend
-to work on the issue yourself, please assign the issue to yourself.
+
 
 To contribute, isolate `an issue <https://github.com/LSSTDESC/RAIL/issues>`_ to work on, assign yourself, and leave a comment on
 the issue's discussion page to let others know you're working on it. 
@@ -42,9 +48,12 @@ As regards `full coverage`, the automatic tests will require that 100% of the li
 
 When you're ready to merge your branch into the `main` branch,
 `make a pull request <https://github.com/LSSTDESC/RAIL/compare>`_, and request that other team members review it if you have any in mind, for example, those who have consulted on some of the work.
-Once the changes have been approved, you can merge and squash the pull request as well as close its corresponding issue by putting `closes #[#]` in the comment closing the pull request.
+Once the changes have been approved, 1. select "Squash and merge" on the approved pull request, 2. enter `closes #[#]` in the comment field to close the resolved issue, and 3. delete your branch using the button on the merged pull request.
 
-To review a pull request, it's a good idea to start by pulling the changes and running the unit tests (see above). If there are no problems with that, you can make suggestions for optional improvements (e.g. adding a one-line comment before a clever block of code or including a demonstration of new functionality in the example notebooks) or request necessary changes (e.g. including an exception for an edge case that will break the code or separating out code that's repeated in multiple places).
+To review a pull request, it's a good idea to start by pulling the changes and running the unit tests (see above). 
+Check the code for complete and accurate docstrings, sufficient comments, and to ensure any instances of `#pragma: no cover` (excluding the code from unit test coverage accounting) are extremely well-justified.
+Necessary changes to request may include, e.g. writing an exception for an edge case that will break the code, separating out code that's repeated in multiple places, etc.
+You may also make suggestions for optional improvements, such as adding a one-line comment before a clever block of code or including a demonstration of new functionality in the example notebooks.
 
 
 
@@ -129,11 +138,12 @@ Here is an example of a slightly more complicated `RailStage`.
 
 .. code-block:: python
 
-    class NaiveStack(PZSummarizer):
-        """Summarizer which simply histograms a point estimate
+    class NaiveStackSummarizer(PZSummarizer):
+        """
+        Summarizer taking an average of a qp.Ensemble of PDFs.
         """
 
-        name = 'NaiveStack'
+        name = 'NaiveStackSummarizer'
         config_options = PZSummarizer.config_options.copy()
         config_options.update(zmin=Param(float, 0.0, msg="The minimum redshift of the z grid"),
                               zmax=Param(float, 3.0, msg="The maximum redshift of the z grid"),

docs/source/index_body.rst

@@ -2,32 +2,23 @@
 RAIL: Redshift Assessment Infrastructure Layers
 ===============================================
 
-The LSST-DESC Redshift Assessment Infrastructure Layer (RAIL) code is a framework to perform photometric redshift (PZ) estimation and analysis for DESC.
+RAIL is a flexible software library providing tools to produce at-scale photometric redshift data products, including uncertainties and summary statistics, and stress-test them under realistically complex systematics.
 
-RAIL's purpose is to be the infrastructure enabling the PZ working group deliverables in `the LSST-DESC Science Roadmap (see Sec. 4.14) <https://lsstdesc.org/assets/pdf/docs/DESC_SRM_latest.pdf>`_,
-aiming to guide the selection and implementation of redshift estimators in DESC pipelines.
-RAIL differs from previous plans for PZ pipeline infrastructure in that it is broken into stages,
-each corresponding to a manageable unit of infrastructure advancement, a specific question to answer with that code, and a guaranteed publication opportunity.
-RAIL uses `qp <https://github.com/LSSTDESC/qp>`_ as a back-end for handling univariate probability density functions (PDFs) such as photo-z posteriors or :math:`n(z)` samples.
+RAIL serves as the infrastructure supporting many extragalactic applications of `the Legacy Survey of Space and Time (LSST) <https://www.lsst.org/>`_ on `the Vera C. Rubin Observatory<https://rubinobservatory.org/>`_, including Rubin-wide commissioning activities. 
+RAIL was initiated by the Photometric Redshifts (PZ) Working Group (WG) of the `LSST Dark Energy Science Collaboration (DESC) <https://lsstdesc.org/>`_ as a result of the lessons learned from the `Data Challenge 1 (DC1) experiment <https://academic.oup.com/mnras/article/499/2/1587/5905416>`_ to enable the PZ WG Deliverables in the `LSST-DESC Science Roadmap (see Sec. 5.18) <https://lsstdesc.org/assets/pdf/docs/DESC_SRM_latest.pdf>`_, aiming to guide the selection and implementation of redshift estimators in DESC analysis pipelines.
 
-The RAIL source code is publically available at https://github.com/LSSTDESC/RAIL.
+RAIL is developed and maintained by a diverse team comprising DESC Pipeline Scientists (PSs), international in-kind contributors, LSST Interdisciplinary Collaboration for Computing (LINCC) Frameworks software engineers, and other volunteers, but all are welcome to join the team regardless of LSST data rights. 
+To get involved, chime in on the issues in any of the RAIL repositories described in the Overview section.
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Getting Started
 
-   source/overview
    source/installation
-   source/contributing
    source/citing
-
-.. toctree::
-   :maxdepth: 1
-   :caption: RAIL Plans
-
-   source/immediateplans
-   source/futureplans
+   source/overview
+   source/contributing
 
 .. toctree::
    :maxdepth: 1