rm_lite.utils.synthesis¶

RM-synthesis utils

Attributes¶

`T`
`fdf_params_schema`
`fdf_params_schema_df`

Classes¶

`FDFOptions`	Options for RM-synthesis
`FWHM`
`FractionalSpectra`
`RMSFParams`	RM spread function parameters
`RMSFResults`	Results of the RMSF calculation
`RMSynthParams`	Parameters for RM-synthesis calculation
`RMsynthResults`	Results of the RM-synthesis calculation
`SigmaAdd`	Sigma_add complexity metrics
`SigmaAddArrays`
`StokesData`	Stokes parameters and errors
`StokesSigmaAdd`	Stokes Sigma_add complexity metrics
`TheoreticalNoise`	Theoretical noise of the FDF

Functions¶

`calc_mom2_fdf`(→ float)	Calculate the 2nd moment of the polarised intensity FDF. Can be applied to
`calculate_sigma_add`(→ SigmaAdd)	Calculate the most likely value of additional scatter, assuming the
`calculate_sigma_add_arr`(→ SigmaAddArrays)
`cdf_percentile`(→ float)	Return the value at a given percentile of a cumulative distribution function
`compute_rmsf_params`(→ RMSFParams)
`compute_rmsynth_params`(→ RMSynthParams)	Calculate the parameters for RM-synthesis.
`compute_theoretical_noise`(→ TheoreticalNoise)
`create_fractional_spectra`(→ FractionalSpectra \| None)
`faraday_simple_spectrum`(...)	Create a simple Faraday spectrum with a single component.
`freq_to_lambda2`(→ T)	Convert frequency to lambda^2.
`get_fdf_parameters`(→ polars.DataFrame)	Measure standard parameters from a complex Faraday Dispersion Function.
`get_fwhm_rmsf`(→ FWHM)	Calculate the FWHM of the RMSF.
`get_mask_index`(→ numpy.typing.NDArray[numpy.bool_])
`get_rmsf_nufft`(→ RMSFResults)	Compute the RMSF for a given set of lambda^2 values.
`inverse_rmsynth_nufft`(...)	Inverse RM-synthesis - FDF to Stokes Q and U in wavelength^2 space.
`lambda2_to_freq`(→ T)	Convert lambda^2 to frequency.
`make_double_phi_arr`(→ numpy.typing.NDArray[numpy.float64])
`make_phi_arr`(→ numpy.typing.NDArray[numpy.float64])	Construct a Faraday depth array.
`measure_fdf_complexity`(→ float)
`measure_qu_complexity`(→ StokesSigmaAdd)
`rmsynth_nufft`(→ numpy.typing.NDArray[numpy.complex128])	Run RM-synthesis on a cube of Stokes Q and U data using the NUFFT method.

Module Contents¶

class rm_lite.utils.synthesis.FDFOptions¶

Bases: NamedTuple

Options for RM-synthesis

d_phi_radm2: float | None = None¶: Faraday depth resolution

do_fit_rmsf: bool = False¶: Fit RMSF

do_fit_rmsf_real: bool = False¶: Fit real part of the RMSF

n_samples: float | None = 10.0¶: Number of samples

phi_max_radm2: float | None = None¶: Maximum Faraday depth

weight_type: Literal['variance', 'uniform'] = 'variance'¶: Weight type

class rm_lite.utils.synthesis.FWHM¶

Bases: NamedTuple

d_lambda_sq_max_m2: float¶: The maximum difference in lambda^2 values

fwhm_rmsf_radm2: float¶: The FWHM of the RMSF main lobe

lambda_sq_range_m2: float¶: The range of lambda^2 values

class rm_lite.utils.synthesis.FractionalSpectra¶

Bases: NamedTuple

fit_result: rm_lite.utils.fitting.FitResult | None¶

no_nan_idx: numpy.typing.NDArray[numpy.bool_]¶

stokes_data: StokesData¶

class rm_lite.utils.synthesis.RMSFParams¶

Bases: NamedTuple

RM spread function parameters

phi_max: float¶: Maximum Faraday depth

phi_max_scale: float¶: Maximum Faraday depth scale

rmsf_fwhm_meas: float¶: Measured FWHM of the RMSF

rmsf_fwhm_theory: float¶: Theoretical FWHM of the RMSF

class rm_lite.utils.synthesis.RMSFResults¶

Bases: NamedTuple

Results of the RMSF calculation

fit_status_arr: numpy.typing.NDArray[numpy.float64]¶: The status of the RMSF fit

fwhm_rmsf_arr: numpy.typing.NDArray[numpy.float64]¶: The FWHM of the RMSF main lobe

phi_double_arr_radm2: numpy.typing.NDArray[numpy.float64]¶: The (double length) Faraday depth array

rmsf_cube: numpy.typing.NDArray[numpy.float64]¶: The RMSF cube

class rm_lite.utils.synthesis.RMSynthParams¶

Bases: NamedTuple

Parameters for RM-synthesis calculation

lam_sq_0_m2: float¶: Reference wavelength^2 value

lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64]¶: Wavelength^2 values in m^2

phi_arr_radm2: numpy.typing.NDArray[numpy.float64]¶: Faraday depth values in rad/m^2

weight_arr: numpy.typing.NDArray[numpy.float64]¶: Weight array

class rm_lite.utils.synthesis.RMsynthResults¶

Bases: NamedTuple

Results of the RM-synthesis calculation

fdf_dirty_cube: numpy.typing.NDArray[numpy.float64]¶: The Faraday dispersion function cube

lam_sq_0_m2: float¶: The reference lambda^2 value

class rm_lite.utils.synthesis.SigmaAdd¶

Bases: NamedTuple

Sigma_add complexity metrics

sigma_add: float¶: Sigma_add median value

sigma_add_arrays: SigmaAddArrays¶: Sigma_add arrays

sigma_add_minus: float¶: Sigma_add lower quartile

sigma_add_plus: float¶: Sigma_add upper quartile

class rm_lite.utils.synthesis.SigmaAddArrays¶

Bases: NamedTuple

cdf: numpy.typing.NDArray[numpy.float64]¶: CDF array of the additional noise term

pdf: numpy.typing.NDArray[numpy.float64]¶: PDF array of the additional noise term

sigma_add_arr: numpy.typing.NDArray[numpy.float64]¶: Array of additional noise values

class rm_lite.utils.synthesis.StokesData¶

Bases: NamedTuple

Stokes parameters and errors

with_options(**kwargs)¶

Create a new StokesData instance with keywords updated

Returns:: New StokesData instance with updated attributes
Return type:: StokesData

complex_pol_arr: numpy.typing.NDArray[numpy.complex128]¶: Stokes Q and U array

complex_pol_error: numpy.typing.NDArray[numpy.complex128]¶: Stokes Q and U error array

freq_arr_hz: numpy.typing.NDArray[numpy.float64]¶: Frequency array in Hz

stokes_i_arr: numpy.typing.NDArray[numpy.float64] | None = None¶: Stokes I array

stokes_i_error_arr: numpy.typing.NDArray[numpy.float64] | None = None¶: Stokes I error array

stokes_i_model_arr: numpy.typing.NDArray[numpy.float64] | None = None¶: Stokes I model array

stokes_i_model_error: numpy.typing.NDArray[numpy.float64] | None = None¶: Stokes I model error array

class rm_lite.utils.synthesis.StokesSigmaAdd¶

Bases: NamedTuple

Stokes Sigma_add complexity metrics

sigma_add_p: SigmaAdd¶: Sigma_add for polarised intensity

sigma_add_q: SigmaAdd¶: Sigma_add for Stokes Q

sigma_add_u: SigmaAdd¶: Sigma_add for Stokes U

class rm_lite.utils.synthesis.TheoreticalNoise¶

Bases: NamedTuple

Theoretical noise of the FDF

with_options(**kwargs)¶

Create a new TheoreticalNoise instance with keywords updated

Returns:: New TheoreticalNoise instance with updated attributes
Return type:: TheoreticalNoise

fdf_error_noise: float¶: Theoretical noise of the FDF

fdf_q_noise: float¶: Theoretical noise of the real FDF

fdf_u_noise: float¶: Theoretical noise of the imaginary FDF

rm_lite.utils.synthesis.calc_mom2_fdf(complex_fdf_arr: numpy.typing.NDArray[numpy.complex128], phi_arr_radm2: numpy.typing.NDArray[numpy.float64]) → float¶: Calculate the 2nd moment of the polarised intensity FDF. Can be applied to a clean component spectrum or a standard FDF

rm_lite.utils.synthesis.calculate_sigma_add(y_arr: numpy.typing.NDArray[numpy.float64], dy_arr: numpy.typing.NDArray[numpy.float64], median: float | None = None, noise: float | None = None, n_samples: int = 1000) → SigmaAdd¶: Calculate the most likely value of additional scatter, assuming the input data is drawn from a normal distribution. The total uncertainty on each data point Y_i is modelled as dYtot_i**2 = dY_i**2 + dYadd**2.

rm_lite.utils.synthesis.calculate_sigma_add_arr(y_arr: numpy.typing.NDArray[numpy.float64], dy_arr: numpy.typing.NDArray[numpy.float64], median: float | None = None, noise: float | None = None, n_samples: int = 1000) → SigmaAddArrays¶

rm_lite.utils.synthesis.cdf_percentile(values: numpy.typing.NDArray[numpy.float64], cdf: numpy.typing.NDArray[numpy.float64], q=50.0) → float¶

Return the value at a given percentile of a cumulative distribution function

Parameters:

values (NDArray[np.float64]) – Array of values
cdf (NDArray[np.float64]) – Cumulative distribution function
q (float, optional) – Percentile. Defaults to 50.0.

Returns:

Interpolated value at the given percentile

Return type:

float

rm_lite.utils.synthesis.compute_rmsf_params(freq_arr_hz: numpy.typing.NDArray[numpy.float64], weight_arr: numpy.typing.NDArray[numpy.float64]) → RMSFParams¶

rm_lite.utils.synthesis.compute_rmsynth_params(freq_arr_hz: numpy.typing.NDArray[numpy.float64], complex_pol_arr: numpy.typing.NDArray[numpy.complex128], complex_pol_error: numpy.typing.NDArray[numpy.complex128], fdf_options: FDFOptions) → RMSynthParams¶

Calculate the parameters for RM-synthesis.

Parameters:

freq_arr_hz (NDArray[np.float64]) – Frequency array in Hz
pol_arr (NDArray[np.complex128]) – Complex polarisation array
real_qu_error (NDArray[np.float64 | np.float32]) – Error in Stokes Q and U (real)
fdf_options (FDFOptions) – Options for RM-synthesis

Raises:

ValueError – If d_phi_radm2 is not provided and n_samples is None.

Returns:

Wavelength^2 values, reference wavelength^2, Faraday depth values, weight array

Return type:

RMSynthParams

rm_lite.utils.synthesis.compute_theoretical_noise(complex_pol_error: numpy.typing.NDArray[numpy.complex128], weight_arr: numpy.typing.NDArray[numpy.float64]) → TheoreticalNoise¶

rm_lite.utils.synthesis.create_fractional_spectra(stokes_data: StokesData, ref_freq_hz: float, fit_order: int = 2, fit_function: Literal['log', 'linear'] = 'log', n_error_samples: int = 10000) → FractionalSpectra | None¶

rm_lite.utils.synthesis.faraday_simple_spectrum(freq_arr_hz: numpy.typing.NDArray[numpy.float64], frac_pol: float, psi0_deg: float, rm_radm2: float) → numpy.typing.NDArray[numpy.complex128]¶

Create a simple Faraday spectrum with a single component.

Parameters:

freq_arr_hz (NDArray[np.float64]) – Frequency array in Hz
frac_pol (float) – Fractional polarization
psi0_deg (float) – Initial polarization angle in degrees
rm_radm2 (float) – RM in rad/m^2

Returns:

Complex polarization spectrum

Return type:

NDArray[np.float64]

rm_lite.utils.synthesis.freq_to_lambda2(freq_hz: T) → T¶

Convert frequency to lambda^2.

Parameters:: freq_hz (float) – Frequency in Hz
Returns:: Wavelength^2 in m^2
Return type:: float

rm_lite.utils.synthesis.get_fdf_parameters(fdf_arr: numpy.typing.NDArray[numpy.complex128], phi_arr_radm2: numpy.typing.NDArray[numpy.float64], fwhm_rmsf_radm2: float, freq_arr_hz: numpy.typing.NDArray[numpy.float64], complex_pol_arr: numpy.typing.NDArray[numpy.complex128], complex_pol_error: numpy.typing.NDArray[numpy.complex128], lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64], lam_sq_0_m2: float, stokes_i_reference_flux: float, theoretical_noise: TheoreticalNoise, fit_function: Literal['log', 'linear'], bias_correction_snr: float = 5.0) → polars.DataFrame¶: Measure standard parameters from a complex Faraday Dispersion Function. Currently this function assumes that the noise levels in the Stokes Q and U spectra are the same. Returns a dictionary containing measured parameters.

rm_lite.utils.synthesis.get_fwhm_rmsf(lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64]) → FWHM¶

Calculate the FWHM of the RMSF.

Parameters:

lambda_sq_arr_m2 (NDArray[np.float64]) – Wavelength^2 values in m^2
super_resolution (bool, optional) – Use Cotton+Rudnick superresolution. Defaults to False.

Returns:

FWHM of the RMSF main lobe, maximum difference in lambda^2 values, range of lambda^2 values

Return type:

fwhm_rmsf_arr

rm_lite.utils.synthesis.get_mask_index(stokes_data: StokesData) → numpy.typing.NDArray[numpy.bool_]¶

rm_lite.utils.synthesis.get_rmsf_nufft(lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64], phi_arr_radm2: numpy.typing.NDArray[numpy.float64], weight_arr: numpy.typing.NDArray[numpy.float64], lam_sq_0_m2: float, mask_arr: numpy.typing.NDArray[numpy.bool_] | None = None, do_fit_rmsf: bool = False, do_fit_rmsf_real=False, eps: float = 1e-06) → RMSFResults¶

Compute the RMSF for a given set of lambda^2 values.

Parameters:

lambda_sq_arr_m2 (NDArray[np.float64]) – Wavelength^2 values in m^2
phi_arr_radm2 (NDArray[np.float64]) – Faraday depth values in rad/m^2
weight_arr (NDArray[np.float64]) – Weight array
lam_sq_0_m2 (float) – Reference wavelength^2 value
super_resolution (bool, optional) – Use superresolution. Defaults to False.
mask_arr (Optional[NDArray[np.float64]], optional) – Mask array. Defaults to None.
do_fit_rmsf (bool, optional) – Fit the RMSF with a Gaussian. Defaults to False.
do_fit_rmsf_real (bool, optional) – Fit the real part of the. Defaults to False.
eps (float, optional) – NUFFT tolerance. Defaults to 1e-6.

Raises:

ValueError – If the wavelength^2 and weight arrays are not the same shape.
ValueError – If the mask dimensions are > 3.
ValueError – If the mask depth does not match the lambda^2 vector.

Returns:

rmsf_cube, phi_double_arr_radm2, fwhm_rmsf_arr, fit_status_arr

Return type:

RMSFResults

rm_lite.utils.synthesis.inverse_rmsynth_nufft(complex_fdf_arr: numpy.typing.NDArray[numpy.complex128], lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64], phi_arr_radm2: numpy.typing.NDArray[numpy.float64], lam_sq_0_m2: float, eps: float = 1e-06) → numpy.typing.NDArray[numpy.complex128]¶

Inverse RM-synthesis - FDF to Stokes Q and U in wavelength^2 space.

Parameters:

complex_fdf_arr (NDArray[np.complex128]) – Complex polarisation array in Faraday depth space
lambda_sq_arr_m2 (NDArray[np.float64]) – Wavelength^2 values in m^2
phi_arr_radm2 (NDArray[np.float64]) – Faraday depth values in rad/m^2
lam_sq_0_m2 (float) – Reference wavelength^2 value
eps (float, optional) – NUFFT tolerance. Defaults to 1e-6.

Raises:

ValueError – If the Stokes Q and U data arrays are not the same shape.
ValueError – If the data dimensions are > 3.
ValueError – If the data depth does not match the lambda^2 vector.

Returns:

Complex polarisation array in wavelength^2 space

Return type:

NDArray[np.float64]

rm_lite.utils.synthesis.lambda2_to_freq(lambda_sq_m2: T) → T¶

Convert lambda^2 to frequency.

Parameters:: lambda_sq_m2 (NDArray[np.float64]) – Wavelength^2 in m^2
Returns:: Frequency in Hz
Return type:: NDArray[np.float64]

rm_lite.utils.synthesis.make_double_phi_arr(phi_arr_radm2: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64]¶

rm_lite.utils.synthesis.make_phi_arr(phi_max_radm2: float, d_phi_radm2: float) → numpy.typing.NDArray[numpy.float64]¶

Construct a Faraday depth array.

Parameters:

phi_max_radm2 (float) – Maximum Faraday depth in rad/m^2
d_phi_radm2 (float) – Spacing in Faraday depth in rad/m^2

Returns:

Faraday depth array in rad/m^2

Return type:

NDArray[np.float64]

rm_lite.utils.synthesis.measure_fdf_complexity(phi_arr_radm2: numpy.typing.NDArray[numpy.float64], complex_fdf_arr: numpy.typing.NDArray[numpy.complex128]) → float¶

rm_lite.utils.synthesis.measure_qu_complexity(freq_arr_hz: numpy.typing.NDArray[numpy.float64], complex_pol_arr: numpy.typing.NDArray[numpy.complex128], complex_pol_error: numpy.typing.NDArray[numpy.complex128], frac_pol: float, psi0_deg: float, rm_radm2: float) → StokesSigmaAdd¶

rm_lite.utils.synthesis.rmsynth_nufft(complex_pol_arr: numpy.typing.NDArray[numpy.complex128], lambda_sq_arr_m2: numpy.typing.NDArray[numpy.float64], phi_arr_radm2: numpy.typing.NDArray[numpy.float64], weight_arr: numpy.typing.NDArray[numpy.float64], lam_sq_0_m2: float, eps: float = 1e-06) → numpy.typing.NDArray[numpy.complex128]¶

Run RM-synthesis on a cube of Stokes Q and U data using the NUFFT method.

Parameters:

complex_pol_arr (NDArray[np.complex128]) – Complex polarisation values (Q + iU)
lambda_sq_arr_m2 (NDArray[np.float64]) – Wavelength^2 values in m^2
phi_arr_radm2 (NDArray[np.float64]) – Faraday depth values in rad/m^2
weight_arr (NDArray[np.float64]) – Weight array
lam_sq_0_m2 (Optional[float], optional) – Reference wavelength^2 in m^2. Defaults to None.
eps (float, optional) – NUFFT tolerance. Defaults to 1e-6.

Raises:

ValueError – If the weight and lambda^2 arrays are not the same shape.
ValueError – If the Stokes Q and U data arrays are not the same shape.
ValueError – If the data dimensions are > 3.
ValueError – If the data depth does not match the lambda^2 vector.

Returns:

Dirty Faraday dispersion function cube

Return type:

NDArray[np.float64]

rm_lite.utils.synthesis.T¶

rm_lite.utils.synthesis.fdf_params_schema¶

rm_lite.utils.synthesis.fdf_params_schema_df¶