Command-line interface#

PySE image configuration options. These can override the values specified in the TOML config file.

usage: pyse [-h] [--config-file CONFIG_FILE] [--pdb] [--show-args] [-v]
            [--interpolate-order INTERPOLATE_ORDER]
            [--median-filter MEDIAN_FILTER] [--mf-threshold MF_THRESHOLD]
            [--rms-filter RMS_FILTER] [--deblend-mincont DEBLEND_MINCONT]
            [--structuring-element STRUCTURING_ELEMENT] [--vectorized]
            [--nr-threads NR_THREADS] [--margin MARGIN] [--radius RADIUS]
            [--back-size-x BACK_SIZE_X] [--back-size-y BACK_SIZE_Y]
            [--grid GRID] [--eps-ra EPS_RA] [--eps-dec EPS_DEC]
            [--detection-thr DETECTION_THR] [--analysis-thr ANALYSIS_THR]
            [--fdr] [--alpha ALPHA] [--deblend-nthresh DEBLEND_NTHRESH]
            [--bmaj BMAJ] [--bmin BMIN] [--bpa BPA] [--force-beam]
            [--detection-image DETECTION_IMAGE] [--fixed-posns FIXED_POSNS]
            [--fixed-posns-file FIXED_POSNS_FILE] [--ffbox FFBOX]
            [--ew-sys-err EW_SYS_ERR] [--ns-sys-err NS_SYS_ERR]
            [--output-dir OUTPUT_DIR] [--skymodel] [--csv] [--regions]
            [--rmsmap] [--sigmap] [--residuals] [--islands]
            [files ...]

Positional Arguments#

files: Image files for processing

General#

--config-file

TOML file containing input arguments to PySE. Overridden by command line arguments, but overrides built-in defaults from config.ImgConf and config.ExportSettings. This is especially convenient when swapping between configurations for the same project.

--pdb

Enter debug mode when the application crashes. Meant to be used for more comprehensive debugging.

Default: False

--show-args

View all arguments pyse will run with in the current configuration after aggregating the command-line arguments, config-file parameters and pyse defaults.

Default: False

-v, --version

show program’s version number and exit

Image parameters#

--interpolate-order

Order of interpolation - e.g. 1 for linear - to use to derive the background mean and background standard deviation (rms) maps from the corresponding background grid values. The nodes of the background grids are centred on the subimages of size back_size_x by back_size_y.

[default: 1]

--median-filter

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.

[default: 0]

--mf-threshold

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.

[default: 0]

--rms-filter

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.

[default: 0.001]

--deblend-mincont

Minimum flux density fraction (relative to the original, i.e. unblended, island) required for a subisland to be considered a valid deblended component.

[default: 0.005]

--structuring-element

The ‘structuring element’ defines island connectivity as in ‘4-connectivity’ and ‘8-connectivity’ as a Python-style nested list, e.g. ‘[[1,1,1], [1,1,1], [1,1,1]]’ for 8-connectivity and ‘[[0,1,0], [1, 1,1], [0,1,0]]’ for 4-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.

--vectorized

Measure sources using a vectorized implementation of the ‘tweaked moments’ method. Compared to Gaussian fitting, this approach is much faster and more suitable for large numbers of sources. Peak spectral brightnesses remain biased downward, but generally show a smaller negative bias than Gaussian fits. The derived elliptical source axes (major and minor) tend to be biased upward, typically more so than for Gaussian fits.

[default: True]

Default: False

--nr-threads

The number of threads used to parallelize Gaussian fits to detected sources. This integer sets ‘max_workers’ in ‘concurrent.futures.ThreadpoolExecutor’. Expect speedups when using a free-threading version of Python, but this integer is probably best set to 1 if you’re not. Note: this does not change numba’s ‘NUMBA_NUM_THREADS’ for the numerous parallel numba operations in PySE.

--margin

Margin in pixels to ignore near the edges of the image, i.e. sources within this margin will not be detected.

[default: 0]

--radius

Radius in pixels (from image center) considered valid, i.e. sources beyond this radius will not be detected.

[default: 0.0]

--back-size-x

Subimage size for estimation of background node values (X- direction). The nodes are centred on the subimages.

--back-size-y

Subimage size for estimation of background node values (Y- direction). The nodes are centred on the subimages.

--grid

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.

[default: 64]

--eps-ra

Calibration uncertainty in right ascension (degrees), see equation 27a of the NVSS paper.

[default: 0.0]

--eps-dec

Calibration uncertainty in declination (degrees), see equation 27b of the NVSS paper.

[default: 0.0]

--detection-thr

Detection threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image.

[default: 10.0]

--analysis-thr

Analysis threshold as multiple of the background standard deviation (rms) map, after the background mean values have been subtracted from the image. Island pixels above the analysis threshold are used for the measurement of the source. The analysis threshold must be lower than or equal to the detection threshold.

[default: 3.0]

--fdr

Use False Detection Rate (FDR) algorithm for determining the detection threshold.

[default: False]

Default: False

--alpha

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.

[default: 0.01]

--deblend-nthresh

Number of deblending subthresholds; 0 to disable.

[default: 0]

--bmaj

Major axis of restoring beam (degrees).

--bmin

Minor axis of restoring beam (degrees).

--bpa

Restoring beam position angle (degrees).

--force-beam

Force source shape to align restoring beam shape (bmaj, bmin, bpa) for Gaussian fits and vetorized source measurement, i.e. when vectorized=True.

[default: False]

Default: False

--detection-image

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

--fixed-posns

JSON __list__ of RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements).

--fixed-posns-file

Path to JSON file with RA, Dec pairs of coordinates to measure sources at (disables blind extraction and vectorized source measurements).

--ffbox

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.

[default: 3.0]

--ew-sys-err

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.

[default: 0.0]

--ns-sys-err

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.

[default: 0.0]

Export parameters#

--output-dir

--skymodel

Generate a sky model.

[default: False]

Default: False

--csv

Generate a CSV text file (e.g., for TopCat).

[default: False]

Default: False

--regions

Generate DS9 region file(s).

[default: False]

Default: False

--rmsmap

Generate map with the root-mean-square (RMS) of the background noise.

[default: False]

Default: False

--sigmap

Generate a significance map, i.e. the observational data - with mean background subtracted - divided by the RMS map.

[default: False]

Default: False

--residuals

Generate a residuals map, i.e. a map where the Gaussian reconstructions of all detected sources have been subtracted from the observational data, with mean background subtracted.

[default: False]

Default: False

--islands

Generate an islands map, i.e. a map with the Gaussian reconstructions of all detected sources.

[default: False]

Default: False

Command-line interface#

Positional Arguments#

General#

Image parameters#

Export parameters#

This Page