API reference

Top-level API

radialpaths.build_geometry(support, centres, *, centre_order='yx', validate_connected=True)[source]

Build support-constrained multi-centre radial geometry.

Parameters:

  • support (array-like of bool, 2D) – Accepted support \(\Omega\). True pixels are traversable and False pixels—including internal holes—are excluded.

  • centres (array-like, shape (N, 2)) – Supplied centre coordinates. Values are rounded with numpy.rint.

  • centre_order ({"yx", "xy"}, optional) – Coordinate ordering. The default is NumPy (row, column) order; "xy" accepts astronomy/plotting-style (x, y) positions.

  • validate_connected (bool, optional) – Require one 8-connected support component. The mathematical construction assumes a connected support, so the default is True.

Returns:

Reusable float64 geometry independent of any subsequently measured tracer.

Return type:

RadialGeometry

Notes

Distances are calculated on an 8-neighbour pixel graph with unit in-support costs. Exact distance ties are assigned to the first supplied centre, matching the validated implementation. Centre order is therefore part of the input whenever exact ties occur.

The paper’s observational products serialized normalized coordinates as float32. That reproduction-only storage setting is available from radialpaths.reproduction.build_paper_geometry(); they are not the numerical default of this public constructor.

The array should contain at least one layer of excluded pixels around its outer support if contact with the array edge is intended to be a physical boundary. This preserves the boundary expression without silently padding the input.

radialpaths.radial_profile(data, geometry, *, coordinate='rho_D', bins=30, min_pixels=6, mask=None)[source]

Measure unweighted median profiles on a precomputed geometry.

Parameters:

  • data (array-like, 2D) – Registered scalar field. Non-finite and masked values are excluded. An Astropy Quantity is accepted and its unit string is retained.

  • geometry (RadialGeometry) – Geometry returned by radialpaths.build_geometry().

  • coordinate ({"rho_D", "rho_X"}, optional) – Radial coordinate used for binning.

  • bins (int or array-like, optional) – Number of equal bins on [0, 1] or explicit edges spanning that interval. The validated default is 30 equal bins.

  • min_pixels (int, optional) – Minimum selected pixels required for a populated bin. The validated default is six.

  • mask (array-like of bool, optional) – Additional exclusion mask, where True pixels are omitted.

Returns:

Per-centre counts, unweighted medians, and 16th/84th percentiles.

Return type:

RadialProfile

Notes

Bins are lower-inclusive and upper-exclusive. Values exactly equal to one are explicitly included in the final bin, matching the observational figure estimator. No spline is fitted.

Image preparation

Inspectable preparation of support masks and candidate centres from images.

The functions in this module prepare the two formal inputs to the radial construction: a connected support and supplied centre coordinates. They do not infer physical nuclei, galaxies, or components.

class radialpaths.preprocessing.BackgroundResult(background, sigma_bg, background_mask, number_of_iterations, metadata)[source]

Bases: object

Background location and scatter with the pixels used to estimate them.

Parameters:
background: float
background_mask: NDArray[bool]
metadata: Mapping[str, object]
number_of_iterations: int
sigma_bg: float
class radialpaths.preprocessing.CentreCandidates(positions, peak_values, significance, rank, min_separation, selection_min_separation, detection_mask, metadata)[source]

Bases: object

Ranked local-intensity maxima considered as possible supplied centres.

Parameters:

  • positions (NDArray[int64])

  • peak_values (NDArray[float64])

  • significance (NDArray[float64])

  • rank (NDArray[int64])

  • min_separation (float)

  • selection_min_separation (float | None)

  • detection_mask (NDArray[bool])

  • metadata (Mapping[str, object])

detection_mask: NDArray[bool]
metadata: Mapping[str, object]
min_separation: float
peak_values: NDArray[float64]
positions: NDArray[int64]
rank: NDArray[int64]
select(indices)[source]

Return candidate positions for explicit zero-based candidate indices.

Parameters:

indices (Sequence[int])

Return type:

NDArray[int64]

selection_min_separation: float | None
significance: NDArray[float64]
class radialpaths.preprocessing.FinalSupportResult(support, component_labels, selected_component, rejected_components, number_of_pixels, all_centres_contained, touches_array_boundary)[source]

Bases: object

One connected support selected after supplied centres are known.

Parameters:

  • support (NDArray[bool])

  • component_labels (NDArray[int32])

  • selected_component (int)

  • rejected_components (tuple[int, ...])

  • number_of_pixels (int)

  • all_centres_contained (bool)

  • touches_array_boundary (bool)

all_centres_contained: bool
component_labels: NDArray[int32]
number_of_pixels: int
rejected_components: tuple[int, ...]
selected_component: int
support: NDArray[bool]
touches_array_boundary: bool
class radialpaths.preprocessing.PreparedImage(image, background_result, support_result, candidates, centres, final_support)[source]

Bases: object

All decisions made by prepare_image(), before radial geometry.

Parameters:
property background: float
background_result: BackgroundResult
candidates: CentreCandidates
centres: NDArray[int64]
final_support: FinalSupportResult
image: NDArray[float64]
property provisional_support: NDArray[bool]
property sigma_bg: float
property smoothed: NDArray[float64]
property support: NDArray[bool]
support_result: SupportResult
class radialpaths.preprocessing.SupportResult(image, smoothed, background, sigma_bg, provisional_support, threshold, smoothing_sigma, closing_radius, dilation_radius, valid_mask, metadata)[source]

Bases: object

Intermediate products from threshold-based support preparation.

Parameters:

  • image (NDArray[float64])

  • smoothed (NDArray[float64])

  • background (float)

  • sigma_bg (float)

  • provisional_support (NDArray[bool])

  • threshold (float)

  • smoothing_sigma (float)

  • closing_radius (float)

  • dilation_radius (float)

  • valid_mask (NDArray[bool])

  • metadata (Mapping[str, object])

background: float
closing_radius: float
dilation_radius: float
image: NDArray[float64]
metadata: Mapping[str, object]
provisional_support: NDArray[bool]
sigma_bg: float
smoothed: NDArray[float64]
smoothing_sigma: float
threshold: float
valid_mask: NDArray[bool]
radialpaths.preprocessing.estimate_background(image, *, preset='generic', psf_fwhm=None, smoothing_sigma=None, morphology_radius=None, error=None, bad_pixel_mask=None, border_fraction=0.2, threshold_sigma=1.5, maximum_iterations=5, convergence_centre_sigma=0.02, convergence_scale_fraction=0.02)[source]

Estimate a background from the image exterior with source exclusion.

preset="paper" reproduces the finite iterative estimator used for the JADES preparation. It is a reference procedure, not a claim that this background model is appropriate for every image.

Parameters:

  • image (ArrayLike)

  • preset (str)

  • psf_fwhm (float | None)

  • smoothing_sigma (float | None)

  • morphology_radius (float | None)

  • error (ArrayLike | None)

  • bad_pixel_mask (ArrayLike | None)

  • border_fraction (float)

  • threshold_sigma (float)

  • maximum_iterations (int)

  • convergence_centre_sigma (float)

  • convergence_scale_fraction (float)

Return type:

BackgroundResult

radialpaths.preprocessing.finalize_support(provisional_support, centres, *, connectivity=8, bad_pixel_mask=None)[source]

Retain the connected provisional component containing all centres.

Parameters:

  • provisional_support (ArrayLike)

  • centres (ArrayLike)

  • connectivity (int)

  • bad_pixel_mask (ArrayLike | None)

Return type:

FinalSupportResult

radialpaths.preprocessing.find_centre_candidates(prepared_support, *, preset='generic', psf_fwhm=None, maximum_radius=None, threshold_sigma=5.0, selection_min_separation=None)[source]

Rank local maxima on the support-preparation smoothed image.

The paper preset uses a maximum-filter radius of one PSF FWHM. The separate two-FWHM admission separation is stored as the recommended selection separation and is applied only when centres are selected automatically.

Parameters:
Return type:

CentreCandidates

radialpaths.preprocessing.prepare_image(image, *, preset, n_centres=None, selected_candidate_indices=None, centres=None, psf_fwhm=None, smoothing_sigma=None, closing_radius=None, dilation_radius=None, maximum_radius=None, minimum_separation=None, background=None, sigma_bg=None, error=None, bad_pixel_mask=None)[source]

Run the inspectable image-to-support-and-centres preparation sequence.

Exactly one of n_centres, selected_candidate_indices, or centres must be provided. The returned object exposes every intermediate product; it does not build radial geometry.

Parameters:

  • image (ArrayLike)

  • preset (str)

  • n_centres (int | None)

  • selected_candidate_indices (Sequence[int] | None)

  • centres (ArrayLike | None)

  • psf_fwhm (float | None)

  • smoothing_sigma (float | None)

  • closing_radius (float | None)

  • dilation_radius (float | None)

  • maximum_radius (float | None)

  • minimum_separation (float | None)

  • background (float | None)

  • sigma_bg (float | None)

  • error (ArrayLike | None)

  • bad_pixel_mask (ArrayLike | None)

Return type:

PreparedImage

radialpaths.preprocessing.prepare_support(image, *, background, sigma_bg, preset='generic', psf_fwhm=None, smoothing_sigma=None, closing_radius=None, dilation_radius=None, threshold_sigma=1.5, bad_pixel_mask=None)[source]

Construct a provisional support without selecting a component.

Internal holes are never filled. Invalid and user-masked pixels remain excluded from the provisional support.

Parameters:

  • image (ArrayLike)

  • background (float)

  • sigma_bg (float)

  • preset (str)

  • psf_fwhm (float | None)

  • smoothing_sigma (float | None)

  • closing_radius (float | None)

  • dilation_radius (float | None)

  • threshold_sigma (float)

  • bad_pixel_mask (ArrayLike | None)

Return type:

SupportResult

radialpaths.preprocessing.select_centres(candidates=None, *, n_centres=None, indices=None, centres=None, min_separation=None)[source]

Select supplied centres by rank, candidate indices, or coordinates.

No value of n_centres is inferred. Explicit coordinates bypass candidate detection entirely.

Parameters:
Return type:

NDArray[int64]

Result objects

class radialpaths.RadialGeometry(support, centres, distances, labels, centre_distance, boundary, boundary_distance, rho_D, rho_X, extents)[source]

Reusable radial geometry for a support and supplied centres.

Parameters are exposed as arrays so the construction remains inspectable. Arrays outside support are NaN for continuous fields and -1 for labels.

Parameters:

  • support (NDArray[bool])

  • centres (NDArray[int64])

  • distances (NDArray[float64])

  • labels (NDArray[int16])

  • centre_distance (NDArray[float64])

  • boundary (NDArray[bool])

  • boundary_distance (NDArray[float64])

  • rho_D (NDArray[float64])

  • rho_X (NDArray[float64])

  • extents (NDArray[float64])

support

Connected accepted support \(\Omega\).

Type:

ndarray of bool, shape (ny, nx)

centres

Rounded centre positions in NumPy (row, column) order. Here, N is the number of supplied centres.

Type:

ndarray of int, shape (N, 2)

distances

Per-centre support-constrained graph distances \(d_k(x)\).

Type:

ndarray, shape (N, ny, nx)

labels

Centre assignment \(a(x)\). Outside-support pixels are -1.

Type:

ndarray of int, shape (ny, nx)

centre_distance

Distance to the assigned centre.

Type:

ndarray, shape (ny, nx)

boundary

In-support pixels adjacent to excluded pixels in the 3-by-3 neighborhood.

Type:

ndarray of bool, shape (ny, nx)

boundary_distance

Support-constrained distance \(b(x)\) to the boundary.

Type:

ndarray, shape (ny, nx)

rho_D, rho_X

Relative depth and normalized progression coordinates.

Type:

ndarray, shape (ny, nx)

extents

\(L_k\), the maximum assigned-centre distance in each region.

Type:

ndarray, shape (N,)

property basin: NDArray[int16]

Alias for labels, retained for implementation provenance.

coordinate(name)[source]

Return one radial-coordinate field.

Parameters:

name ({"rho_D", "rho_X"}) – Coordinate name. Lower-case spellings "rho_d" and "rho_x" are accepted.

Return type:

NDArray[float64]

property n_centres: int

Number of supplied centres.

region(centre)[source]

Return the centre-associated region \(B_k\) as a mask.

Parameters:

centre (int)

Return type:

NDArray[bool]

property shape: tuple[int, int]

Spatial array shape.

class radialpaths.RadialProfile(coordinate, edges, radius, median, p16, p84, count, min_pixels, unit=None)[source]

Centre-conditioned binned profiles for a registered scalar field.

All two-dimensional result arrays have shape (N, n_bins), where N is the number of supplied centres. Omitted bins contain NaN in the summary arrays while retaining their actual pixel count in count.

Parameters:

  • coordinate (str)

  • edges (NDArray[float64])

  • radius (NDArray[float64])

  • median (NDArray[float64])

  • p16 (NDArray[float64])

  • p84 (NDArray[float64])

  • count (NDArray[int64])

  • min_pixels (int)

  • unit (str | None)

for_centre(centre)[source]

Return the profile for one zero-based centre index.

Parameters:

centre (int)

Return type:

CentreProfile

property n_bins: int

Number of radial bins.

property n_centres: int

Number of centre-conditioned profiles.

property populated: NDArray[bool]

Boolean array marking bins that satisfy min_pixels.

property values: NDArray[float64]

Alias for the binned median values.

class radialpaths.CentreProfile(centre, coordinate, edges, radius, median, p16, p84, count, unit=None)[source]

One centre-associated profile extracted from a RadialProfile.

Parameters:

  • centre (int)

  • coordinate (str)

  • edges (NDArray[float64])

  • radius (NDArray[float64])

  • median (NDArray[float64])

  • p16 (NDArray[float64])

  • p84 (NDArray[float64])

  • count (NDArray[int64])

  • unit (str | None)

property populated: NDArray[bool]

Boolean mask of bins satisfying the minimum-pixel rule.

Synthetic examples

Small deterministic supports and tracers for examples and teaching.

class radialpaths.synthetic.SyntheticScene(name, support, centres, brightness, tracer)[source]

A support, supplied centres, and two registered demonstration tracers.

Parameters:

  • name (str)

  • support (NDArray[bool])

  • centres (NDArray[int64])

  • brightness (NDArray[float64])

  • tracer (NDArray[float64])

radialpaths.synthetic.make_scene(name='folded', size=101)[source]

Create a canonical deterministic demonstration scene.

Parameters:

  • name ({"compact", "folded", "perforated", "branched",) – "capybara", "trex"} Geometric example.

  • size (int, optional) – Square array size. Values below 61 are rejected to keep structures resolved for the 30-bin demonstration.

Return type:

SyntheticScene

Plotting

Optional Matplotlib helpers with manuscript-consistent semantics.

radialpaths.plotting.plot_centre_candidates(image, candidates, *, selected=None, ax=None)[source]

Plot numbered centre candidates for scientific review.

Selected and unselected markers are visually distinct. Candidate numbers are zero-based and match CentreCandidates.rank.

Parameters:

candidates (CentreCandidates)

radialpaths.plotting.plot_geometry(geometry, *, coordinate='rho_D', ax=None, contours=True)[source]

Plot a radial-coordinate field, support outline, and supplied centres.

Returns the Matplotlib Axes and image artist.

Parameters:
radialpaths.plotting.plot_overview(data, geometry, *, coordinate='rho_D', profile=None)[source]

Plot tracer, coordinate geometry, and profile as a compact narrative.

Parameters:
radialpaths.plotting.plot_profile(profile, *, ax=None, uncertainty=True)[source]

Plot centre-conditioned profile medians with optional percentile bands.

Parameters:

I/O

Serialization helpers for reusable geometries and registered images.

radialpaths.io.load_geometry(path)[source]

Load a geometry written by save_geometry().

Parameters:

path (str | Path)

Return type:

RadialGeometry

radialpaths.io.read_fits(path, *, extension=0)[source]

Read a FITS image lazily through the optional Astropy dependency.

Parameters:

path (str | Path)

radialpaths.io.read_image(path, *, channel=None, colour_mode=None)[source]

Read a raster image as a two-dimensional scalar array.

Grayscale PNG, JPEG, and TIFF files are returned directly. For a colour image, provide a zero-based channel or set colour_mode="luminance". The documented luminance conversion is Rec. 709: 0.2126 R + 0.7152 G + 0.0722 B. No colour conversion is performed silently.

Parameters:

  • path (str | Path)

  • channel (int | None)

  • colour_mode (str | None)

radialpaths.io.save_geometry(path, geometry)[source]

Save a RadialGeometry to a compressed NPZ file.

Parameters:
Return type:

None