sourcefinder.config =================== .. py:module:: sourcefinder.config Attributes ---------- .. autoapisummary:: sourcefinder.config.T sourcefinder.config._compat_types sourcefinder.config._source_params sourcefinder.config._source_params_file sourcefinder.config._structuring_element Classes ------- .. autoapisummary:: sourcefinder.config.Conf sourcefinder.config.ExportSettings sourcefinder.config.ImgConf sourcefinder.config._Validate Functions --------- .. autoapisummary:: sourcefinder.config._is_dataclass sourcefinder.config.assert_t sourcefinder.config.normalize_none_values sourcefinder.config.read_conf sourcefinder.config.validate_nested sourcefinder.config.validate_types Module Contents --------------- .. py:class:: Conf .. py:attribute:: export :type: ExportSettings .. py:attribute:: image :type: ImgConf .. py:class:: ExportSettings Bases: :py:obj:`_Validate` Selection of output, related to detected sources and/or intermediate image processing products .. !! processed by numpydoc !! .. py:attribute:: csv :type: bool :value: False Generate CSV text file (e.g., for TopCat). .. !! processed by numpydoc !! .. py:attribute:: file_type :type: str :value: 'csv' Output file type (default: csv). .. !! processed by numpydoc !! .. py:attribute:: islands :type: bool :value: False Generate island maps. .. !! processed by numpydoc !! .. py:attribute:: output_dir :type: str :value: '.' Directory in which to write the output files. .. !! processed by numpydoc !! .. py:attribute:: pandas_df :type: bool :value: True If True, the measured and derived source parameters will be returned as a Pandas DataFrame. If false, they will be returned as a `utility.containers.ExtractionResults` object. .. !! processed by numpydoc !! .. py:attribute:: regions :type: bool :value: False Generate DS9 region file(s). .. !! processed by numpydoc !! .. py:attribute:: residuals :type: bool :value: False Generate residual maps. .. !! processed by numpydoc !! .. py:attribute:: rmsmap :type: bool :value: False Generate RMS map. .. !! processed by numpydoc !! .. py:attribute:: sigmap :type: bool :value: False Generate significance map. .. !! processed by numpydoc !! .. py:attribute:: skymodel :type: bool :value: False Generate sky model. .. !! processed by numpydoc !! .. py:attribute:: source_params :type: list[str] Collect all possible source parameters. .. !! processed by numpydoc !! .. py:attribute:: source_params_file :type: list[str] Source parameters to include in a file for storage. .. !! processed by numpydoc !! .. py:class:: ImgConf Bases: :py:obj:`_Validate` Configuration that should cover all the specifications for processing the image. .. !! processed by numpydoc !! .. py:attribute:: alpha :type: float :value: 0.01 FDR alpha value (float, default 0.01) that sets an upper limit on the fraction of pixels erroneously detected as source pixels, relative to all source pixels. This requirement should be met when averaged over a large ensemble of images, but problems were encountered with alpha as low as 0.001, see paragraph 3.6 of Spreeuw's thesis. .. !! processed by numpydoc !! .. py:attribute:: alpha_brightness1 :type: float :value: 1.5 First exponent for scaling errors in peak brightness, see equation 26 and paragraph 5.2.5 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_brightness2 :type: float :value: 1.5 Second exponent for scaling errors in peak brightness, see equation 26 and paragraph 5.2.5 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_maj1 :type: float :value: 2.5 First exponent for scaling errors along the fitted major axis, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_maj2 :type: float :value: 0.5 Second exponent for scaling errors along the fitted major axis, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_min1 :type: float :value: 0.5 First exponent for scaling errors along the fitted minor axis and for scaling errors in the position angle, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: alpha_min2 :type: float :value: 2.5 Second exponent for scaling errors along the fitted minor axis and for scaling errors in the position angle, see equation 26 and paragraph 5.2.3 of the NVSS paper and equation 41 and paragraph 3 of Condon's (1997) "Errors in Elliptical Gaussian Fits". .. !! processed by numpydoc !! .. py:attribute:: analysis_thr :type: float :value: 3.0 Analysis threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image. .. !! processed by numpydoc !! .. py:attribute:: back_size_x :type: int | None :value: None Subimage size for estimation of background node values (X direction). The nodes are centred on the subimages. .. !! processed by numpydoc !! .. py:attribute:: back_size_y :type: int | None :value: None Subimage size for estimation of background node values (Y direction). The nodes are centred on the subimages. .. !! processed by numpydoc !! .. py:attribute:: bmaj :type: float | None :value: None Set beam: Major axis of restoring beam (degrees). .. !! processed by numpydoc !! .. py:attribute:: bmin :type: float | None :value: None Set beam: Minor axis of restoring beam (degrees). .. !! processed by numpydoc !! .. py:attribute:: bpa :type: float | None :value: None Set beam: Restoring beam position angle (degrees). .. !! processed by numpydoc !! .. py:attribute:: clean_bias :type: float :value: 0.0 Clean bias to subtract from the peak brightnesses (Jy/beam), see parapagraph 5.2.5 and equation 34 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: clean_bias_error :type: float :value: 0.0 1-sigma uncertainty in clean bias (Jy/beam), see parapagraph 5.2.5 and equation 37 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: deblend_mincont :type: float :value: 0.005 Minimum flux density fraction (relative to the original, i.e. unblended, island) required for a subisland to be considered a valid deblended component. .. !! processed by numpydoc !! .. py:attribute:: deblend_nthresh :type: int :value: 0 Number of deblending subthresholds; 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: detection_image :type: str | None :value: None Path to detection map. PySE will identify sources and the positions of pixels which comprise them on the detection image, but then use the corresponding pixels on the target images to perform measurements. Of course, the detection image and the target image(s) must have the same pixel dimensions. Note that only a single detection image may be specified, and the same pixels are then used on all target images. Note further that this detection-image option is incompatible with --fdr .. !! processed by numpydoc !! .. py:attribute:: detection_thr :type: float :value: 10.0 Detection threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image. .. !! processed by numpydoc !! .. py:attribute:: eps_dec :type: float :value: 0.0 Calibration uncertainty in declination (degrees), see equation 27b of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: eps_ra :type: float :value: 0.0 Calibration uncertainty in right ascension (degrees), see equation 27a of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: ew_sys_err :type: float :value: 0.0 Systematic error in east-west direction, see paragraph 5.2.3 of the NVSS paper. Note that this parameter is currently not applied in PySE, because it should be considered a final step before entering source parameters in a catalog, i.e. it is simply returned to allow for systematic positional offset cf. the NVSS. Therefore, its unit (degrees, arcseconds) is up to the user. .. !! processed by numpydoc !! .. py:attribute:: fdr :type: bool :value: False Use False Detection Rate (FDR) algorithm for determining detection threshold. .. !! processed by numpydoc !! .. py:attribute:: ffbox :type: float :value: 3.0 When fitting to a fixed position, a square “box” of pixels is chosen around the requested position, and the optimization procedure allows the source position to vary within that box. The size of the box may be changed with this option. Note that this parameter is given in units of the major axis of the beam in pixels. .. !! processed by numpydoc !! .. py:attribute:: fixed_posns :type: str | None :value: None JSON __list__ of RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements). .. !! processed by numpydoc !! .. py:attribute:: fixed_posns_file :type: str | None :value: None Path to JSON file with RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements). .. !! processed by numpydoc !! .. py:attribute:: force_beam :type: bool :value: False Force source shape to align restoring beam shape (bmaj, bmin, bpa) for Gauss fits and vetorized source measurement, i.e. when vectorized=True (as of 2025-06-13: upcoming, issue #131). .. !! processed by numpydoc !! .. py:attribute:: frac_flux_cal_error :type: float :value: 0.0 Intensity-proportional calibration uncertainty, see paragraph 5.2.5 and equation 37 of the NVSS paper. .. !! processed by numpydoc !! .. py:attribute:: grid :type: int | None :value: 64 Background subimage size used as fallback for back_size_x and back_size_y. If both are not set, this implies back_size_x=backsize_y=grid, i.e. the subimages are squares. .. !! processed by numpydoc !! .. py:attribute:: interpolate_order :type: int :value: 1 Order of interpolation to use for the background mean and background standard deviation (rms) maps (e.g. 1 for linear) .. !! processed by numpydoc !! .. py:attribute:: margin :type: int :value: 0 Margin in pixels to ignore near the edge of the image, i.e. sources within this margin will not be detected. .. !! processed by numpydoc !! .. py:attribute:: median_filter :type: int :value: 0 Size of the median filter to apply to background and RMS grids prior to interpolating. This is used to discard outliers. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: mf_threshold :type: int :value: 0 Threshold (Jy/beam) used with the median filter if median_filter is non-zero. This is used to only discard outliers (i.e. extreme background mean or rms node values) beyond a certain threshold. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: nr_threads :type: int | None :value: None The number of threads used to parallelize Gaussian fits to detected sources. Note: this does not change numba's 'num threads' for parallel numba operations. .. !! processed by numpydoc !! .. py:attribute:: ns_sys_err :type: float :value: 0.0 Systematic error in north-south direction, see paragraph 5.2.3 of the NVSS paper. Note that this parameter is currently not applied in PySE, because it should be considered a final step before entering source parameters in a catalog, i.e. it is simply returned to allow for systematic positional offset cf. the NVSS. Therefore, its unit (degrees, arcseconds) is up to the user. .. !! processed by numpydoc !! .. py:attribute:: radius :type: float :value: 0.0 Radius in pixels (from image center) considered valid, i.e. sources beyond this radius will not be detected. .. !! processed by numpydoc !! .. py:attribute:: remove_edge_sources :type: bool :value: True When source pixels - with values above the analysis threshold - connect with the edge of a map or with masked pixels, do not measure the source properties. Consequently, the parameters of this source will not be returned. The idea here is that, when source pixels are adjacent to edges or masked pixels, we'll likely be missing some pixels and any source measurement will be compromised. .. !! processed by numpydoc !! .. py:attribute:: rms_filter :type: float :value: 0.001 Any interpolated background standard deviation (rms) value should be above this threshold times the median of all background standard deviation (rms) node values. This is used to avoid picking up sources towards the edges of the image where the values of the background rms map may be the result of poor interpolation, i.e. are the result of extrapolation rather than interpolation. Use 0 to disable. .. !! processed by numpydoc !! .. py:attribute:: structuring_element :type: list[list[int]] :value: [[1, 1, 1], [1, 1, 1], [1, 1, 1]] The "structuring element" defines island connectivity as in "4-connectivity" and "8-connectivity". These two are the only reasonable choices, since the structuring element must be centrosymmetric. The structuring element is applied in scipy.ndimage.label, so check its documentation for some background on its use. .. !! processed by numpydoc !! .. py:attribute:: vectorized :type: bool :value: True Measure sources in a vectorized way. Expect peak spectral brightnesses with a lower bias (downwards) than for Gaussian fits (also downwards), but with a higher bias (upwards for both) for the elliptical axes. .. !! processed by numpydoc !! .. py:class:: _Validate .. py:function:: _is_dataclass(_type: Type[T], /) -> bool Remove ``TypeGuard`` from is_dataclass. see: https://github.com/python/mypy/issues/14941 .. !! processed by numpydoc !! .. py:function:: assert_t(key: str, value, *types: type) Assert value is of one of the types ``key`` is the TOML configuration key the value is associated to. It is used to generate a meaningful error message. .. !! processed by numpydoc !! .. py:function:: normalize_none_values(val) .. py:function:: read_conf(path: str | pathlib.Path) .. py:function:: validate_nested(key: str, value, origin_t, args) Validate nested types allowed in TOML ``key`` is the TOML configuration key being validated. ``value`` should be of type ``origin_t[args]``. It is passed to this function separately to avoid recomputing the type again. When the type is a ``list``, the value is tested recursively. On recursive calls, the list index is appended to the key. For ``dict``-s, iterate over all key-value pairs and validated. .. !! processed by numpydoc !! .. py:function:: validate_types(key: str, value, type_: type) Validate types, dispatch on generic or POD types ``key`` is the TOML configuration key the value is associated to. It is used to generate a meaningful error message. .. !! processed by numpydoc !! .. py:data:: T .. py:data:: _compat_types :type: collections.defaultdict[type, set[type]] .. py:data:: _source_params .. py:data:: _source_params_file .. py:data:: _structuring_element :value: [[1, 1, 1], [1, 1, 1], [1, 1, 1]]