rm_lite.tools_3d.rmclean¶

RM-CLEAN on chunked 3D FDF/RMSF cubes via dask.

Classes¶

`RMClean3DResults`	Results of chunked 3D RM-CLEAN.
`_RMCleanBlockResult`

Functions¶

`_clean_block`(→ _RMCleanBlockResult)
`run_rmclean`(→ RMClean3DResults)	Run RM-CLEAN on chunked dirty FDF and RMSF cubes.
`run_rmclean_from_synth`(→ RMClean3DResults)	Run RM-CLEAN on the results of rm_lite.tools_3d.rmsynth.rmsynth_3d.

Module Contents¶

class rm_lite.tools_3d.rmclean.RMClean3DResults¶

Bases: NamedTuple

Results of chunked 3D RM-CLEAN.

clean_fdf_cube: dask.array.Array¶: Cleaned FDF cube, lazy dask array of shape (n_phi, ny, nx).

iter_count_map: dask.array.Array¶: Per-pixel CLEAN iteration count, lazy dask array of shape (ny, nx).

model_fdf_cube: dask.array.Array¶: Clean-component (model) FDF cube, same shape as clean_fdf_cube.

mom0_map: dask.array.Array¶: Zeroth Faraday moment (total polarised intensity) of the clean FDF, lazy dask array of shape (ny, nx). See calc_faraday_moments.

mom1_map: dask.array.Array¶: First Faraday moment (mean Faraday depth, rad/m^2), shape (ny, nx).

mom2_map: dask.array.Array¶: Second Faraday moment (Faraday depth dispersion, rad/m^2), shape (ny, nx).

resid_fdf_cube: dask.array.Array¶: Residual FDF cube, same shape as clean_fdf_cube.

class rm_lite.tools_3d.rmclean._RMCleanBlockResult¶

Bases: NamedTuple

clean_fdf: numpy.typing.NDArray[numpy.complex128]¶

iter_count: numpy.typing.NDArray[numpy.int64]¶

model_fdf: numpy.typing.NDArray[numpy.complex128]¶

resid_fdf: numpy.typing.NDArray[numpy.complex128]¶

rm_lite.tools_3d.rmclean._clean_block(dirty_fdf_block: numpy.typing.NDArray[numpy.complex128], rmsf_block: numpy.typing.NDArray[numpy.complex128], phi_arr_radm2: numpy.typing.NDArray[numpy.float64], phi_double_arr_radm2: numpy.typing.NDArray[numpy.float64], fwhm_rmsf_radm2: float, clean_options: rm_lite.utils.clean.RMCleanOptions, log_level: int, multiscale_options: rm_lite.utils.clean.MultiscaleOptions | None = None) → _RMCleanBlockResult¶

rm_lite.tools_3d.rmclean.run_rmclean(fdf_dirty_cube: dask.array.Array, rmsf_cube: dask.array.Array, phi_arr_radm2: numpy.typing.NDArray[numpy.float64], phi_double_arr_radm2: numpy.typing.NDArray[numpy.float64], fwhm_rmsf_radm2: float, mask: float, threshold: float, max_iter: int = 100000, gain: float = 0.1, moment_threshold: float | None = None, fdf_noise: float | None = None, log_level: int = logging.ERROR, multiscale: bool = False, multiscale_scales: numpy.typing.NDArray[numpy.float64] | None = None, multiscale_n_scales: int | None = None, multiscale_kernel: Literal['tapered_quad', 'gaussian'] = 'tapered_quad', multiscale_max_iter_sub_minor: int = 10000, multiscale_sub_minor_fraction: float = 0.5, multiscale_selection_margin: float = 0.08) → RMClean3DResults¶

Run RM-CLEAN on chunked dirty FDF and RMSF cubes.

Parameters:

fdf_dirty_cube (da.Array) – Dirty FDF cube, shape (n_phi, ny, nx), chunked spatially only (as produced by rm_lite.tools_3d.rmsynth.rmsynth_3d).
rmsf_cube (da.Array) – RMSF cube, shape (n_phi_double, ny, nx), with the same spatial chunking as fdf_dirty_cube.
phi_arr_radm2 (NDArray[np.float64]) – Faraday depth values in rad/m^2.
phi_double_arr_radm2 (NDArray[np.float64]) – Double-length Faraday depth values in rad/m^2, for the RMSF.
fwhm_rmsf_radm2 (float) – RMSF FWHM, shared by every pixel (3D RM-CLEAN here does not support a per-pixel FWHM map).
mask (float) – Masking threshold. Pixels below this value are not cleaned.
threshold (float) – Cleaning threshold. Stop when all pixels are below this value.
max_iter (int, optional) – Maximum CLEAN iterations. Defaults to 1000.
gain (float, optional) – CLEAN loop gain. Defaults to 0.1.
moment_threshold (float | None, optional) – Amplitude cut (in FDF amplitude units) applied to the clean FDF before computing the Faraday moment maps, passed to calc_faraday_moments. None includes all amplitudes (noise-biased). Defaults to None.
fdf_noise (float | None, optional) – Theoretical FDF noise; enables the adaptive off-source auto-mask (mask contracts off the RMSF sidelobes of bright sources, then relaxes as they subtract). None keeps the fixed-mask behaviour. Defaults to None.
log_level (int, optional) – Log level applied to rm_lite’s logger while each chunk runs. rmclean’s Hogbom loop logs at INFO and WARNING per pixel (e.g. “Starting minor loop…”, “All channels masked… performed N iterations”). These are routine per-pixel loop termination conditions, not anomalies, and at cube scale they’re just noise, so this defaults to ERROR (silencing both). Pass logging.WARNING or logging.INFO to restore progressively more per-pixel verbosity, e.g. while debugging a specific chunk. Defaults to logging.ERROR.
multiscale (bool, optional) – Use multiscale RM-CLEAN (recovers Faraday-thick structure). Defaults to False.
multiscale_scales (NDArray[np.float64] | None, optional) – Explicit scales (RMSF FWHM units); None auto-selects.
multiscale_n_scales (int | None, optional) – Cap on the auto scale count.
multiscale_kernel ("tapered_quad" | "gaussian", optional) – Scale kernel. Defaults to “tapered_quad”.
multiscale_max_iter_sub_minor (int, optional) – Max sub-minor iterations. Defaults to 10_000.
multiscale_sub_minor_fraction (float, optional) – Sub-minor re-selection fraction. Defaults to 0.5.
multiscale_selection_margin (float, optional) – Hybrid scale-selection parsimony margin in [0, 1). Among scales within this fraction of the best matched-filter score the smallest is chosen, keeping points on the delta scale. Defaults to 0.08.

Returns:

Lazy clean/model/residual FDF cubes and iteration-count map.

Return type:

RMClean3DResults

rm_lite.tools_3d.rmclean.run_rmclean_from_synth(rm_synth_3d_results: rm_lite.tools_3d.rmsynth.RMSynth3DResults, auto_mask: float = 7, auto_threshold: float = 1, max_iter: int = 100000, gain: float = 0.1, moment_threshold_snr: float = 5.0, log_level: int = logging.ERROR, multiscale: bool = False, multiscale_scales: numpy.typing.NDArray[numpy.float64] | None = None, multiscale_n_scales: int | None = None, multiscale_kernel: Literal['tapered_quad', 'gaussian'] = 'tapered_quad', multiscale_max_iter_sub_minor: int = 10000, multiscale_sub_minor_fraction: float = 0.5, multiscale_selection_margin: float = 0.08) → RMClean3DResults¶

Run RM-CLEAN on the results of rm_lite.tools_3d.rmsynth.rmsynth_3d.

Convenience wrapper that unpacks an RMSynth3DResults into run_rmclean, mirroring rm_lite.tools_1d.rmclean.run_rmclean_from_synth. mask and threshold are scaled from rm_synth_3d_results.theoretical_noise, the same way the 1D version scales from its per-pixel theoretical noise. 3D RM-synthesis only carries a per-channel (not per-pixel) noise estimate (see rm_lite.utils.dask_io.estimate_channel_noise_mad), so the resulting mask and threshold are uniform across the cube rather than per-pixel.

Parameters:

rm_synth_3d_results (RMSynth3DResults) – Results from rmsynth_3d.
auto_mask (float, optional) – Masking threshold in SNR, scaled by the theoretical FDF noise. Defaults to 7.
auto_threshold (float, optional) – Cleaning threshold in SNR, scaled by the theoretical FDF noise. Defaults to 1.
max_iter (int, optional) – Maximum CLEAN iterations. Defaults to 1000.
gain (float, optional) – CLEAN loop gain. Defaults to 0.1.
moment_threshold_snr (float, optional) – SNR cut (times the theoretical FDF noise) applied to the clean FDF before computing the Faraday moment maps. Defaults to 5.0.
log_level (int, optional) – See run_rmclean. Defaults to logging.ERROR.
multiscale (bool, optional) – Use multiscale RM-CLEAN (recovers Faraday-thick structure). Defaults to False.
scales – selection_margin: Multiscale options, see run_rmclean.
n_scales – selection_margin: Multiscale options, see run_rmclean.
kernel – selection_margin: Multiscale options, see run_rmclean.
max_iter_sub_minor – selection_margin: Multiscale options, see run_rmclean.
sub_minor_fraction – selection_margin: Multiscale options, see run_rmclean.

:param : selection_margin: Multiscale options, see run_rmclean.

Returns:: Lazy clean/model/residual FDF cubes and iteration-count map.
Return type:: RMClean3DResults