setigen API reference

Signal parameter functions

setigen.funcs package

setigen.frame module

class setigen.frame.Frame(waterfall: Any = None, fchans: int | None = None, tchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: None | int | Generator | BitGenerator | SeedSequence = None, **kwargs: Any)[source]

Bases: object

Represent synthetic or waterfall-backed SETI spectrogram data.

__init__(waterfall: Any = None, fchans: int | None = None, tchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: None | int | Generator | BitGenerator | SeedSequence = None, **kwargs: Any) → None[source]

Initialize a frame from synthetic dimensions or existing data.

Parameters:

waterfall – Waterfall object or path to a .fil or .h5 file.
fchans – Number of frequency channels for synthetic initialization.
tchans – Number of time channels for synthetic initialization.
df – Frequency resolution.
dt – Time resolution.
fch1 – Frequency of the first channel.
ascending – Whether the frequency axis should be ascending.
data – Optional preloaded frame data.
seed – Random seed or generator.
**kwargs – Additional construction keywords such as shape, mjd, t_start, source_name, f_start, or f_stop.

Build a frame directly from an in-memory data array.

Parameters:

df – Frequency resolution.
dt – Time resolution.
fch1 – Frequency of the first channel.
ascending – Whether the frequency axis is ascending.
data – Preloaded frame data.
metadata – Optional metadata to attach to the frame.
waterfall – Optional associated waterfall object.
seed – Random seed or generator.

Returns:

Frame populated with the supplied data.

classmethod from_waterfall(waterfall: Any, seed: None | int | Generator | BitGenerator | SeedSequence = None) → Frame[source]

Build a frame from a waterfall-backed observation.

Parameters:

waterfall – Waterfall object or path to a supported file.
seed – Random seed or generator.

Returns:

Frame loaded from the supplied waterfall.

classmethod from_backend_params(fchans: int | None = None, obs_length: float = 300, sample_rate: float = 3000000000.0, num_branches: int = 1024, fftlength: int = 1048576, int_factor: int = 51, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: None | int | Generator | BitGenerator | SeedSequence = None) → Frame[source]

Build a frame from backend-like observing parameters.

Parameters:

fchans – Number of frequency channels. Required when data is not supplied.
obs_length – Observation length in seconds.
sample_rate – Real-voltage sample rate in Hz.
num_branches – Number of PFB branches.
fftlength – Fine-channel FFT length.
int_factor – Fine-channel integration factor.
fch1 – Frequency of the first channel.
ascending – Whether the frequency axis is ascending.
data – Optional preloaded frame data.
seed – Random seed or generator.

Returns:

Frame with dimensions implied by the backend parameters.

Raises:

ValueError – If neither fchans nor data is supplied, or if the supplied data shape is inconsistent with the backend parameters.

copy() → Frame[source]

Return a deep copy of the frame.

Returns:: Independent frame copy.

property fmid: float: Return the midpoint frequency of the frame.

property mjd: float: Return the frame start time in Modified Julian Date.

property t_stop: float: Return the observation stop time in Unix seconds.

property obs_length: float: Return the total observation length in seconds.

property ts_ext: ndarray: Return the time axis extended by one final endpoint sample.

property mean: float: Return the mean intensity of the frame.

property std: float: Return the standard deviation of the frame.

get_total_stats() → tuple[float, float][source]

Return the mean and standard deviation of the full frame.

Returns:: Mean and standard deviation of the frame data.

get_noise_stats() → tuple[float, float][source]

Return the sigma-clipped noise statistics for the frame.

Returns:: Sigma-clipped noise mean and standard deviation.

zero_data() → None[source]: Reset frame data and cached noise statistics to zero.

add_noise(x_mean: float, x_std: float | None = None, x_min: float | None = None, noise_type: str = 'chi2') → ndarray[source]

Add synthetic radiometer or Gaussian noise to the frame.

Parameters:

x_mean – Target mean intensity.
x_std – Target standard deviation for Gaussian noise.
x_min – Optional lower bound for truncated Gaussian noise.
noise_type – Noise distribution selector.

Returns:

Synthetic noise array added to the frame.

Raises:

ValueError – If Gaussian noise is requested without x_std.

add_noise_from_obs(x_mean_array: ndarray | None = None, x_std_array: ndarray | None = None, x_min_array: ndarray | None = None, share_index: bool = True, noise_type: str = 'chi2') → ndarray[source]

Add synthetic noise by sampling empirical observation parameters.

Parameters:

x_mean_array – Candidate noise means.
x_std_array – Candidate noise standard deviations.
x_min_array – Candidate truncated-Gaussian minima.
share_index – Whether to sample correlated parameters by shared index.
noise_type – Noise distribution selector.

Returns:

Synthetic noise array added to the frame.

Raises:

IndexError – If shared-index sampling is requested for mismatched parameter arrays.

Add a synthetic signal to the frame.

Parameters:

path – Signal path in time-frequency space.
t_profile – Time-intensity profile.
f_profile – Frequency profile callable.
bp_profile – Optional bandpass profile.
bounding_f_range – Optional bounding frequency range for rendering.
integrate_path – Whether to oversample and average the path in time.
integrate_t_profile – Whether to oversample and average the time profile.
integrate_f_profile – Whether to oversample and average the frequency profile.
doppler_smearing – Whether to numerically smear power across frequency bins.
t_subsamples – Number of time subsamples per bin.
f_subsamples – Number of frequency subsamples per bin.
smearing_subsamples – Number of substeps used for Doppler smearing.

Returns:

Two-dimensional signal array that was added to the frame.

add_constant_signal(f_start: Any, drift_rate: Any, level: float, width: Any, f_profile_type: str = 'sinc2', doppler_smearing: bool = False) → ndarray[source]

Add a constant-intensity, constant-drift signal to the frame.

Parameters:

f_start – Starting signal frequency.
drift_rate – Signal drift rate.
level – Signal intensity.
width – Signal width.
f_profile_type – Spectral profile selector.
doppler_smearing – Whether to numerically smear power across bins.

Returns:

Two-dimensional signal array that was added to the frame.

get_index(frequency: Any) → ndarray[source]

Convert frequency to the closest channel index.

Parameters:: frequency – Frequency or array of frequencies to convert.
Returns:: Closest frame index or indices.

get_frequency(index: int | ndarray) → float | ndarray[source]

Convert a frame index into frequency.

Parameters:: index – Frame index or indices.
Returns:: Frequency value or array in Hz.

get_intensity(snr: float) → float[source]

Calculate signal intensity from SNR using the frame noise estimate.

Parameters:: snr – Desired signal-to-noise ratio.
Returns:: Signal intensity that corresponds to the requested SNR.
Raises:: ValueError – If the frame does not yet contain measurable noise.

get_snr(intensity: float) → float[source]

Calculate SNR from signal intensity using the frame noise estimate.

Parameters:: intensity – Signal intensity.
Returns:: Signal-to-noise ratio for the supplied intensity.
Raises:: ValueError – If the frame does not yet contain measurable noise.

get_drift_rate(start_index: int, stop_index: int) → float[source]

Calculate drift rate from pixel coordinates.

Parameters:

start_index – Starting frequency index.
stop_index – Ending frequency index.

Returns:

Drift rate in Hz/s.

get_info() → dict[str, Any][source]

Return the full frame attribute dictionary.

Returns:: Full frame attribute dictionary.

get_params() → dict[str, Any][source]

Return the core frame parameters.

Returns:: Dictionary of primary frame parameters.

get_data(db: bool = False) → ndarray[source]

Return frame data in linear or decibel units.

Parameters:: db – Whether to convert intensities to dB before returning them.
Returns:: Frame data array.

get_metadata() → dict[str, Any][source]

Return attached frame metadata.

Returns:: Metadata dictionary associated with the frame.

add_metadata(new_metadata: dict[str, Any]) → None[source]

Append custom metadata to the frame.

Parameters:: new_metadata – Metadata entries to merge into the frame metadata.

update_metadata(new_metadata: dict[str, Any]) → None[source]

Alias for add_metadata().

Parameters:: new_metadata – Metadata entries to merge into the frame metadata.

plot(*args: Any, **kwargs: Any) → Any[source]

Plot frame spectrogram data.

Parameters:

frame – Frame to plot.
ftype – Frequency-axis display mode.
ttype – Time-axis display mode.
db – Whether to convert intensities to dB.
colorbar – Whether to display the colorbar.
label – Whether to place the source name as an anchored label.
minor_ticks – Whether to enable minor ticks.
grid – Whether to draw the major-tick grid.
swap_axes – Whether to swap frequency and time axes.
**kwargs – Additional matplotlib.pyplot.imshow() keyword arguments.

Returns:

Spectrogram image artist.

get_slice(*args: Any, **kwargs: Any) → Any[source]

Return a frequency slice of a frame.

Parameters:

fr – Input frame.
l – Left frequency index.
r – Right frequency index.

Returns:

Sliced frame.

get_waterfall() → Any[source]

Return the current frame as an updated waterfall object.

Returns:: Waterfall representation of the frame.

check_waterfall() → Any[source]

Return the updated attached waterfall when one exists.

Returns:: Updated waterfall object or None when the frame has no attached waterfall.

save_fil(filename: str | PathLike[str], max_load: int = 1) → None[source]

Save frame data as a SIGPROC filterbank file.

Parameters:

filename – Output .fil path.
max_load – Maximum load parameter for a lazily created waterfall.

save_hdf5(filename: str | PathLike[str], max_load: int = 1) → None[source]

Save frame data as an HDF5 waterfall file.

Parameters:

filename – Output .h5 path.
max_load – Maximum load parameter for a lazily created waterfall.

save_h5(filename: str | PathLike[str], max_load: int = 1) → None[source]

Save frame data as an HDF5 waterfall file.

Parameters:

filename – Output .h5 path.
max_load – Maximum load parameter for a lazily created waterfall.

save_npy(filename: str | PathLike[str]) → None[source]

Save frame data as a NumPy binary file.

Parameters:: filename – Output .npy path.

load_npy(filename: str | PathLike[str]) → None[source]

Load frame data from a NumPy binary file.

Parameters:: filename – Input .npy path.

save_pickle(filename: str | PathLike[str]) → None[source]

Serialize the full frame with pickle.

Parameters:: filename – Output pickle path.

classmethod load_pickle(filename: str | PathLike[str]) → Frame[source]

Load a frame from a pickled file.

Parameters:: filename – Input pickle path created by save_pickle().
Returns:: Deserialized frame object.

setigen.frame.params_from_backend(obs_length: float = 300, sample_rate: float = 3000000000.0, num_branches: int = 1024, fftlength: int = 1048576, int_factor: int = 51) → dict[str, float][source]

Return frame parameters implied by backend characteristics.

Parameters:

obs_length – Observation length in seconds.
sample_rate – Real-voltage sample rate in Hz.
num_branches – Number of PFB branches.
fftlength – Fine-channel FFT length.
int_factor – Fine-channel integration factor.

Returns:

Dictionary containing tchans, df, and dt.

setigen.cadence module

class setigen.cadence.Cadence(frame_list: Iterable[Frame] | None = None, t_slew: float = 0, t_overwrite: bool = False)[source]

Bases: MutableSequence

Organize a sequence of compatible Frame objects into a cadence.

__init__(frame_list: Iterable[Frame] | None = None, t_slew: float = 0, t_overwrite: bool = False) → None[source]

Initialize a cadence.

Parameters:

frame_list – Optional iterable of frames to include.
t_slew – Slew time between frames in seconds.
t_overwrite – Whether to overwrite frame start times to enforce slew spacing.

property t_start: float | None: Return the cadence start time in Unix seconds.

property fch1: float | None: Return the first-channel frequency shared by the cadence.

property ascending: bool | None: Return whether cadence frequencies are ascending.

property fmin: float | None: Return the minimum cadence frequency.

property fmax: float | None: Return the maximum cadence frequency.

property fmid: float | None: Return the midpoint cadence frequency.

property df: float | None: Return the shared cadence frequency resolution.

property dt: float | None: Return the shared cadence time resolution.

property fchans: int | None: Return the number of frequency channels in each frame.

property tchans: int | None: Return the total number of time channels across the cadence.

property obs_range: float | None: Return the total observed time span covered by the cadence.

insert(i: int, v: Frame) → None[source]

Insert a compatible frame into the cadence.

Parameters:

i – Insertion index.
v – Frame to insert.

overwrite_times() → None[source]: Overwrite frame start times using the configured slew spacing.

property slew_times: ndarray: Return slew times between consecutive frames.

add_signal(*args: Any, **kwargs: Any) → None[source]

Add the same signal specification to every frame in the cadence.

Parameters:

*args – Positional arguments forwarded to Frame.add_signal().
**kwargs – Keyword arguments forwarded to Frame.add_signal().

apply(func: Callable[[Frame], Any]) → list[Any][source]

Apply a function to each frame in the cadence.

Parameters:: func – Callable that accepts a frame.
Returns:: Results returned from each frame application.

plot(*args: Any, **kwargs: Any) → Any[source]

Plot a cadence as a vertically stacked figure.

Parameters:

cadence – Cadence to plot.
ftype – Frequency-axis display mode.
ttype – Time-axis display mode.
db – Whether to convert intensities to dB.
slew_times – Whether to space panels proportionally to slew time.
colorbar – Whether to display a shared colorbar.
labels – Whether to place source labels on each subplot.
title – Whether to add the first source name as the figure title.
minor_ticks – Whether to enable minor ticks.
grid – Whether to draw the major-tick grid.
**kwargs – Additional matplotlib.figure.Figure.subplots() keyword arguments.

Returns:

Tuple of subplot axes and optional colorbar axis.

Raises:

ValueError – If negative slew-time spacing is requested.

consolidate() → Frame | None[source]

Concatenate the cadence into a single frame.

Returns:: Consolidated frame, or None when the cadence is empty.

save_pickle(filename: str | PathLike[str]) → None[source]

Serialize the full cadence with pickle.

Parameters:: filename – Output pickle path.

classmethod load_pickle(filename: str | PathLike[str]) → Cadence[source]

Load a cadence from a pickled file.

Parameters:: filename – Input pickle path created by save_pickle().
Returns:: Deserialized cadence object.

class setigen.cadence.OrderedCadence(frame_list: Iterable[Frame] | None = None, order: str = 'ABACAD', t_slew: float = 0, t_overwrite: bool = False)[source]

Bases: Cadence

Cadence variant that tracks per-frame order labels.

__init__(frame_list: Iterable[Frame] | None = None, order: str = 'ABACAD', t_slew: float = 0, t_overwrite: bool = False) → None[source]

Initialize an ordered cadence.

Parameters:

frame_list – Optional iterable of frames to include.
order – Cadence order string such as “ABACAD”.
t_slew – Slew time between frames in seconds.
t_overwrite – Whether to overwrite frame start times to enforce slew spacing.

insert(i: int, v: Frame) → None[source]

Insert a frame and assign its order label when needed.

Parameters:

i – Insertion index.
v – Frame to insert.

set_order(order: str) → None[source]

Reassign cadence order labels.

Parameters:: order – New cadence order string.

by_label(order_label: str = 'A') → Cadence[source]

Filter frames by cadence order label.

Parameters:: order_label – Cadence label to match.
Returns:: New cadence containing only matching frames.

setigen.spectrum module

class setigen.spectrum.Spectrum(fchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: Any = None, **kwargs: Any)[source]

Bases: Frame

Store a one-dimensional frequency spectrum as a Frame subclass.

__init__(fchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: Any = None, **kwargs: Any) → None[source]

Initialize a one-row spectral frame.

Parameters:

fchans – Number of frequency channels.
df – Frequency resolution.
dt – Time resolution.
fch1 – Frequency of the first channel.
ascending – Whether the frequency axis is ascending.
data – Optional preloaded spectrum.
seed – Random seed or generator.
**kwargs – Additional frame-construction keyword arguments.

array(db: bool = False) → ndarray[source]

Return the spectrum as a one-dimensional array.

Parameters:: db – Whether to convert intensities to dB.
Returns:: One-dimensional spectral array.

plot(ftype: str = 'fmid', snr: bool = False, db: bool = False, minor_ticks: bool = False, **kwargs: Any) → None[source]

Plot the spectrum.

Parameters:

ftype – Frequency-axis display mode.
snr – Whether to plot normalized signal-to-noise instead of raw power.
db – Whether to convert intensities to dB.
minor_ticks – Whether to enable minor ticks.
**kwargs – Additional matplotlib.pyplot.plot() keyword arguments.

normalize() → None[source]: Normalize the spectrum background to zero mean and unit variance.

setigen.timeseries module

class setigen.timeseries.TimeSeries(tchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: Any = None, **kwargs: Any)[source]

Bases: Frame

Store a one-dimensional time series as a Frame subclass.

__init__(tchans: int | None = None, df: Any = <Quantity 2.79396772 Hz>, dt: Any = <Quantity 18.25361101 s>, fch1: Any = <Quantity 6. GHz>, ascending: bool = False, data: ndarray | None = None, seed: Any = None, **kwargs: Any) → None[source]

Initialize a one-channel time-series frame.

Parameters:

tchans – Number of time channels.
df – Frequency resolution.
dt – Time resolution.
fch1 – Frequency of the first channel.
ascending – Whether the frequency axis is ascending.
data – Optional preloaded time series.
seed – Random seed or generator.
**kwargs – Additional frame-construction keyword arguments.

array(db: bool = False) → ndarray[source]

Return the time series as a one-dimensional array.

Parameters:: db – Whether to convert intensities to dB.
Returns:: One-dimensional time-series array.

plot(ttype: str = 'trel', norm: bool = False, db: bool = False, minor_ticks: bool = False, **kwargs: Any) → None[source]

Plot the time series.

Parameters:

ttype – Time-axis display mode.
norm – Whether to normalize the time series to mean one before plotting.
db – Whether to convert intensities to dB.
minor_ticks – Whether to enable minor ticks.
**kwargs – Additional matplotlib.pyplot.plot() keyword arguments.

normalize() → None[source]: Normalize the time series to unit mean.

autocorr(remove_spike: bool = False) → ndarray[source]

Calculate the normalized autocorrelation of the time series.

Parameters:: remove_spike – Whether to replace the zero-lag spike with the first nonzero lag.
Returns:: Normalized autocorrelation sequence.

acf(remove_spike: bool = False) → ndarray[source]

Alias for autocorr().

Parameters:: remove_spike – Whether to replace the zero-lag spike.
Returns:: Normalized autocorrelation sequence.

setigen.dedrift module

setigen.dedrift.dedrift(fr: Frame, drift_rate: float | None = None) → Frame[source]

De-drift a frame using an explicit or metadata-provided drift rate.

This operation aligns drifting signals relative to the center of the frame. Signals near the frequency edges may be truncated by the resulting shift.

Parameters:

fr – Input frame to de-drift.
drift_rate – Drift rate in Hz/s. When omitted, the function looks for "drift_rate" in fr.metadata.

Returns:

New frame with the drift removed.

Raises:

KeyError – If no drift rate is provided or stored in the frame metadata.
ValueError – If the requested drift rate would shift the signal beyond the frame width.

setigen.split_utils module

setigen.split_utils.split_waterfall_generator(waterfall_fn: str | PathLike[str], fchans: int, tchans: int | None = None, f_shift: int | None = None) → Iterator[Waterfall][source]

Yield smaller waterfall views split from a larger filterbank file.

Parameters:

waterfall_fn – Input filterbank filename.
fchans – Number of frequency samples per split.
tchans – Optional number of time samples to include.
f_shift – Optional shift in frequency bins between splits.

Yields:

Waterfall views covering smaller sections of the input.

Raises:

ValueError – If tchans exceeds the available number of time samples.

setigen.split_utils.split_fil(waterfall_fn: str | PathLike[str], output_dir: str | PathLike[str], fchans: int, tchans: int | None = None, f_shift: int | None = None) → list[Path][source]

Split a filterbank file into smaller .fil files.

Parameters:

waterfall_fn – Input filterbank filename.
output_dir – Directory for the new filterbank files.
fchans – Number of frequency samples per split file.
tchans – Optional number of time samples to include.
f_shift – Optional shift in frequency bins between splits.

Returns:

Paths to the new filterbank files.

setigen.split_utils.split_array(data: ndarray, f_sample_num: int | None = None, t_sample_num: int | None = None, f_shift: int | None = None, t_shift: int | None = None, f_trim: bool = False, t_trim: bool = False) → ndarray[source]

Split an array into smaller frequency-time windows.

Parameters:

data – Two-dimensional time-frequency data array.
f_sample_num – Number of frequency samples per split.
t_sample_num – Number of time samples per split.
f_shift – Shift in frequency bins between splits.
t_shift – Shift in time bins between splits.
f_trim – Whether to drop splits with incomplete frequency width.
t_trim – Whether to drop splits with incomplete time height.

Returns:

Array of split time-frequency windows.

Raises:

ValueError – If the input is not an ndarray or an invalid shift is supplied.

setigen.normalize module

Normalize data using sigma-clipped background statistics.

Parameters:

fr – Input frame or array to normalize.
axis – Optional axis along which to normalize.
background – Optional background frame or array used for statistics.

Returns:

Normalized data with the same container type as the input.

setigen.normalize.sliding_norm(data: ndarray, cols: int = 0, exclude: float = 0.0, db: bool = False, use_median: bool = False) → ndarray[source]

Normalize data per frequency channel using a sliding window.

Parameters:

data – Time-frequency data array.
cols – Number of columns on either side of the current frequency bin.
exclude – Fraction of brightest samples to exclude.
db – Whether to convert data to dB before normalization.
use_median – Whether to use median and MAD instead of mean and standard deviation.

Returns:

Normalized data array.

setigen.normalize.blimpy_clip(data: ndarray, exclude: float = 0) → ndarray[source]

Clip the brightest fraction of samples from a data array.

Parameters:

data – Time-frequency data array.
exclude – Fraction of brightest samples to exclude.

Returns:

Clipped one-dimensional data array.

setigen.normalize.max_norm(data: ndarray) → ndarray[source]

Normalize data by its maximum value.

Parameters:: data – Time-frequency data array.
Returns:: Maximum-normalized data.

setigen.distributions module

setigen.distributions.fwhm(sigma: float) → float[source]

Return the Gaussian full width at half maximum.

Parameters:: sigma – Gaussian standard deviation.
Returns:: Full width at half maximum.

Sample from a Gaussian distribution.

Parameters:

x_mean – Mean of the distribution.
x_std – Standard deviation of the distribution.
shape – Output shape.
seed – Random seed or generator.

Returns:

Sampled Gaussian array.

Sample from a Gaussian distribution with a lower bound.

Parameters:

x_mean – Mean of the distribution.
x_std – Standard deviation of the distribution.
x_min – Lower bound for returned values.
shape – Output shape.
seed – Random seed or generator.

Returns:

Lower-bounded Gaussian array.

Sample a chi-squared distribution scaled to a target mean.

Parameters:

x_mean – Target mean of the scaled distribution.
chi2_df – Degrees of freedom.
shape – Output shape.
seed – Random seed or generator.

Returns:

Chi-squared noise array.

setigen.waterfall_utils module

setigen.waterfall_utils.max_freq(waterfall: str | PathLike[str] | Waterfall) → float[source]

Return the highest channel-center frequency in a waterfall.

Parameters:: waterfall – Filterbank filename or waterfall object.
Returns:: Maximum frequency in the data.

setigen.waterfall_utils.min_freq(waterfall: str | PathLike[str] | Waterfall) → float[source]

Return the lowest channel-center frequency in a waterfall.

Parameters:: waterfall – Filterbank filename or waterfall object.
Returns:: Minimum frequency in the data.

setigen.waterfall_utils.get_data(waterfall: str | PathLike[str] | Waterfall, db: bool = False) → ndarray[source]

Return waterfall data as a two-dimensional array.

Parameters:

waterfall – Filterbank filename or waterfall object.
db – Whether to convert intensities to dB.

Returns:

Time-frequency data array.

Raises:

ValueError – If the waterfall input type is unsupported.

setigen.waterfall_utils.get_fs(waterfall: str | PathLike[str] | Waterfall) → ndarray[source]

Return waterfall frequency values.

Parameters:: waterfall – Filterbank filename or waterfall object.
Returns:: Frequency axis in MHz.
Raises:: ValueError – If the waterfall input type is unsupported.

setigen.waterfall_utils.get_ts(waterfall: str | PathLike[str] | Waterfall) → ndarray[source]

Return waterfall time values.

Parameters:: waterfall – Filterbank filename or waterfall object.
Returns:: Time axis in seconds relative to the start.
Raises:: ValueError – If the waterfall input type is unsupported.

setigen.sample_from_obs module

Sample Gaussian parameters from empirical distributions.

Parameters:

x_mean_array – Candidate distribution means.
x_std_array – Candidate distribution standard deviations.
x_min_array – Optional candidate lower bounds.
seed – Random seed or generator.

Returns:

Tuple containing sampled mean and standard deviation, plus minimum when x_min_array is provided.

setigen.sample_from_obs.get_parameter_distributions(waterfall_fn: str | PathLike[str], fchans: int, tchans: int | None = None, f_shift: int | None = None) → tuple[ndarray, ndarray, ndarray][source]

Estimate empirical noise-parameter distributions from observations.

Parameters:

waterfall_fn – Input filterbank filename.
fchans – Number of frequency samples per split frame.
tchans – Optional number of time samples to include.
f_shift – Optional shift in frequency bins between splits.

Returns:

Arrays of empirical means, standard deviations, and minima.

setigen.sample_from_obs.get_mean_distribution(waterfall_fn: str | PathLike[str], fchans: int, tchans: int | None = None, f_shift: int | None = None) → ndarray[source]

Estimate an empirical distribution of mean intensities.

Parameters:

waterfall_fn – Input filterbank filename.
fchans – Number of frequency samples per split frame.
tchans – Optional number of time samples to include.
f_shift – Optional shift in frequency bins between splits.

Returns:

Array of empirical mean intensities.

setigen.unit_utils module

This module contains a couple unit conversion utilities used in frame.Frame.

In general, we rely on astropy units for conversions, and note that float values are assumed to be in SI units (e.g. Hz, s).

setigen.unit_utils.cast_value(value: float | Quantity, unit: UnitBase) → Quantity[source]

Cast a scalar value into the requested astropy unit.

Parameters:

value – Numeric scalar or quantity to cast.
unit – Destination unit.

Returns:

Value expressed as an astropy quantity in unit.

setigen.unit_utils.get_value(value: float | Quantity, unit: UnitBase | None = None) → float[source]

Extract a float from a scalar or astropy quantity.

Parameters:

value – Numeric scalar or quantity to unwrap.
unit – Optional unit to convert into before extracting the numeric value.

Returns:

Floating-point value in the requested unit when provided.