pyBIA.catalog

Created on Thu Nov 17 10:10:11 2021

@author: danielgodinez

Classes

Catalog

Build photometric and morphological catalogs from postage-stamp astronomical images.

Functions

morph_parameters(data, x, y[, size, nsig, threshold, ...])

Compute segmentation-based morphological features for sources at given positions.

make_table(props, moments)

Assemble a flat feature array from photutils SourceCatalog properties and custom moments.

make_dataframe([table, x, y, zp, flux, flux_err, ...])

Assemble a photometry+morphology catalog into a pandas DataFrame (and optional CSV).

subtract_background(data[, length])

Subtract a local background estimate from a 2D image.

segm_find(data, *[, nsig, kernel_size, deblend, ...])

Perform image segmentation to detect sources above a sigma threshold.

get_segmentation(data, nsig, *[, xpix, ypix, size, ...])

Extract the segmentation map of a single central object in a postage stamp.

compute_layered_segmentation(image, sigma_values, ...)

Generate a layered segmentation map across multiple detection thresholds.

get_extent(img, pix_conversion)

Compute the spatial extent of an image for matplotlib.imshow.

get_display_limits(img)

Compute robust display limits for image visualization.

plot_objects_segmentation(*images[, pix_conversion, ...])

Plot images alongside layered segmentation masks.

plot_images_grid_2x2(img1, img2, img3, img4, *[, ...])

Display four images in a 2×2 grid with consistent visualization settings.

align_error_array(data, error, data_coords, error_coords)

Align an error map with a data array by shifting and padding.

Module Contents

class pyBIA.catalog.Catalog(data: numpy.ndarray, *, x: numpy.ndarray | list | None = None, y: numpy.ndarray | list | None = None, bkg: float | None = None, error: numpy.ndarray | None = None, zp: float | None = None, exptime: float | None = None, morph_params: bool = True, nsig: float = 0.3, threshold: int = 10, deblend: bool = False, size: int = 100, obj_name=None, field_name=None, flag=None, aperture: int = 15, annulus_in: int = 20, annulus_out: int = 35, kernel_size: int = 21, npixels: int = 9, connectivity: int = 8, invert: bool = False, cat: pandas.DataFrame | None = None)[source]

Build photometric and morphological catalogs from postage-stamp astronomical images.

This class extracts source positions and performs aperture photometry along with segmentation-based morphological analysis. Sources can be detected automatically via image segmentation or specified manually through input coordinates. The resulting catalog includes flux measurements, optional background subtraction, and a comprehensive set of shape descriptors for use in classification pipelines.

Parameters:

  • data (ndarray) – 2D image array.

  • x (array-like or None, optional) – Pixel coordinates of source centers. If None, sources are detected automatically.

  • y (array-like or None, optional) – Pixel coordinates of source centers. If None, sources are detected automatically.

  • bkg (float or None, optional) – Background mode. Use 0 if background is already subtracted; None to estimate the local sky background.

  • error (ndarray or None, optional) – Pixel-wise error map with the same shape as data.

  • zp (float or None, optional) – Zeropoint for magnitude calculations. If None, magnitudes are not computed.

  • exptime (float or None, optional) – Exposure time in seconds. If provided, data is normalized (e.g., counts per sec) when performing segmentation and computing morphology.

  • morph_params (bool, optional) – If True, compute moment-based morphological features (default is True).

  • nsig (float, optional) – Detection threshold in units of background sigma. Pixels above nsig are considered in segmentation. Default is 0.3.

  • threshold (int, optional) – Radius (in pixels) around the source center used to validate detection. If no object is found within this region, the source is flagged as a non-detection. Set to 0 to require exact overlap. Default is 10.

  • deblend (bool, optional) – If True, enables deblending of overlapping sources. Default is False (recommended for diffuse, extended objects).

  • size (int, optional) – Side length (pixels) of the square cutout used per source. If the image is smaller than size along any axis, the largest square that fits is used. Default is 100.

  • obj_name (array-like or None, optional) – List of object names for catalog rows.

  • field_name (array-like or None, optional) – List of field names for catalog rows.

  • flag (array-like or None, optional) – List of flags for catalog rows.

  • aperture (int, optional) – Aperture radius (in pixels) for photometry. Default is 15.

  • annulus_in (int, optional) – Inner radius (in pixels) of background annulus for local sky estimation. Default is 20.

  • annulus_out (int, optional) – Outer radius (in pixels) of background annulus. Default is 35.

  • kernel_size (int, optional) – Size of Gaussian kernel (in pixels) for segmentation smoothing. Default is 21.

  • npixels (int, optional) – Minimum area (in pixels) for segmentation detection. Default is 9.

  • connectivity (int, optional) – Pixel connectivity for segmentation (4 or 8). Default is 8.

  • invert (bool, optional) – If True, flips the (x, y) input order when cropping sub-images. Useful for data with (row, column) indexing or FITS-style origin. Default is False.

  • cat (pandas.DataFrame or None, optional) – Existing catalog to augment or use for metadata.

data[source]
error = None[source]
zp = None[source]
exptime = None[source]
morph_params = True[source]
nsig = 0.3[source]
threshold = 10[source]
deblend = False[source]
aperture = 15[source]
annulus_in = 20[source]
annulus_out = 35[source]
kernel_size = 21[source]
npixels = 9[source]
connectivity = 8[source]
invert = False[source]
bkg = None[source]
size = 100[source]
cat = None[source]
x = None[source]
y = None[source]
obj_name = None[source]
field_name = None[source]
flag = None[source]
create(*, save_file: bool = True, path: str | None = None, filename: str | None = None)[source]

Build the full photometric and morphological catalog.

This method performs source detection (via segmentation or user-supplied positions), computes aperture photometry, and optionally includes morphological features. It returns the catalog as a pandas DataFrame and can also save it to disk.

Parameters:

  • save_file (bool, optional) – If True, saves the catalog as a CSV file. Default is True.

  • path (str or None, optional) – Directory where the output CSV file will be saved. If None, defaults to the home directory.

  • filename (str or None, optional) – Name of the output CSV file. Defaults to “pyBIA_catalog.csv”.

Returns:

DataFrame containing the photometric and morphological measurements for all detected sources.

Return type:

pandas.DataFrame

Raises:

ValueError – If background mode (bkg) is invalid, data and error shapes mismatch, aperture and annulus sizes are incompatible, or if x and y coordinates differ in length.

Notes

  • If x and y are not provided, automatic source detection is run on the full frame.

  • If x and y are given, photometry and morphology are computed only at those positions.

  • Catalog output includes flux, flux error, optional magnitudes, and morphology features depending on initialization settings.

_auto_detect_sources()[source]

Automatically detect sources using segmentation and build the catalog.

This method performs full-frame source detection via image segmentation (using photutils.detect_sources), estimates background if needed, computes aperture photometry, and optionally derives morphological features using moment-based shape descriptors. Results are stored in self.cat.

_aperture_photometry()[source]

Perform aperture photometry at user-supplied positions and build the catalog.

This method computes circular-aperture fluxes at specified (x, y) coordinates, optionally subtracts a local background estimated from an annular region, and calculates flux errors if an error map is provided. Morphological features are computed if enabled. The resulting catalog is stored in self.cat.

_subtract_global_background()[source]

Estimate and subtract a global background level from the image. Only used when no catalog positions are input.

For large images, the method estimates the background using a sliding box of size 2 × annulus_out, ensuring the region encompasses the largest background annulus used for photometry. For small images, a single sigma-clipped median value is subtracted instead.

Returns:

Background-subtracted image.

Return type:

ndarray

pyBIA.catalog.morph_parameters(data, x, y, size=100, nsig=0.6, threshold=10, kernel_size=21, median_bkg=None, invert=False, deblend=False, exptime=None, npixels=9, connectivity=8)[source]

Compute segmentation-based morphological features for sources at given positions.

For each (x, y) position, a size × size cutout is extracted, optionally background- corrected and exposure-normalized, then segmented (via segm_find) to isolate the central source. Moment-based features are measured (via make_moments_table) and photutils-like source properties are recorded. Results are suitable for downstream classification tasks.

Parameters:

  • data (ndarray) – 2D image array.

  • x (array-like or scalar) – Pixel coordinates of source centers. Scalars are accepted and will be promoted to length-1 arrays.

  • y (array-like or scalar) – Pixel coordinates of source centers. Scalars are accepted and will be promoted to length-1 arrays.

  • size (int, optional) – Side length (pixels) of the square cutout used per source. If the image is smaller than size along any axis, the largest square that fits is used. Default is 100.

  • nsig (float, optional) – Detection threshold in units of background sigma for segmentation. Pixels above nsig contribute to detected regions. Default is 0.6.

  • threshold (int, optional) – Central-detection validation radius (pixels). If threshold == 0, require that the exact central pixel belongs to a segmented object; otherwise, require at least one segmented pixel within a central circular region of radius threshold. Sources failing this test are flagged as non-detections. Default is 10.

  • kernel_size (int, optional) – Gaussian kernel size (pixels) used by segm_find for segmentation smoothing. Default is 21.

  • median_bkg (array-like or None, optional) – Per-source median background values to subtract from each cutout (not a full background map). If None, input data is assumed to be background-subtracted. Length must match x/y if provided. Default is None.

  • invert (bool, optional) – If True, swap (x, y) when cropping (useful for data in row–column indexing or FITS-style top-left origin). Default is False.

  • deblend (bool, optional) – If True, enable deblending in segm_find to split overlapping sources. Default is False.

  • exptime (float or None, optional) – Exposure time in seconds. If provided, each cutout is divided by exptime prior to segmentation/feature measurement (e.g., to convert counts to counts/s). Default is None.

  • npixels (int, optional) – Minimum area (pixels) for valid segmented regions. Default is 9.

  • connectivity (int, optional) – Pixel connectivity for segmentation (4 or 8). Default is 8.

Returns:

  • props_list (ndarray of object) – Array of per-source photutils-like property selections (e.g., slices from SourceCatalog). For non-detections, the sentinel value -999 is inserted.

  • moments_list (list of pandas.DataFrame) – Per-source moment feature tables returned by make_moments_table. For non-detections, the sentinel value -999 is inserted.

  • segm_map (ndarray) – Segmentation map (int labels) for the last processed cutout. If any source failed detection, a zero array of that cutout’s shape is returned.

Raises:

ValueError – If the number of properties and moment tables differs (internal consistency check).

Notes

  • Each source is processed independently using a cropped cutout for computational efficiency.

  • Central-detection validation:

    • threshold == 0 enforces exact central-pixel membership in a segment.

    • threshold > 0 accepts any segment intersecting the central circular mask.

    The segment nearest the center is retained when multiple intersect the mask.

  • FITS coordinate convention: Many FITS images use a top-left origin (row, column). If your coordinates follow this convention, set invert=True so cropping treats inputs correctly. pyBIA assumes standard (x to the right, y upward) unless inverted.

  • For very small images (< ~50 pixels on a side), results may be unstable if the source is truncated at the edges (a warning is printed).

pyBIA.catalog.make_table(props, moments)[source]

Assemble a flat feature array from photutils SourceCatalog properties and custom moments.

For each source, this function concatenates (i) the moment-based features from moments and (ii) a selected subset of photutils segmentation properties from props. The resulting per-source feature vector is suitable for ML pipelines.

Parameters:

  • props (sequence) – Sequence (length N) where each element is an indexable selection of a photutils SourceCatalog (e.g., props[i][0]) representing the segmented source for sample i. If a source is missing (e.g., no segment), that entry should still exist but may be unusable; this function will emit sentinels.

  • moments (sequence) –

    Sequence (length N) of mapping-like objects (e.g., dict or DataFrame row) containing scalar moment features keyed by the following names: `[“M00”,”M10”,”M01”,”M20”,”M11”,”M02”,”M30”,”M21”,”M12”,”M03”,

    ”mu00”,”mu10”,”mu01”,”mu20”,”mu11”,”mu02”,”mu30”,”mu21”,”mu12”,”mu03”, “G00”,”G10”,”G01”,”G20”,”G11”,”G02”,”G30”,”G21”,”G12”,”G03”, “Hu1”,”Hu2”,”Hu3”,”Hu4”,”Hu5”,”Hu6”,”Hu7”, “L00”,”L10”,”L01”,”L20”,”L11”,”L02”,”L30”,”L21”,”L12”,”L03”]`.

Returns:

features – Per-source feature matrix.

Return type:

ndarray, shape (N, D)

Notes

  • If a source has no valid segmented object or moments, the function fills the entire feature vector for that source with the sentinel value -999.

  • The ‘isscalar’ property is cast to an integer flag: 1 for True (single source), 0 for False.

  • All other properties are extracted as scalars from the photutils table.

pyBIA.catalog.make_dataframe(table=None, x=None, y=None, zp=None, flux=None, flux_err=None, median_bkg=None, obj_name=None, field_name=None, flag=None, save=True, path=None, filename=None)[source]

Assemble a photometry+morphology catalog into a pandas DataFrame (and optional CSV).

This function merges per-source metadata (names, positions, flags), photometric measurements (flux, flux error, optional magnitudes), background statistics, and morphology features (moments + photutils properties) into a single DataFrame. If requested, the table is also written to disk as a CSV.

Parameters:

  • table (array-like or None, optional) –

    Feature matrix from make_table, shape (N, D) or (D,) for a single source. Columns are expected to be ordered as: moments [“M00”,”M10”,”M01”,”M20”,”M11”,”M02”,”M30”,”M21”,”M12”,”M03”,

    ”mu00”,”mu10”,”mu01”,”mu20”,”mu11”,”mu02”,”mu30”,”mu21”,”mu12”,”mu03”, “G00”,”G10”,”G01”,”G20”,”G11”,”G02”,”G30”,”G21”,”G12”,”G03”, “Hu1”,”Hu2”,”Hu3”,”Hu4”,”Hu5”,”Hu6”,”Hu7”, “L00”,”L10”,”L01”,”L20”,”L11”,”L02”,”L30”,”L21”,”L12”,”L03”]

    followed by photutils properties [“area”,”covar_sigx2”,”covar_sigy2”,”covar_sigxy”,

    ”covariance_eigval1”,”covariance_eigval2”, “cxx”,”cxy”,”cyy”,”eccentricity”,”ellipticity”,”elongation”, “equivalent_radius”,”fwhm”,”gini”,”orientation”,”perimeter”, “semimajor_sigma”,”semiminor_sigma”,”isscalar”, “bbox_xmax”,”bbox_xmin”,”bbox_ymax”,”bbox_ymin”, “max_value”,”maxval_xindex”,”maxval_yindex”, “min_value”,”minval_xindex”,”minval_yindex”].

    Default is None (no morphology columns added).

  • x (array-like or None, optional) – Pixel coordinates of source centers. If provided, columns xpix, ypix are added. Length should match the number of rows N. Default is None.

  • y (array-like or None, optional) – Pixel coordinates of source centers. If provided, columns xpix, ypix are added. Length should match the number of rows N. Default is None.

  • zp (float or None, optional) – Photometric zeropoint. If provided with flux, columns mag and mag_err are computed as -2.5*log10(flux) + zp and (2.5/ln 10)*(flux_err/flux), respectively. Default is None.

  • flux (array-like or None, optional) – Aperture-sum fluxes; adds column flux. Default is None.

  • flux_err (array-like or None, optional) – Flux uncertainties; adds column flux_err. If zp is also provided, mag_err is computed. Default is None.

  • median_bkg (array-like or None, optional) – Per-source median background values; adds column median_bkg. Default is None.

  • obj_name (array-like or None, optional) – Per-source object names; adds column obj_name. Default is None.

  • field_name (array-like or None, optional) – Per-source field names; adds column field_name. Default is None.

  • flag (array-like or None, optional) – Per-source flag values; adds column flag. Default is None.

  • save (bool, optional) – If True, write the DataFrame to CSV. Default is True.

  • path (str or Path or None, optional) – Output directory for CSV. If None, use the user’s home directory. Default is None.

  • filename (str or None, optional) – Output CSV filename. Default is “pyBIA_catalog.csv”.

Returns:

df – Catalog with available columns among: - Metadata: obj_name, field_name, flag - Positions: xpix, ypix - Background: median_bkg - Photometry: flux, flux_err, and (if zp provided) mag, mag_err - Morphology: the full set listed in table (moments + photutils properties)

Return type:

pandas.DataFrame

Notes

  • If table is 1D, it is promoted to 2D with a single row.

  • Magnitudes are computed only when both flux and zp are provided; no guards are applied here for non-positive flux (users should prefilter or post-handle infinities/NaNs if needed).

  • When save=True, the CSV is written to path/filename with index=False.

pyBIA.catalog.subtract_background(data, length=150)[source]

Subtract a local background estimate from a 2D image.

The image is divided into non-overlapping square regions of size length × length. For each region, the sigma-clipped median pixel value is computed and subtracted from that region. For images whose dimensions are not divisible by length, the array is padded symmetrically so that tiles align evenly. Padding is removed before return.

Parameters:

  • data (ndarray) – 2D image array.

  • length (int, optional) – Side length (pixels) of local regions used for background estimation. Default is 150. Smaller values capture more local variations, while larger values enforce a smoother background.

Returns:

data_sub – Background-subtracted image of the same shape as input.

Return type:

ndarray

Notes

  • For small images (min(data.shape) < length), no tiling is done; instead, the global sigma-clipped median is subtracted.

  • Padding is applied symmetrically (mode=’symmetric’) so that regions near the edges are treated consistently. Padding is sliced away before returning.

  • Background estimation uses astropy.stats.sigma_clipped_stats, which is robust against outliers.

pyBIA.catalog.segm_find(data: numpy.ndarray, *, nsig: float = 0.6, kernel_size: int = 21, deblend: bool = False, npixels: int = 9, connectivity: int = 8)[source]

Perform image segmentation to detect sources above a sigma threshold.

The input image is convolved with a 2D Gaussian kernel, then thresholded at nsig × sigma to identify sources. Optionally, overlapping sources can be deblended. Returns both the segmentation map and the convolved image.

Parameters:

  • data (ndarray) – 2D background-subtracted image array.

  • nsig (float, optional) – Detection threshold in units of background sigma. Pixels above nsig are considered during segmentation. Default is 0.6.

  • kernel_size (int, optional) – Size (pixels) of the square Gaussian kernel used for convolution. Must be odd. Default is 21.

  • deblend (bool, optional) – If True, deblend overlapping sources in the segmentation map. Default is False (recommended when preserving diffuse blobs as single objects).

  • npixels (int, optional) – Minimum number of connected pixels above threshold required to define a source. Default is 9.

  • connectivity (int, optional) – Pixel connectivity: 4 (edge-connected) or 8 (edge+corner-connected). Default is 8.

Returns:

  • segm (photutils.segmentation.SegmentationImage or None) – Segmentation image labeling detected sources. None if no sources are found.

  • convolved_data (ndarray) – Gaussian-convolved version of the input data used for source detection.

Notes

  • Input data must be background-subtracted prior to calling this function.

  • The Gaussian kernel is constructed with FWHM = 9 pixels (sigma = 9 × gaussian_fwhm_to_sigma) and size kernel_size × kernel_size.

  • If deblend=True, photutils.segmentation.deblend_sources is applied to split overlapping sources.

pyBIA.catalog.get_segmentation(data, nsig, *, xpix=100, ypix=100, size=100, median_bkg=None, kernel_size=21, deblend=False, r_in=20, r_out=35, npixels=9, connectivity=8, invert=False, threshold=10)[source]

Extract the segmentation map of a single central object in a postage stamp.

A square cutout is taken around (xpix, ypix) (or the frame center if unspecified), background-subtracted, and segmented using segm_find. Central validation matches morph_parameters behavior:

  • If threshold == 0, require the exact central pixel to belong to a segmented object.

  • If threshold > 0, require that at least one segmented pixel lies within a central circular mask of radius threshold, then select the object whose centroid is closest to the center (from all segments).

If validation fails, a zero array is returned.

Parameters:

  • data (ndarray) – 2D image array.

  • nsig (float) – Detection threshold in units of background sigma (passed to segm_find).

  • xpix (int or None, optional) – Central pixel coordinates of the target object. If both are None, the image center is used. Default is 100 each.

  • ypix (int or None, optional) – Central pixel coordinates of the target object. If both are None, the image center is used. Default is 100 each.

  • size (int, optional) – Side length (pixels) of the square cutout. If larger than the image dimensions, reduced to fit. Default is 100.

  • median_bkg (float or None, optional) – Background estimate for the cutout. If None, a local annulus (radii r_in, r_out) is used. If 0, no subtraction is applied. Default is None.

  • kernel_size (int, optional) – Size (pixels) of Gaussian kernel used in segm_find. Default is 21.

  • deblend (bool, optional) – If True, deblend overlapping sources in the segmentation map. Default is False.

  • r_in (int, optional) – Inner and outer radii (pixels) of the annulus used for local background estimation when median_bkg is None. Defaults are 20 and 35.

  • r_out (int, optional) – Inner and outer radii (pixels) of the annulus used for local background estimation when median_bkg is None. Defaults are 20 and 35.

  • npixels (int, optional) – Minimum number of connected pixels above threshold required for detection (passed to segm_find). Default is 9.

  • connectivity (int, optional) – Pixel connectivity: 4 (edge-connected) or 8 (edge+corner-connected). Default is 8.

  • invert (bool, optional) – If True, swap (x, y) ordering when cropping. Default is False.

  • threshold (int, optional) – Central validation parameter (pixels). See behavior above. Default is 10.

Returns:

seg – Segmentation map of shape (size, size) with only the selected object retained (nonzero label). If validation fails, a zero array is returned.

Return type:

ndarray

pyBIA.catalog.compute_layered_segmentation(image, sigma_values, pix_conversion, xpix, ypix, size, *, median_bkg=None, kernel_size=21, deblend=False, r_in=20, r_out=35, npixels=9, connectivity=8, threshold=10)[source]

Generate a layered segmentation map across multiple detection thresholds.

For each sigma threshold in sigma_values, get_segmentation is called to isolate the central source in a postage stamp. The resulting masks are stacked into a single 2D array, with different intensity values assigned to each layer. Higher sigma thresholds receive larger intensity values, creating a graded segmentation useful for visualization and contouring.

Parameters:

  • image (ndarray) – 2D image array.

  • sigma_values (sequence of float) – Detection thresholds (in sigma) to apply sequentially. Each value is passed as nsig to get_segmentation.

  • pix_conversion (float) – Pixel-to-arcsecond (or other physical unit) conversion factor. Currently unused internally, but included for consistency with downstream plotting routines.

  • xpix (int) – Pixel coordinates of the central source.

  • ypix (int) – Pixel coordinates of the central source.

  • size (int) – Side length (pixels) of the square cutout to extract.

  • median_bkg (float or None, optional) – Background estimate for the cutout. If None, a local annulus (radii r_in, r_out) is used. If 0, no subtraction is applied. Default is None.

  • kernel_size (int, optional) – Gaussian kernel size (pixels) used for segmentation convolution. Default is 21.

  • deblend (bool, optional) – If True, apply deblending to split overlapping sources. Default is False.

  • r_in (int, optional) – Inner and outer radii (pixels) for annular background estimation if median_bkg is None. Defaults are 20 and 35.

  • r_out (int, optional) – Inner and outer radii (pixels) for annular background estimation if median_bkg is None. Defaults are 20 and 35.

  • npixels (int, optional) – Minimum number of connected pixels above threshold to define a source. Default is 9.

  • connectivity (int, optional) – Pixel connectivity (4 or 8). Default is 8.

  • threshold (int, optional) – Central circular mask radius (pixels) used in get_segmentation to enforce detection near the cutout center. Default is 10.

Returns:

layered – Composite segmentation map. Pixels belonging to a detection at the i-th sigma level are assigned intensity values: [1.0, 0.7, 0.4, 0.1] (truncated to the number of sigma levels). Higher sigma levels correspond to higher intensities.

Return type:

ndarray of float, shape (size, size)

Notes

  • If fewer than four sigma values are provided, only the corresponding fraction of the default intensity sequence is used.

  • If more than four sigma values are provided, only the first four are represented (later thresholds are ignored).

  • This function is designed primarily for visualization (e.g., multi-level contours), not for quantitative feature extraction.

pyBIA.catalog.get_extent(img: numpy.ndarray, pix_conversion: float)[source]

Compute the spatial extent of an image for matplotlib.imshow.

The extent is centered on (0, 0) and converted from pixels to arcseconds (or other physical units) using the provided pixel-to-unit conversion.

Parameters:

  • img (ndarray) – 2D image array.

  • pix_conversion (float) – Pixel scale conversion factor (pixels per arcsecond, or pixels per unit). The returned extent is expressed in the reciprocal units (e.g., arcsec).

Returns:

extent – Extent values suitable for passing to imshow(extent=…), with coordinates centered on (0, 0).

Return type:

list of float [xmin, xmax, ymin, ymax]

Notes

  • The extent is computed as: x = (arange(width) - width/2) / pix_conversion, y = (arange(height) - height/2) / pix_conversion.

  • Units depend on pix_conversion: for example, if pix_conversion = 3.8961 pixels per arcsec, then the output extent is in arcseconds.

pyBIA.catalog.get_display_limits(img: numpy.ndarray)[source]

Compute robust display limits for image visualization.

The limits are based on the median and median absolute deviation (MAD) of finite pixels in the image, providing a stretch that is less sensitive to outliers than standard min/max scaling.

Parameters:

img (ndarray) – 2D image array. Non-finite values (NaN, inf) are ignored.

Returns:

vmin, vmax – Lower and upper display limits, defined as: vmin = median - 3 * MAD vmax = median + 10 * MAD

Return type:

float

Notes

  • This stretch is useful for displaying faint, extended features while suppressing noise and extreme outliers.

  • MAD is defined as median(|x - median(x)|).

  • The asymmetric scaling (-3 × MAD, +10 × MAD) biases toward emphasizing positive flux features.

pyBIA.catalog.plot_objects_segmentation(*images, pix_conversion=1.0, sigma_values=(0.1, 0.25, 0.55, 0.95), titles=None, suptitle='', xpix=None, ypix=None, size=None, median_bkg=None, kernel_size=21, deblend=False, r_in=20, r_out=35, npixels=9, connectivity=8, threshold=10, cmap='viridis', savepath='segm_multi.png', savefig=True)[source]

Plot images alongside layered segmentation masks.

Each input image is displayed in the top row, with its corresponding layered segmentation map (computed from sigma_values) displayed directly below. This provides a side-by-side visualization of raw data and threshold-dependent segmentation.

Parameters:

  • *images (ndarray) – One or more 2D image arrays. Between 1 and 5 are allowed.

  • pix_conversion (float, optional) – Pixel-to-arcsecond (or other unit) conversion factor. Used to compute axis extents. Default is 1.0.

  • sigma_values (sequence of float, optional) – Detection thresholds (in sigma) for layered segmentation. Default is (0.1, 0.25, 0.55, 0.95).

  • titles (list of str or None, optional) – Titles for each image panel (top row). Length must match number of images. Default is no titles.

  • suptitle (str, optional) – Figure-wide title. Default is “”.

  • xpix (int or None, optional) – Central pixel coordinates for cropping. If all of xpix, ypix, and size are given, each image is cropped to that region before plotting. Default is None.

  • ypix (int or None, optional) – Central pixel coordinates for cropping. If all of xpix, ypix, and size are given, each image is cropped to that region before plotting. Default is None.

  • size (int or None, optional) – Side length (pixels) of cropped cutouts, if cropping is applied. Default is None (no cropping).

  • median_bkg (float or None, optional) – Background estimate for segmentation. If None, background is estimated locally via annuli of radii r_in and r_out. If 0, no subtraction is applied. Default is None.

  • kernel_size (int, optional) – Gaussian kernel size (pixels) for segmentation convolution. Default is 21.

  • deblend (bool, optional) – If True, split overlapping sources during segmentation. Default is False.

  • r_in (int, optional) – Inner and outer radii (pixels) for annular background estimation. Defaults are 20 and 35.

  • r_out (int, optional) – Inner and outer radii (pixels) for annular background estimation. Defaults are 20 and 35.

  • npixels (int, optional) – Minimum connected pixel area (pixels) required for detection. Default is 9.

  • connectivity (int, optional) – Pixel connectivity: 4 (edge-connected) or 8 (edge+corner-connected). Default is 8.

  • threshold (int, optional) – Central circular mask radius (pixels) used to validate detections during segmentation. Default is 10.

  • cmap (str, optional) – Matplotlib colormap for displaying the original images. Default is “viridis”.

  • savepath (str, optional) – Output path for saving the figure when savefig=True. Default is “segm_multi.png”.

  • savefig (bool, optional) – If True, save the figure to savepath. If False, display with plt.show(). Default is True.

Returns:

Displays or saves the figure. Does not return a DataFrame or array.

Return type:

None

Notes

  • A maximum of 5 images may be passed at once.

  • Each figure has two rows: raw images (top) and layered segmentation masks (bottom).

  • A legend indicates which intensity levels correspond to the sigma_values used in layered segmentation.

  • Axis labels are expressed in arcseconds if pix_conversion is given in pixels per arcsecond.

pyBIA.catalog.plot_images_grid_2x2(img1, img2, img3, img4, *, pix_conversion=1.0, titles=None, suptitle='', xpix=None, ypix=None, size=None, cmap='viridis', savepath='outliers.png', savefig=True)[source]

Display four images in a 2×2 grid with consistent visualization settings.

This function mirrors the style of the image panels from plot_objects_segmentation: identical extent handling, robust (median±MAD) display limits, axis labeling, spacing, and aesthetics. Useful for side-by-side comparison of four sources or cutouts.

Parameters:

  • img1 (ndarray) – Four 2D image arrays to display.

  • img2 (ndarray) – Four 2D image arrays to display.

  • img3 (ndarray) – Four 2D image arrays to display.

  • img4 (ndarray) – Four 2D image arrays to display.

  • pix_conversion (float, optional) – Pixel-to-arcsecond (or other unit) conversion factor. Passed to get_extent. Default is 1.0.

  • titles (list of str or None, optional) – Titles for the four panels, in row-major order ([top-left, top-right, bottom-left, bottom-right]). Must be length 4. Default is None (no titles).

  • suptitle (str, optional) – Figure-level title. Default is “”.

  • xpix (int or None, optional) – If all three are provided, each image is cropped to a square cutout using data_processing.crop_image(img, xpix, ypix, size). Default is None (no cropping).

  • ypix (int or None, optional) – If all three are provided, each image is cropped to a square cutout using data_processing.crop_image(img, xpix, ypix, size). Default is None (no cropping).

  • size (int or None, optional) – If all three are provided, each image is cropped to a square cutout using data_processing.crop_image(img, xpix, ypix, size). Default is None (no cropping).

  • cmap (str, optional) – Matplotlib colormap for images. Default is “viridis”.

  • savepath (str, optional) – Output file path if saving the figure. Default is “outliers.png”.

  • savefig (bool, optional) – If True, save the figure to savepath. If False, display the figure interactively with plt.show(). Default is True.

Returns:

Displays or saves the figure. Does not return arrays or DataFrames.

Return type:

None

Notes

  • Each panel is flipped vertically (consistent with other plotting functions in this module) and labeled in arcseconds relative to the cutout center.

  • Robust display scaling is applied via get_display_limits.

  • Grid layout uses equal spacing (no white space between panels).

pyBIA.catalog.align_error_array(data, error, data_coords, error_coords)[source]

Align an error map with a data array by shifting and padding.

This function shifts the error array so that a reference object (identified by coordinates in both arrays) is aligned, then pads or crops as needed to match the shape of data. Useful when error maps (e.g., rms images) are offset relative to science images due to inconsistent sizes or coordinate origins.

Parameters:

  • data (ndarray) – Target 2D science image array.

  • error (ndarray) – Error map (e.g., rms image) to align with data.

  • data_coords (tuple of int) – (x, y) pixel coordinates of a reference object in data.

  • error_coords (tuple of int) – (x, y) pixel coordinates of the same object in error.

Returns:

padded_error – Error array aligned and padded/cropped to the same shape as data. Non-overlapping regions are filled with zeros.

Return type:

ndarray

Notes

  • This approach assumes both arrays are on the same pixel grid up to an integer shift, and does not perform interpolation.

  • Alignment is determined by the relative offset between data_coords and error_coords.

  • This was originally motivated by the NDWFS Boötes R-band data, where rms maps and images had inconsistent dimensions. In general, a WCS-based solution (via astropy.wcs) may be preferable if RA/Dec information is available.