Merge branch 'develop' into im/add-tutorial-notebook

LSSTDESC · Jun 29, 2022 · 4a019d1 · 4a019d1
2 parents 4e7a3a1 + 097e197
commit 4a019d1
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 6 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -89,6 +89,7 @@ def __div__(self, other):
     "sphinx.ext.napoleon",
     "jupyter_sphinx",
     "sphinx_rtd_theme",
+    "sphinx.ext.autosectionlabel",
 ]
 
 autodoc_default_options = {
@@ -121,7 +122,7 @@ def __div__(self, other):
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -443,20 +443,21 @@ In order to circumvent the aforementioned caveat, BTK offers the possibility to
 More information about the COSMOS catalog
 ''''''''''''''''''''''''''''''''''''''''''''
 
-To go a little bit deeper about providing custom COSMOS data to BTK, let's review in more details in what the COSMOS data set and its BTK implementation consists of.
+To better understand how to provided custom COSMOS data to BTK, let's review in more detail the COSMOS dataset and its implementation in BTK.
 
-As seen above, the BTK ``CosmosCatalog`` is instantiated from two COSMOS catalogs. The first one contains all the necessary information to draw a galaxy (such as the paths to the galaxy and PSF stamps or the noise characteristics). The second one contains information about parameters fits to the galaxies (such as sersic parameters or bulge-to-disk ratios). You can refer to the README coming with the COSMOS data set `download <https://zenodo.org/record/3242143>`_ to check the column details of each catalog.
+As seen :ref:`above <Using COSMOS galaxies>`, the BTK ``CosmosCatalog`` is instantiated from two COSMOS catalog files. The first one contains all the necessary information to draw a real galaxy (such as the paths to the galaxy and PSF stamps or the noise characteristics). The second one contains information about parameters fits to the galaxies (such as sersic parameters or bulge-to-disk ratios). You can refer to the galsim `documentation <https://galsim-developers.github.io/GalSim/_build/html/real_gal.html>`_ for more details. You can refer to the `COSMOS_23.5_training_sample_readme.txt` and `COSMOS_25.2_training_sample_readme.txt` README files coming with the COSMOS data set `download <https://zenodo.org/record/3242143>`_ to check the column details of each catalog.
 
-Internally, BTK uses galsim to draw the galaxies. In particular, it instantiates a ``galsim.COSMOSCatalog``, that requires both catalogs. Yet, this object enables galsim to draw galaxies in two different modes that do not use the two catalogs in the same way: the parametric mode uses information of the second catalog while the 'real' mode uses information of the first catalog (and the actual galaxy and PSF stamps). You can refer to the galsim `documentation <https://galsim-developers.github.io/GalSim/_build/html/real_gal.html>`_ for more details. In BTK, we use only the 'real' drawing mode, so that the information of the second catalog is not necessary, even if the file must exist to instantiate the ``CosmosCatalog`` and ``galsim.COSMOSCatalog`` objects.
-However, BTK still retrieves the ``flux_radius`` information from this catalog, in order to compute an estimate of the size of each source and to measure deblending performance depending on the source sizes. Thus, the following conditions must be satisfied when providing custom COSMOS data to BTK:
+In BTK, both the 'parametric' and 'real' mode to draw galaxies can be used. When drawing 'real' galaxies, most of the information of the second catalog is not necessary, but the file must be provided to instantiate the ``CosmosCatalog`` and ``galsim.COSMOSCatalog`` objects. In practice, BTK uses the ``flux_radius`` column to compute an estimate of the size of each source used for performance evaluation measures, so the second catalog should contain at least this column.
+
+Custom COSMOS catalogs to draw 'real' galaxies should thus satisfy the following conditions:
 
 1. The second catalog should contain at least the ``flux_radius`` column,
 
 2. The first catalog should contain the same columns than the official COSMOS data release
 
 3. The galaxy and PSF stamps should be provided and accessible.
 
-4. (optional) One of the two catalogs can contain multiband magnitudes using the format just described.
+4. (optional) One of the two catalogs can contain multiband magnitudes using the format described :ref:`above <Using different magnitudes for each band>`.
 
 SCARLET implementation
 -----------------------