From 6c53de7263c12aed8c0818ceb54a6f53524ba6b1 Mon Sep 17 00:00:00 2001 From: "E. Madison Bray" Date: Thu, 19 Jun 2025 21:51:10 +0200 Subject: [PATCH 1/2] doc: a variety of minor typos and typographic inconsistencies fixed --- .../python/sourcextractor/config/argv.py | 10 +- .../sourcextractor/config/model_fitting.py | 17 +-- doc/src/Background.rst | 8 +- doc/src/Config.rst | 120 +++++++++--------- doc/src/Input.rst | 18 +-- doc/src/Measurements.rst | 16 +-- doc/src/Model.rst | 16 +-- doc/src/Output.rst | 8 +- doc/src/Photom.rst | 10 +- doc/src/TestData.rst | 2 +- doc/src/Weighting.rst | 2 +- doc/src/figures/detandmeas.svg | 2 +- 12 files changed, 115 insertions(+), 114 deletions(-) diff --git a/SEImplementation/python/sourcextractor/config/argv.py b/SEImplementation/python/sourcextractor/config/argv.py index 8333248a4..57faba016 100644 --- a/SEImplementation/python/sourcextractor/config/argv.py +++ b/SEImplementation/python/sourcextractor/config/argv.py @@ -34,10 +34,10 @@ class Arguments(object): key1 = 32. key2 = float - For the first case - a value -, if no value is passed via sys.argv, this will be the default. Otherwise, + For the first case--a value--if no value is passed via sys.argv, this will be the default. Otherwise, its type (float) will be used to cast the received value. - For the second case - a type -, if no value is passed via sys.argv, the parameter will default to None. + For the second case--a type -, if no value is passed via sys.argv, the parameter will default to None. Otherwise, the type will be used to cast the received value. Callables are also accepted. They should accept to be called with no parameters, returning the default, @@ -45,7 +45,7 @@ class Arguments(object): Values can be accessed later as attributes: - instance.key1 and instance.key2 + ``instance.key1`` and ``instance.key2`` Raises ------ @@ -128,7 +128,7 @@ def __repr__(self): class FileList(object): """ Helper class for receiving a globing pattern as a parameter, defining a list of files - - i.e. measurement images or PSFs. + --i.e. measurement images or PSFs. It is an iterable, and can be passed directly to load_fits_images. Parameters @@ -136,7 +136,7 @@ class FileList(object): value : str A file globing expression. i.e "*.psf", "band_[r|i|g]_*.fits" or similar. The result is always stored and returned in alphabetical order, so the order between two - file lists - i.e frame image and PSF - is consistent and a matching can be done easily between them. + file lists--i.e frame image and PSF--is consistent and a matching can be done easily between them. See Also -------- diff --git a/SEImplementation/python/sourcextractor/config/model_fitting.py b/SEImplementation/python/sourcextractor/config/model_fitting.py index 8b8a30413..627431056 100644 --- a/SEImplementation/python/sourcextractor/config/model_fitting.py +++ b/SEImplementation/python/sourcextractor/config/model_fitting.py @@ -422,7 +422,7 @@ class ModelBase(cpp.Id): """ Base class for all models. """ - + def get_params(self): return [] @@ -449,7 +449,7 @@ def __init__(self, x_coord, y_coord, flux): self.x_coord = x_coord if isinstance(x_coord, ParameterBase) else ConstantParameter(x_coord) self.y_coord = y_coord if isinstance(y_coord, ParameterBase) else ConstantParameter(y_coord) self.flux = flux if isinstance(flux, ParameterBase) else ConstantParameter(flux) - + def get_params(self): return [self.x_coord, self.y_coord, self.flux] @@ -530,7 +530,7 @@ def to_string(self, show_params=False): return 'ConstantModel[value={}]'.format(self.value) else: return 'ConstantModel[value={}]'.format(self.value.id) - + def get_params(self): return [self.value] @@ -826,6 +826,7 @@ def __init__(self, ra, dec): def pixel_to_world_coordinate(x, y): """ Transform an (X, Y) in pixel coordinates on the detection image to (RA, DEC) in world coordinates. + Parameters ---------- x : float @@ -1229,28 +1230,28 @@ def set_meta_iteration_stop(self, meta_iteration_stop): """ self.params_dict["meta_iteration_stop"] = meta_iteration_stop - + def set_window_type(self, window_type): """ Parameters ---------- - + window_type : WindowType specify the type of model fitting window """ if type(window_type) != WindowType: raise TypeError("Window type must be a WindowType enum value!") - + self.params_dict["window_type"] = window_type def set_ellipse_scale(self, ellipse_scale): """ Parameters ---------- - + ellipse_scale : double - specify scaling of elliptic footprints + specify scaling of elliptic footprints """ self.params_dict["ellipse_scale"] = ellipse_scale diff --git a/doc/src/Background.rst b/doc/src/Background.rst index 3ab90aee2..1afb1bf44 100644 --- a/doc/src/Background.rst +++ b/doc/src/Background.rst @@ -10,7 +10,7 @@ Modeling the background On linear detectors, the value measured at each pixel is the sum of a "background" signal and light coming from the sources of interest. To be able to detect the faintest objects and make accurate measurements, |SourceXtractor++| needs first computing a precise estimate of the background level at any position of the image: a *background map*. Strictly speaking, there should be one background map per source, that is, what would the image look like if that very source was missing. -However, one can start by assuming that most discrete sources do not overlap too severely — which is generally the case for high galactic latitude fields —, and that the background varies smoothly across the field. |SourceXtractor++|'s current background model is essentially the same as that of |SExtractor|_ :cite:`1996AAS_117_393B`. +However, one can start by assuming that most discrete sources do not overlap too severely — which is generally the case for high galactic latitude fields, and that the background varies smoothly across the field. |SourceXtractor++|'s current background model is essentially the same as that of |SExtractor|_ :cite:`1996AAS_117_393B`. Background estimation --------------------- @@ -32,7 +32,7 @@ Using simulated images, the expression above was found more accurate with clippe \mbox{Mode} = 3 \times \mbox{Median} - 2 \times \mbox{Mean}. -:numref:`fig_modevsmean` shows that the mode estimation in :eq:`sexbackmode` is considerably less affected by source crowding than a simple clipped mean :cite:`1981AJ_86_476J,1987AA_183_177I` but it is :math:`\approx 30\%` noisier. +:numref:`fig_modevsmean` shows that the mode estimation in :eq:`sexbackmode` is considerably less affected by source crowding than a simple clipped mean :cite:`1981AJ_86_476J,1987AA_183_177I` but it is :math:`\approx 30\%` noisier. Obviously :eq:`sexbackmode` is not valid for any distribution; |SourceXtractor++| falls back to a simple median for estimating the local background value if the mode and the median disagree by more than 30%. .. _fig_modevsmean: @@ -43,7 +43,7 @@ Obviously :eq:`sexbackmode` is not valid for any distribution; |SourceXtractor++ Simulations of 32×32 pixels background cells contamined by random Gaussian profiles. The true background lies at 0 ADUs. - While being a bit noisier, the clipped "mode" gives a more robust estimate than the clipped mean in crowded regions. + While being a bit noisier, the clipped "mode" gives a more robust estimate than the clipped mean in crowded regions. .. _chap_backfilter: @@ -75,7 +75,7 @@ The user has some control over background map filtering by specifying the size o The ``smoothing-box-size`` configuration parameter sets the box size in pixels. ``smoothing-box-size=3`` is the default and is sufficient in most cases. ``smoothing-box-size=1`` deactivates filtering. -Larger dimensions may occasionally be used to compensate for small background cell sizes, or in the presence of large image artifacts. +Larger dimensions may occasionally be used to compensate for small background cell sizes, or in the presence of large image artifacts. By default, the computed background maps are automatically subtracted from input images. However there are situations where subtracting a *constant* from the detection image may be more relevant, e.g., for images with strongly non-Gaussian background noise |pdf|_\ s). diff --git a/doc/src/Config.rst b/doc/src/Config.rst index d409a9285..19e0effbc 100644 --- a/doc/src/Config.rst +++ b/doc/src/Config.rst @@ -58,195 +58,195 @@ Please refer to the next sections for a detailed description of their meaning. ===================================== ================= ======================================= Option Default Use ===================================== ================= ======================================= -**Generic options** +**Generic options** ----------------------------------------------------------------------------------------------- ``version`` Print version string ``help`` Produce help message ``config-file`` `---` Name of a configuration file -``log-level`` ``INFO`` Log level: FATAL, ERROR, WARN, INFO +``log-level`` ``INFO`` Log level: FATAL, ERROR, WARN, INFO (default), DEBUG ``log-file`` `---` Name of a log file ``list-output-properties`` List the possible output properties for the given input parameters and exit -``property-column-mapping-all`` Show the columns created for each +``property-column-mapping-all`` Show the columns created for each property -``property-column-mapping`` Show the columns created for each +``property-column-mapping`` Show the columns created for each property, for the given configuration -``progress-min-interval`` 5 Minimal interval to wait before - printing a new log entry with the +``progress-min-interval`` 5 Minimal interval to wait before + printing a new log entry with the progress report ``progress-bar-disable`` Disable progress bar display -\ +\ ------------------------------------- ----------------- --------------------------------------- **Auto (Kron) photometry options** ----------------------------------------------------------------------------------------------- ``auto-kron-factor`` `2.5` Scale factor for AUTO (Kron) photometry -``auto-kron-min-radius`` `3.5` Minimum radius for AUTO (Kron) +``auto-kron-min-radius`` `3.5` Minimum radius for AUTO (Kron) photometry -\ +\ ------------------------------------- ----------------- --------------------------------------- **Background modelling** ----------------------------------------------------------------------------------------------- -``background-cell-size`` `64` Background mesh cell size to determine +``background-cell-size`` `64` Background mesh cell size to determine a value ``smoothing-box-size`` `3` Background median filter size -\ +\ ------------------------------------- ----------------- --------------------------------------- **Check images** ----------------------------------------------------------------------------------------------- -``check-image-model-fitting`` `---` Path to save the model fitting check +``check-image-model-fitting`` `---` Path to save the model fitting check image ``check-image-residual`` `---` Path to save the model fitting residual check image ``check-image-background`` `---` Path to save the background check image ``check-image-variance`` `---` Path to save the variance check image -``check-image-segmentation`` `---` Path to save the segmentation check +``check-image-segmentation`` `---` Path to save the segmentation check image ``check-image-partition`` `---` Path to save the partition check image ``check-image-grouping`` `---` Path to save the grouping check image ``check-image-filtered`` `---` Path to save the filtered check image -``check-image-thresholded`` `---` Path to save the thresholded check +``check-image-thresholded`` `---` Path to save the thresholded check image -``check-image-auto-aperture`` `---` Path to save the auto aperture check +``check-image-auto-aperture`` `---` Path to save the auto aperture check image ``check-image-aperture`` `---` Path to save the aperture check image ``check-image-moffat`` `---` Path to save the moffat check image ``check-image-psf`` `---` Path to save the PSF check image -\ +\ ------------------------------------- ----------------- --------------------------------------- **Cleaning** ----------------------------------------------------------------------------------------------- -``use-cleaning`` Enable the cleaning of sources - (remove false detections near bright +``use-cleaning`` Enable the cleaning of sources + (remove false detections near bright objects) ``cleaning-minarea`` `3` Minimum # of pixels above threshold -\ +\ ------------------------------------- ----------------- --------------------------------------- **Detection image** ----------------------------------------------------------------------------------------------- -``background-value`` `---` Background value to be subtracted from +``background-value`` `---` Background value to be subtracted from the detection image -``detection-threshold`` `1.5` Detection threshold above the +``detection-threshold`` `1.5` Detection threshold above the background -``segmentation-algorithm`` ``LUTZ`` Segmentation algorithm to be used. +``segmentation-algorithm`` ``LUTZ`` Segmentation algorithm to be used. Currently LUTZ is the only choice ``segmentation-disable-filtering`` Disables filtering ``segmentation-filter`` `---` Loads a filter -``detection-image`` `---` Path to a fits format image to be used +``detection-image`` `---` Path to a fits format image to be used as detection image. -``detection-image-gain`` `0` Detection image gain in e-/ADU (0 = +``detection-image-gain`` `0` Detection image gain in e-/ADU (0 = infinite gain) ``detection-image-flux-scale`` Detection image flux scale -``detection-image-saturation`` Detection image saturation level (0 = +``detection-image-saturation`` Detection image saturation level (0 = no saturation) -``detection-image-interpolation`` `1` Interpolate bad pixels in detection +``detection-image-interpolation`` `1` Interpolate bad pixels in detection image ``detection-image-interpolation-gap`` `5` Maximum number if pixels to interpolate over -\ +\ ------------------------------------- ----------------- --------------------------------------- **External flag options** ----------------------------------------------------------------------------------------------- -``flag-image-*`` `---` FITS file containing the external +``flag-image-*`` `---` FITS file containing the external flag -``flag-type-*`` `---` The combination type of the external +``flag-type-*`` `---` The combination type of the external flag (OR, AND, MIN, MAX, MOST) -\ +\ ------------------------------------- ----------------- --------------------------------------- **Extraction** ----------------------------------------------------------------------------------------------- ``detect-minarea`` `3` Minimum # of pixels above threshold -``use-attractors-partition`` Enables the use of attractors for +``use-attractors-partition`` Enables the use of attractors for partitioning -\ +\ ------------------------------------- ----------------- --------------------------------------- **Grouping** ----------------------------------------------------------------------------------------------- ``grouping-algorithm`` ``NONE`` Grouping algorithm to be used (NONE, MOFFAT) -``grouping-moffat-threshold`` `0.02` Threshold used for Moffat grouping. -\ +``grouping-moffat-threshold`` `0.02` Threshold used for Moffat grouping +\ ------------------------------------- ----------------- --------------------------------------- **Magnitude** ----------------------------------------------------------------------------------------------- ``magnitude-zeropoint`` `0` Magnitude zero point calibration -\ +\ ------------------------------------- ----------------- --------------------------------------- **Measurement config** ----------------------------------------------------------------------------------------------- ``python-config-file`` `---` Measurements Python configuration file -``python-arg`` `---` Parameters to pass to Python via +``python-arg`` `---` Parameters to pass to Python via `sys.argv` -\ +\ ------------------------------------- ----------------- --------------------------------------- **Memory usage** ----------------------------------------------------------------------------------------------- -``tile-memory-limit`` `512` Maximum memory used for image tiles +``tile-memory-limit`` `512` Maximum memory used for image tiles cache in megabytes ``tile-size`` `256` Image tiles size in pixels -\ +\ ------------------------------------- ----------------- --------------------------------------- **Model Fitting** ----------------------------------------------------------------------------------------------- -``model-fitting-iterations`` `1000` Maximum number of iterations allowed +``model-fitting-iterations`` `1000` Maximum number of iterations allowed for model fitting -\ +\ ------------------------------------- ----------------- --------------------------------------- **Multi-threading** ----------------------------------------------------------------------------------------------- ``thread-count`` `4` Number of worker threads (0=disable all multithreading) -\ +\ ------------------------------------- ----------------- --------------------------------------- **Multi-thresholding** ----------------------------------------------------------------------------------------------- ``partition-multithreshold`` Activate multithreshold partitioning ``partition-threshold-count`` `32` of thresholds -``partition-min-area`` `3` Minimum area in pixels to consider +``partition-min-area`` `3` Minimum area in pixels to consider partitioning ``partition-min-contrast`` `0.005` Minimum contrast for partitioning -\ +\ ------------------------------------- ----------------- --------------------------------------- **Output configuration** ----------------------------------------------------------------------------------------------- ``output-catalog-filename`` `---` The file to store the output catalog -``output-catalog-format`` ``FITS`` The format of the output catalog, one +``output-catalog-format`` ``FITS`` The format of the output catalog, one of ASCII or FITS -``output-properties`` ``PixelCentroid`` The output properties to add in the +``output-properties`` ``PixelCentroid`` The output properties to add in the output catalog -\ +\ ------------------------------------- ----------------- --------------------------------------- **Plugin configuration** ----------------------------------------------------------------------------------------------- -``plugin-directory`` `---` Path to a directory that contains the +``plugin-directory`` `---` Path to a directory that contains the plugins -``plugin`` `---` Defines a plugin to load (without file +``plugin`` `---` Defines a plugin to load (without file extension). Can be used multiple times -\ +\ ------------------------------------- ----------------- --------------------------------------- **Variable PSF** ----------------------------------------------------------------------------------------------- ``psf-filename`` `---` PSF image file (FITS format) -``psf-fwhm`` `---` Generate a Gaussian PSF with the given +``psf-fwhm`` `---` Generate a Gaussian PSF with the given full-width half-maximum (in pixels) -``psf-pixel-sampling`` `---` Generate a Gaussian PSF with the given +``psf-pixel-sampling`` `---` Generate a Gaussian PSF with the given pixel sampling step size -\ +\ ------------------------------------- ----------------- --------------------------------------- **Weight map** ----------------------------------------------------------------------------------------------- -``weight-image`` `---` Path to a FITS format image to be used +``weight-image`` `---` Path to a FITS format image to be used as weight image -``weight-absolute`` `0` Is the weight map provided as absolute +``weight-absolute`` `0` Is the weight map provided as absolute values or relative to background ``weight-type`` ``BACKGROUND`` Weight image type (BACKGROUND, RMS, VARIANCE, WEIGHT) ``weight-scaling`` `1` Weight map scaling factor -``weight-threshold`` `---` Threshold for pixels to be considered - bad pixels. In same units as weight - map. -``weight-usesymmetry`` `1` Use object symmetry to replace pixels - above the weight threshold for +``weight-threshold`` `---` Threshold for pixels to be considered + bad pixels. In same units as weight + map +``weight-usesymmetry`` `1` Use object symmetry to replace pixels + above the weight threshold for photometry ===================================== ================= ======================================= diff --git a/doc/src/Input.rst b/doc/src/Input.rst index 84f613c41..26eaf21ae 100644 --- a/doc/src/Input.rst +++ b/doc/src/Input.rst @@ -64,8 +64,8 @@ PSF models PSF models must be specified in the :ref:`model-fitting module `. |SourceXtractor++| accepts several |PSF|_ formats: -* using no PSF at all is specified with ``.., psf="nopsf",..`` in the configuration files (ASCII or python); -* a constant PSF can be given with a FITS image, and the keyword ``SAMPLING`` provides the sampling of the +* using no PSF at all is specified with ``.., psf="nopsf",..`` in the configuration files (ASCII or Python); +* a constant PSF can be given with a FITS image, and the keyword ``SAMPLING`` provides the sampling of the PSF image with respect to the corresponding measurement image (SAMPLING=0.5 means the 2 PSF pixels correspond to one pixel in the measurement image); * a variable PSF can be provided as FITS binary tables in the @@ -75,22 +75,22 @@ PSF models must be specified in the :ref:`model-fitting module `. |S * the first extension is a primary extension without data; * the second extension is an image extension named ``PSF_IMAGE`` containing, aligned in a grid (see Figure 2), the PSF data for the various regions in the measurement image. - The required keyword ```STMPSIZE``` gives the size of the PSF stamp, the keyword ```SAMPLING``` its sampling; + The required keyword ``STMPSIZE`` gives the size of the PSF stamp, the keyword ``SAMPLING`` its sampling; * the third extension is a table extension with the mandatory columns (see Figure 3): * ``X_CENTER`` : the central x-position of a grid PSF; * ``Y_CENTER`` : the central y-position of a grid PSF; * ``X`` : the x-position center of the area for the corresponding grid PSF; * ``Y`` : the x-position center of the area for the corresponding grid PSF; - * ``RA`` and ``DEC`` : the sky positions for ```X``` and ```Y``` ; + * ``RA`` and ``DEC`` : the sky positions for ``X`` and ``Y`` ; - * for a source at x_1,y_1 the relevant grid PSF is selected by minimizing the distances to ```X``` , ```Y``` , then the PSF stamp - is extracted using the values in the columns ``X_CENTER``` , ```Y_CENTER``` and the keyword ```STMPSIZE``` + * for a source at x_1,y_1 the relevant grid PSF is selected by minimizing the distances to ``X`` , ``Y`` , then the PSF stamp + is extracted using the values in the columns ``X_CENTER`` , ``Y_CENTER`` and the keyword ``STMPSIZE`` * an example for a stacked PSF file is available in the repository `SourceXtractor-litmus `_ (requires Git Large File Storage). One PSF model must be assigned for every measurement image!. In the ASCII configuration file it is possible to define a -Gaussian PSF with the parameters ```--psf-fwhm``` and ```--psf-pixel-sampling```. If defined, this Gaussian PSF is being used -for all measurement images that have not en explicit PSF defined in the oython configuration. +Gaussian PSF with the parameters ``--psf-fwhm`` and ``--psf-pixel-sampling``. If defined, this Gaussian PSF is being used +for all measurement images that do not have an explicit PSF defined in the Python configuration. .. _fig_psf_data: @@ -106,5 +106,5 @@ for all measurement images that have not en explicit PSF defined in the oython c :figwidth: 100% :align: center - The content of the table in a stacked PSF. + The content of the table in a stacked PSF. diff --git a/doc/src/Measurements.rst b/doc/src/Measurements.rst index 5bb9905b6..eaf89f971 100644 --- a/doc/src/Measurements.rst +++ b/doc/src/Measurements.rst @@ -36,7 +36,7 @@ They can be very sensitive to contamination by the light of neighbors, although They are close to optimum from the point-of-view of |SNR|, but they require accurate PSF models (one per image). |PSF|_ models can be computed using the |PSFEx|_ package. |SourceXtractor++| can fit mixtures of models to clumps of overlapping objects, which is generally effective at taking care of the contamination by the light of neighbors. -The main inconvenient of model-fitting is that it is much slower than aperture photometry. +The main inconvenience of model-fitting is that it is much slower than aperture photometry. .. _chap_configuration_script: @@ -44,7 +44,7 @@ The measurement configuration script ------------------------------------ Measurement settings, as well as :ref:`grouping procedures ` and catalog outputs must be defined in a configuration script that uses the `Python language `_: the measurement configuration script. -The script filename is set with the ``python-config-file`` configuration option. +The script filename is set with the ``python-config-file`` configuration option. Thanks to its flexibility, the Python language makes it possible to set up arbitrarily complex rules to finely control the measurement process. |SourceXtractor++|'s configuration library classes and functions must be imported at the beginning of the script: @@ -60,8 +60,8 @@ The same goes for other Python libraries that might be needed for the current co Measurement images ~~~~~~~~~~~~~~~~~~ -Measurement images are scientific images stored as |FITS|_ files and used only for measurements. -Every measurement image can be associated a |PSF| model (|PSFEx|'s :file:`.psf` file), and a weight map. +Measurement images are scientific images stored as |FITS|_ files and used only for measurements. +Every measurement image can be associated a |PSF| model (|PSFEx|\'s :file:`.psf` file), and a weight map. The :func:`~config.measurement_images.load_fits_image()` function creates a measurement image from a |FITS| image filename; for example: .. _chap_load_fits_image: @@ -131,8 +131,8 @@ It is possible to add images or another group to a pre-existing image group usin Splitting ^^^^^^^^^ -Now, within an image group one may want to create subgroups based on, e.g., band pass filters or epochs. -This is easily accomplished using the :meth:`~config.measurement_images.ImageGroup.split()` method. +Now, within an image group one may want to create subgroups based on, e.g., band pass filters or epochs. +This is easily accomplished using the :meth:`~config.measurement_images.ImageGroup.split()` method. Splitting may be done according to a |FITS| header keyword with the :class:`~config.measurement_images.ByKeyword()` callable. For instance, to generate subgroups each with a different filter (assuming all image headers contain the :param:`FILTER` keyword): @@ -141,8 +141,8 @@ For instance, to generate subgroups each with a different filter (assuming all i imagegroup.split(ByKeyword('FILTER')) :class:`~config.measurement_images.ByPattern()` also checks for a |FITS| header keyword, with the difference that a `regular expression `_ provided by the user is applied to the keyword value. -The first matching group acts as the grouping key, which means that a 'capturing group (within parentheses) '_ must be present in the regular expression. -For instance, the following command groups images by year of observation, ignoring the rest of the date: +The first matching group acts as the grouping key, which means that a `capturing group (within parentheses) `_ must be present in the regular expression. +For instance, the following command groups images by year of observation, ignoring the rest of the date: .. _bypattern: diff --git a/doc/src/Model.rst b/doc/src/Model.rst index 3f5d13a08..1818b4ada 100644 --- a/doc/src/Model.rst +++ b/doc/src/Model.rst @@ -102,7 +102,7 @@ or as a lambda expression, such as: size = FreeParameter(lambda o: 2.5 * o.get_radius(), range) Many model parameters are valid only over a restricted domain. -Fluxes, for instance, cannot be negative. +Fluxes, for instance, cannot be negative. The purpose of the range argument is to define the boundaries of the domain. In |SourceXtractor++|, this domain restriction is achieved through a change of variables, applied individually to every model parameter: @@ -121,7 +121,7 @@ The :class:`~config.model_fitting.Range()` construct is used to set :math:`q^\ma .. code-block:: python - range = Range((-1,1), RangeType.LINEAR) + fit_range = Range((-1,1), RangeType.LINEAR) The first argument is a `tuple `_ of 2 numbers specifying the lower and upper limits of the range. The range type defines :math:`f_j()`. @@ -131,7 +131,7 @@ Exponential ranges are better suited to strictly positive parameters with a larg .. code-block:: python - range = Range((0.01,100), RangeType.EXPONENTIAL) + fit_range = Range((0.01,100), RangeType.EXPONENTIAL) The relation between model and engine parameters is plotted :numref:`fig_rangetypes` for both examples. :numref:`change_of_variable_table` details the formula applied for currently supported range types. @@ -157,17 +157,17 @@ The relation between model and engine parameters is plotted :numref:`fig_rangety - :math:`Q_j = q_j` - :math:`q_j = Q_j` - | Position angles - | + | * - :param:`RangeType.LINEAR` - :math:`Q_j = \ln \frac{q_j - q^\mathsf{(min)}_j}{q^\mathsf{(max)}_j - q_j}` - :math:`q_j = \frac{q^\mathsf{(max)}_j - q^\mathsf{(min)}_j}{1 + \exp -Q_j} + q^\mathsf{(min)}_j` - - | positions - | Sersic index + - | Positions + | Sérsic index * - :param:`RangeType.EXPONENTIAL` - :math:`Q_j = \ln \frac{\ln q_j - \ln q^\mathsf{(min)}_j}{\ln q^\mathsf{(max)}_j - \ln q_j}` - :math:`q_j = q^\mathsf{(min)}_j \frac{\ln q^\mathsf{(max)}_j - \ln q^\mathsf{(min)}_j}{1 + \exp -Q_j}` - - | fluxes - | aspect ratios + - | Fluxes + | Aspect ratios In practice, we find this approach to ease convergence and to be much more reliable than a box constrained algorithm :cite:`Kanzow2004375`. diff --git a/doc/src/Output.rst b/doc/src/Output.rst index 7bef193dd..ae908eb44 100644 --- a/doc/src/Output.rst +++ b/doc/src/Output.rst @@ -10,9 +10,9 @@ Output Catalog ~~~~~~~ -|SourceXtractor++| writes out a catalog file with a filename set by the ``--output-catalog-filename`` option. Note that if no ``output-catalog-filename`` is set in the command line nor in the configuration file, then the catalog is printed in ASCII `to the standard output `_. +|SourceXtractor++| writes out a catalog file with a filename set by the ``--output-catalog-filename`` option. Note that if no ``--output-catalog-filename`` is set in the command line nor in the configuration file, then the catalog is printed in ASCII `to the standard output `_. -The ``--output-catalog-format`` option sets the format of the output catalog. Currently available options are `FITS` for a |FITS| binary table, and `ASCII` for an ASCII table. +The ``--output-catalog-format`` option sets the format of the output catalog. Currently available options are `FITS` for a |FITS| binary table, and `ASCII` for an ASCII table. Output properties ~~~~~~~~~~~~~~~~~ @@ -39,8 +39,8 @@ Additional files can be generated by |SourceXtractor++|, providing diagnostics a * ``check-image-residual``: model-fitting residuals * ``check-image-background``: bicubic-spline-interpolated background model * ``check-image-variance``: variance map -* ``check-image-segmentation``: map of detected objects after the segmentation stage -* ``check-image-partition``: map of detected objects after the partition stage +* ``check-image-segmentation``: map of detected objects after the segmentation stage +* ``check-image-partition``: map of detected objects after the partition stage * ``check-image-grouping``: map of detected objects after the grouping stage * ``check-image-filtered``: filtered copy of the detection image * ``check-image-thresholded``: filtered, thresholded copy of the detection image diff --git a/doc/src/Photom.rst b/doc/src/Photom.rst index 9348d4b3e..d3e8db668 100644 --- a/doc/src/Photom.rst +++ b/doc/src/Photom.rst @@ -38,11 +38,11 @@ Fixed-aperture flux .. _flux_auto_def: -The fixed aperture flux measurements are requested with ``output-properties=...,AperturePhotometry,...``. The diameter of the aperture is specified in the python configuration file (see above) with ``all_apertures.extend(add_aperture_photometry(img,))``. It is possible to give a vector with several diameters ``[diam_1, diam_2, diam_3, ...]``. +The fixed aperture flux measurements are requested with ``--output-properties=...,AperturePhotometry,...``. The diameter of the aperture is specified in the python configuration file (see above) with ``all_apertures.extend(add_aperture_photometry(img,))``. It is possible to give a vector with several diameters ``[diam_1, diam_2, diam_3, ...]``. -It is also necessary to append the aperture measurements to the output with a given column name such as ``add_output_column('aperture', all_apertures)``. The measurements have the dimension ``n x m`` for each object with ``n`` the number of measurement images and ``m`` the number of diameters. +It is also necessary to append the aperture measurements to the output with a given column name such as ``add_output_column('aperture', all_apertures)``. The measurements have the dimension ``n x m`` for each object with ``n`` the number of measurement images and ``m`` the number of diameters. -The fixed aperture checkimage is specified with ``check-image-aperture=`` and provides a visual impression of the apertures for each measurement image. +The fixed aperture checkimage is specified with ``--check-image-aperture=`` and provides a visual impression of the apertures for each measurement image. Automatic aperture flux ----------------------- @@ -53,9 +53,9 @@ Automatic aperture flux :cite:`1980ApJS_43_305K` and :cite:`1987AA_183_177I` have shown that for stars and galaxy profiles convolved with Gaussian seeing, :math:`\ge 90\%` of the flux is expected to lie inside a circular aperture of radius :math:`k r_{\rm Kron}` with :math:`k = 2`, almost independently of the magnitude. Experiments have shown :cite:`1996AAS_117_393B` that this conclusion remains unchanged if one replaces the circular aperture with the "Kron elliptical aperture" :math:`{\cal K}` with reduced pseudo-radius :math:`k r_{\rm Kron}`. -Automatic aperture flux measurements are requested with ``output-properties=...,AutoPhotometry,...``. The scale factor :math:`k` for the Kron radius :math:`r_{\rm Kron}` and the minimal Kron radius :math:`r_{\rm Kron, min}` can be adjusted with the parameters ``auto-kron-factor=`` and ``auto-kron-min-radius=``, respectively. The measurements have the dimension ``n`` for each object with ``n`` the number of measurement images. +Automatic aperture flux measurements are requested with ``--output-properties=...,AutoPhotometry,...``. The scale factor :math:`k` for the Kron radius :math:`r_{\rm Kron}` and the minimal Kron radius :math:`r_{\rm Kron, min}` can be adjusted with the parameters ``--auto-kron-factor=`` and ``--auto-kron-min-radius=``, respectively. The measurements have the dimension ``n`` for each object with ``n`` the number of measurement images. -The automatic aperture checkimage is specified with ``check-image-auto-aperture=`` and provides a visual impression of the automatic apertures for each measurement image. +The automatic aperture checkimage is specified with ``--check-image-auto-aperture=`` and provides a visual impression of the automatic apertures for each measurement image. .. _background_def: diff --git a/doc/src/TestData.rst b/doc/src/TestData.rst index af496fb1a..18ea2b850 100644 --- a/doc/src/TestData.rst +++ b/doc/src/TestData.rst @@ -12,7 +12,7 @@ Test Data Set :keywords: test data -A test data set for |SourceXtractor++| covering various data reduction scenarios was developed for the `ADASS XXXII Conference `_. +A test data set for |SourceXtractor++| covering various data reduction scenarios was developed for the `ADASS XXXII Conference `_. The proceedings contribution is available as a `pre-print `_. The test data set includes the input data, all relevant configuration files, the |SourceXtractor++| commands and the expected output results for a reference and is available for download `here `_. The data set is organized in a series of exercises diff --git a/doc/src/Weighting.rst b/doc/src/Weighting.rst index 2879e6ee4..e71be6b3e 100644 --- a/doc/src/Weighting.rst +++ b/doc/src/Weighting.rst @@ -24,7 +24,7 @@ Effect of weighting Weight-maps modify the working of |SourceXtractor++| in the several ways: - The detection threshold :math:`t` above the local sky background in the detection image is adjusted for each pixel :math:`i` with variance :math:`\sigma^2_i`: :math:`t_i=`\ ``detection-threshold``\ :math:`\times\sqrt{\sigma^2_i}`, where ``detection-threshold`` is expressed in units of standard deviations of the background noise. - Pixels having a variance *above* the threshold set with the ``--weight-threshold`` command line option are never detected. + Pixels having a variance *above* the threshold set with the ``--weight-threshold`` command-line option are never detected. This may result in splitting objects crossed by a group of bad pixels. Interpolation should be used to avoid this problem. If convolution filtering is applied for detection then the variance map is also convolved. diff --git a/doc/src/figures/detandmeas.svg b/doc/src/figures/detandmeas.svg index 560803f1b..805f212a3 100644 --- a/doc/src/figures/detandmeas.svg +++ b/doc/src/figures/detandmeas.svg @@ -1,3 +1,3 @@ -Measurement group #1Mesurement group #2Detection imageMeasurement images +Measurement group #1Measurement group #2Detection imageMeasurement images From e1deb4af5fd28d65eb12355fea23cf87cebc779a Mon Sep 17 00:00:00 2001 From: "E. Madison Bray" Date: Thu, 19 Jun 2025 21:59:49 +0200 Subject: [PATCH 2/2] doc: a few more minor fixes on the troubleshooting page --- doc/src/Troubles.rst | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/src/Troubles.rst b/doc/src/Troubles.rst index 47dcd3ebf..3ccd8ff95 100644 --- a/doc/src/Troubles.rst +++ b/doc/src/Troubles.rst @@ -4,7 +4,7 @@ .. index:: single: Troubleshooting - + Troubleshooting =============== @@ -19,31 +19,31 @@ If you unexpectedly find `NO SOURCES DETECTED` on your data, you should check yo .. code-block:: console Weight image: - --weight-image arg Path to a fits format image to be used + --weight-image arg Path to a fits format image to be used as weight image. --weight-type arg (=none) Weight image type [none|background|rms| variance|weight]. - --weight-threshold arg Threshold for pixels to be considered - bad pixels. In same units as weight + --weight-threshold arg Threshold for pixels to be considered + bad pixels. In same units as weight map. - --weight-absolute arg (=0) Is the weight map provided as absolute + --weight-absolute arg (=0) Is the weight map provided as absolute values or relative to background. --weight-scaling arg (=1) Weight map scaling factor. -What can happen is that :index:`inconsistent` parameters are provided for `--weight-image`, `--weight-type` -and `--weight-threshold`. The `weight-threshold` is adjusted to the `weight-type`. This means that for the -`rms` and `variance` types one wants to mask out large values in the `weight-image` by providing a large `weight-threshold`. -but for the `weight` type the low values should be masked out with a small `weight-threshold`. Mixing this up +What can happen is that :index:`inconsistent` parameters are provided for ``--weight-image``, ``--weight-type`` +and ``--weight-threshold``. The ``--weight-threshold`` is adjusted to the ``--weight-type``. This means that for the +``rms`` and ``variance`` types one wants to mask out large values in the ``--weight-image`` by providing a large ``--weight-threshold``. +but for the ``weight`` type the low values should be masked out with a small ``--weight-threshold```. Mixing this up will result in all pixels in the detection image being masked out and no sources detected. -With `weight-scaling` one provides a scaling factor for the entire weight image. For instance `--weight-scaling=0` +With ``--weight-scaling`` one provides a scaling factor for the entire weight image. For instance ``--weight-scaling=0`` masks out all pixels in the detection image and an inappropriate value may lower the SNR in the detection image to the point that no sources can be found. -The safest way to find objetcs is indeed using `--weight-type=background` which determines the -noise amplitude and therefore the entire SNR for the detection directly from the detection image. With a `--weight-image` -and the correct `--weight-type` (the defaults for `--weight-type` are set to mask out nothing), -`--weight-absolute arg=0` switches on automatic scaling of the `weight-image` with the median rms determined from the detection +The safest way to find objects is indeed using ``--weight-type=background`` which determines the +noise amplitude and therefore the entire SNR for the detection directly from the detection image. With a ``--weight-image`` +and the correct ``--weight-type`` (the defaults for ``--weight-type`` are set to mask out nothing), +`--weight-absolute arg=0` switches on automatic scaling of the ``--weight-image`` with the median RMS determined from the detection image, which usually brings the SNR for detection into a reliable range for detecting objects. @@ -54,13 +54,13 @@ Problems with temporary disk space ---------------------------------- |SourceXtractor++| attempts to store all intermediate products (images and so on) in memory. -If not enough memory is available or provided to |SourceXtractor++| (with the `tile-memory-limit` option), -disk space is put to contribution through temporary files. Depending on the situation (data size, available disk space) +If not enough memory is available or provided to |SourceXtractor++| (with the ``--tile-memory-limit`` option), +disk space is contributed through temporary files. Depending on the situation (data size, available disk space) there could be no space left for these temporary files, resulting in errors such as: .. code-block:: console - 2022-08-18T14:15:48CEST SourceXtractor ERROR : Failed to process the frame! + 2022-08-18T14:15:48CEST SourceXtractor ERROR : Failed to process the frame! Couldn't allocate space for new FITS file: /tmp/80122.1.euclid.test/_tmp_ml_segd1f9bb.fits status: 106 The solution is to extend the available temporary disk space. This can be done by extending the corresponding partition @@ -107,14 +107,14 @@ The log file then ends similar to this example: 2023-02-09T16:07:09CET Progress INFO : Measured: 7 / 7 (100.00%) 2023-02-09T16:07:09CET Progress INFO : Elapsed: 00:01:55 -A possible cause could be a race condition created by the concurrent calls to lower level libraries such as openMP or openBLAS. +A possible cause could be a race condition created by the concurrent calls to lower-level libraries such as OpenMP or OpenBLAS. This can happen in already multi-threaded applications such as |SourceXtractor++| -(see `here `_ for details). +(see `here `_ for details). -A confirmation that the dump is caused by a race condition in lower level libraries is if |SourceXtractor++| runs with multi-threading +A confirmation that the dump is caused by a race condition in lower-level libraries is if |SourceXtractor++| runs with multi-threading switched off (`--thread-count=0`), meaning that |SourceXtractor++| does not dump at least beyound a couple of dozen measurements in. -A solution is to switch off the multi-threading of all lower level libraries by setting the following environmental variables +A solution is to switch off the multi-threading of all lower-level libraries by setting the following environment variables *before the call* to |SourceXtractor++|: .. code-block:: console @@ -127,7 +127,7 @@ A solution is to switch off the multi-threading of all lower level libraries by export NTHREADS=1 sourcextractor++ --conf ... -This switches off the multi-threading in the lower level libraries and should prevent the race conditions. In version 0.20 we +This switches off the multi-threading in the lower-level libraries and should prevent the race conditions. In version 0.20 we are trying to make these settings inside |SourceXtractor++| (see `here `_), however we are not sure whether this will work in all situations and modes.