Flag meaning has changed! See release notes for v0.5.0.

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'Vicente Rodriguez-Gomez'
 
 # The full version, including alpha/beta/rc tags
-release = '0.4.1'
+release = '0.5.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -58,6 +58,8 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+## Uncomment to allow errors in the tutorial notebook:
+#nbsphinx_allow_errors = True
 
 # -- Options for HTML output -------------------------------------------------
 

docs/description.rst

@@ -10,7 +10,7 @@ A more detailed description of the input parameters and the measurements
 performed by statmorph can be found in the API reference, as well as in
 `Rodriguez-Gomez et al. (2019) <https://ui.adsabs.harvard.edu/abs/2019MNRAS.483.4140R>`_.
 We also refer the user to the
-`tutorial <http://nbviewer.jupyter.org/github/vrodgom/statmorph/blob/master/notebooks/tutorial.ipynb>`_,
+`tutorial <notebooks/tutorial.html>`_,
 which contains a more concrete (albeit simplified) usage example.
 
 Input
@@ -55,21 +55,36 @@ The output of the `source_morphology` function is a list of
 `SourceMorphology` objects, one for each labeled source, in which the
 different morphological measurements can be accessed as keys or attributes.
 
-Apart from the morphological parameters, statmorph also produces two
-different "bad measurement" flags (where values of 0 and 1 indicate good
-and bad measurements, respectively):
-
-1. ``flag`` : indicates a problem with the basic morphological measurements
-   (e.g., a discontinuous Gini segmentation map).
-2. ``flag_sersic`` : indicates if there was a problem during the
-   Sersic profile fitting. 
-
-In general, users should enforce ``flag == 0``, while ``flag_sersic == 0``
-should be applied only when actually interested in Sersic fits (which can
-fail for merging galaxies and other "irregular" objects).
+Apart from the morphological parameters, statmorph also returns two
+different quality flags:
+
+- ``flag`` : indicates the quality of the basic morphological measurements.
+  It can take one of the following values:
+
+  - 0 (good): there were no problems with the measurements.
+  - 1 (suspect): the Gini segmap is discontinuous (e.g., due to a secondary
+    source that was not properly labeled/masked) or the Gini and MID segmaps
+    are very different from each other (as determined by the
+    ``segmap_overlap_ratio`` keyword argument).
+  - 2 (bad): there were problems with the measurements (e.g., the asymmetry
+    minimizer tried to exit the image boundaries). However, most measurements
+    are attempted anyway and a non-null value (i.e., not -99) might be
+    returned for most measurements.
+  - 3 (n/a): not currently used.
+  - 4 (catastrophic): this value is returned when even the most basic
+    measurements would be futile (e.g., a source with a negative total flux).
+    This replaces the ``flag_catastrophic`` from earlier versions of statmorph.
+
+- ``flag_sersic`` : indicates if there was a problem during the
+  Sersic profile fitting: values of 0 and 1 indicate good
+  and bad fits, respectively.
+
+In general, users should enforce ``flag <= 1``, while ``flag_sersic == 0``
+should be used only when users are actually interested in Sersic fits
+(which can fail for merging galaxies and other "irregular" objects).
 
 In addition to the flags described above, the output should
-not be trusted when any of the measured distance scales (Petrosian radii,
-half-light radii, etc.) is smaller than the radius at half-maximum of the PSF,
+not be trusted when the smallest of the measured distance scales (``r20``)
+is smaller than the radius at half-maximum of the PSF,
 or when the signal-to-noise per pixel (``sn_per_pixel``) is lower than 2.5
 (`Lotz et al. 2006 <https://ui.adsabs.harvard.edu/abs/2006ApJ...636..592L>`_).

docs/notebooks/tutorial.ipynb

@@ -296,13 +296,13 @@
     "\n",
     "Other morphological measurements that are more general and more robust to noise, which are also calculated by statmorph, include the Gini-M20 (Lotz et al. 2004), CAS (Conselice 2003) and MID (Freeman et al. 2013) statistics, as well as the outer asymmetry (Wen et al. 2014) and shape asymmetry (Pawlik et al. 2016).\n",
     "\n",
-    "Also note that statmorph calculates two different \"bad measurement\" flags (where 0 means good measurement and 1 means bad):\n",
+    "Also note that statmorph returns two quality flags:\n",
     "\n",
-    "1. ``flag`` : indicates a problem with the basic morphological measurements.\n",
+    "1. ``flag`` : indicates the quality the basic morphological measurements, taking one of the following values: 0 (good), 1 (suspect), 2 (bad), or 4 (catastrophic). More details can be found [here](https://statmorph.readthedocs.io/en/latest/description.html#output).\n",
     "\n",
-    "2. ``flag_sersic`` : indicates if there was a problem/warning during the Sersic profile fitting.\n",
+    "2. ``flag_sersic`` : indicates if there was a problem/warning during the Sersic profile fitting: values of 0 and 1 indicate good and bad fits, respectively.\n",
     "\n",
-    "In general, ``flag==0`` should always be enforced, while ``flag_sersic==0`` should only be used when interested in Sersic fits (which might fail for merging galaxies and other \"irregular\" objects)."
+    "In general, ``flag <= 1`` should always be enforced, while ``flag_sersic == 0`` should only be used when one is interested in Sersic fits (which might fail for merging galaxies and other \"irregular\" objects)."
    ]
   },
   {
@@ -395,7 +395,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.10.8"
   }
  },
  "nbformat": 4,

setup.py

@@ -11,7 +11,7 @@
 
 setup(
     name='statmorph',
-    version='0.4.1',
+    version='0.5.0',
     description='Non-parametric morphological diagnostics of galaxy images',
     long_description=long_description,
     url='https://github.com/vrodgom/statmorph',