lightcurvelynx.astro_utils.passbands

The Passband and PassbandGroup objects store information about the filters used to convert flux densities (as a function of wavelength) to bandfluxes. They also provide methods for loading and manipulating passband data.

Attributes

logger

Classes

`PassbandGroup`	A group of passbands.
`Passband`	A passband contains information about its transmission curve and calculates its normalization.

Module Contents

logger[source]

class PassbandGroup(given_passbands, filters=None, **kwargs)[source]

A group of passbands.

The given passbands can come from a single survey or multiple surveys. As such, a given filter may appear in multiple passbands in a passband group. For example we might generate data from a combination of Rubin and DECCAM and want to use both their r filters. Thus the primary mapping is done by the passband’s full name “{SURVEY}_{FILTER}”. Lookups by filter name are permitted in cases where the filter only occurs once in the group and thus the desired passband is unambiguous.

passbands[source]

A dictionary of Passband objects, where the keys are the full_names of the passbands (eg, “LSST_u”).

Type:: dict of Passband

table_dir

The path to the directory containing the passband tables.

Type:: str

waves

The union of all wavelengths in the passbands.

Type:: np.ndarray

_in_band_wave_indices[source]

A dictionary mapping the passband name (eg, “LSST_u”) to the indices of that specific passband’s wavelengths in the full waves list.

Type:: dict

_filter_to_name[source]

A dictionary mapping the filter name to a list of matching passband full names.

Type:: dict

passbands[source]

__str__() → str[source]: Return a string representation of the PassbandGroup.

__len__() → int[source]

__getitem__(key)[source]: Return the passband corresponding to a full name or filter name.

__contains__(key) → bool[source]

__iter__()[source]

property filters: list[source]: Return a list of filter names in the passband group.

classmethod from_preprocessed_file(file_path: str | pathlib.Path, **kwargs) → PassbandGroup[source]

Load a PassbandGroup from a single file containing multiple preprocessed passbands.

The file should be a CSV file with columns: survey, filter_name, wavelength, transmission. The wavelengths should be in Angstroms.

Parameters:

file_path (str or Path) – The path to the file containing the passband data.
**kwargs – Additional keyword arguments to pass to the Passband constructor.

Returns:

A PassbandGroup object containing the passbands from the file.

Return type:

PassbandGroup

Load the passbands from a directory where the directorty name corresponds to the survey and the file names correspond to the filters: path_to_survey_dir/survey_name/filter_name.dat

Parameters:

dir_path (str or Path) – The path to the passband files including the survey directory.
filters (list, optional) – A list of filters to include in this PassbandGroup. If None, includes all filters. Otherwise drops filters that do not occur and throws an error if a filter is missing. Used for loading a subset of the filters.
delta_wave (float or None, optional) – The grid step of the wave grid, in angstroms. It is typically used to downsample transmission using linear interpolation. Default is 5 angstroms. If None the original grid is used.
trim_quantile (float or None, optional) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of the area under the transmission curve.
units (Literal['nm','A'], optional) – Denotes whether the wavelength units of the table are nanometers (‘nm’) or Angstroms (‘A’). By default ‘A’. Does not affect the output units of the class, only the interpretation of the provided passband table.

classmethod from_preset(preset: str, *, table_dir=None, filters=None, **kwargs) → PassbandGroup[source]

Create a passband group from a pre-defined set of passbands.

Parameters:

preset (str) – The name of the pre-defined set of passbands to load.
table_dir (str, optional) – The path to the directory in which to store cached passband tables. If the passband exists in this directory, it will be loaded from there; otherwise it will be downloaded and saved in that directory. The full path to the tables will be {table_dir}/{survey}/{filter_name}.dat.
filters (list, optional) – A list of filters to include in this PassbandGroup. If None, includes all filters. Otherwise drops filters that do not occur and throws an error if a filter is missing. Used for loading a subset of the filters.
**kwargs – Additional keyword arguments to pass to the Passband constructor.

classmethod from_svo(all_filters: list[str], *, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001, **kwargs) → PassbandGroup[source]

Create a PassbandGroup object from the SVO Filter Profile Service given a list of full filter names in the form of “{FACILITY}/{INSTRUMENT}.{FILTER}” or a single string of the form “{FACILITY}/{INSTRUMENT}” to download all filters.

References

This research has made use of the SVO Filter Profile Service “Carlos Rodrigo”, funded by MCIN/AEI/10.13039/501100011033/ through grant PID2023-146210NB-I00 * Rodrigo, C., Cruz, P., Aguilar, J.F., et al. 2024; https://ui.adsabs.harvard.edu/abs/2024A%26A…689A..93R/abstract * Rodrigo, C., Solano, E., Bayo, A., 2012; https://ui.adsabs.harvard.edu/abs/2012ivoa.rept.1015R/abstract * Rodrigo, C., Solano, E., 2020; https://ui.adsabs.harvard.edu/abs/2020sea..confE.182R/abstract

Parameters:

all_filters (str or list[str]) – A string of the form “{FACILITY}/{INSTRUMENT}” to download all filters for a given facility and instrument or a list of full filter names to load from the SVO Filter Profile Service in the FORM “{FACILITY}/{INSTRUMENT}.{FILTER}” to download a subset of filters. If a list is provided, it can include filters from multiple surveys.
delta_wave (float or None, optional) – The grid step of the wave grid, in angstroms. It is typically used to downsample transmission using linear interpolation. Default is 5 angstroms. If None the original grid is used.
trim_quantile (float or None, optional) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of the area under the transmission curve.
**kwargs – Additional keyword arguments to pass to the Passband constructor.

add_passband(passband) → None[source]

Manually add a passband to the group.

Parameters:: passband (Passband) – The passband to add to the group.

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

Get the minimum and maximum wavelength for this group.

Returns:

min_wave (float) – The minimum wavelength.
max_wave (float) – The maximum wavelength.

mask_by_filter(filters) → numpy.ndarray[source]

Compute a mask for whether a given observations is of interest for for a given analysis. For example this could be used to remove unneeded observations from an ObsTable.

Parameters:: filters (list-like) – A length T array of filter names or full names.
Returns:: mask – A length T array of Booleans indicating whether the filter is of interest.
Return type:: numpy.ndarray

process_transmission_tables(*, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001) → None[source]

Process the transmission tables for all passbands in the group; recalculate group’s wave attribute. This function is used to change the preprocessing of the transmission tables after the PassbandGroup has been initialized, such as using different delta_wave or trim_quantile values.

Parameters:

delta_wave (float or None, optional) – The grid step of the wave grid. Default is 5.0.
trim_quantile (float or None, optional) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of rows.

fluxes_to_bandflux(flux_density_matrix: numpy.ndarray, filter: str) → numpy.ndarray[source]

Calculate bandfluxes for a single passband in the group.

Parameters:

flux_density_matrix (np.ndarray) – A 2D array of flux densities where of shape T x W where the rows are times and columns are wavelengths.
filter (str) – The name of the filter to evaluate.

Returns:

bandflux – A length T array of bandfluxes for the given passband.

Return type:

np.ndarray

fluxes_to_bandfluxes(flux_density_matrix: numpy.ndarray) → numpy.ndarray[source]

Calculate bandfluxes for all passbands in the group.

Parameters:: flux_density_matrix (np.ndarray) – A 2D array of flux densities where of shape T x W where the rows are times and columns are wavelengths.
Returns:: A dictionary of bandfluxes with passband full names as keys and np.ndarrays of bandfluxes as values.
Return type:: dict of np.ndarray

to_file(file_path: str | pathlib.Path, *, overwrite: bool = False) → None[source]: Save the entire passband group to a single file.

plot(*, ax=None, figure=None, plot_transmission=False) → None[source]

Plot the PassbandGroup on a single plot.

Parameters:

ax (matplotlib.pyplot.Axes or None, optional) – Axes, None by default.
figure (matplotlib.pyplot.Figure or None) – Figure, None by default.
plot_transmission (bool) – Whether to plot the original transmission table instead of the normalized system response. Default is False, which plots the normalized system response.

class Passband(table_values: numpy.array, survey: str, filter_name: str, *, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001, units: Literal['nm', 'A'] | None = 'A')[source]

A passband contains information about its transmission curve and calculates its normalization.

survey[source]

The survey to which the passband belongs: eg, “LSST”.

Type:: str

filter_name[source]

The name of the passband’s filter: eg, “u”.

Type:: str

full_name[source]

The full name of the passband. This is the survey and filter concatenated: eg, “LSST_u”.

Type:: str

waves

The wavelengths of the transmission table in Angstroms. To be used when evaluating models to generate fluxes that will be passed to fluxes_to_bandflux.

Type:: np.ndarray

delta_wave[source]

The grid step of the wave grid, in angstroms, if the table is a uniform grid. The value is None if the grid is not uniform.

Type:: float or None

transmission_table[source]

A 2D array of wavelengths and transmissions. This is the system throughput table loaded from the file, and is neither interpolated nor normalized.

Type:: np.ndarray

normalized_system_response

A 2D array where the first col is wavelengths (Angstrom) and the second col is transmission values. This table is both interpolated to the _wave_grid and normalized to calculate phi_b(λ).

Type:: np.ndarray

survey[source]

filter_name[source]

full_name[source]

delta_wave = 5.0[source]

transmission_table[source]

__str__() → str[source]: Return a string representation of the Passband.

__eq__(other) → bool[source]: Determine if two passbands have equal values for the processed tables.

classmethod from_file(survey: str, filter_name: str, *, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001, table_path: str | pathlib.Path | None = None, table_url: str | None = None, units: Literal['nm', 'A'] | None = 'A', force_download: bool = False) → Passband[source]

Construct a Passband object from a file, downloading it if needed.

Parameters:

survey (str) – The survey to which the passband belongs: eg, “LSST”.
filter_name (str) – The filter_name of the passband: eg, “u”.
delta_wave (float or None, optional) – The grid step of the wave grid, in angstroms. It is typically used to downsample transmission using linear interpolation. Default is 5 angstroms. If None the original grid is used.
trim_quantile (float or None, optional) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of the area under the transmission curve.
table_path (str, optional) – The path to the transmission table file. If None, the table path will be set to a default path; if no file exists at this location, the file will be downloaded from table_url.
table_url (str, optional) – The URL to download the transmission table file. If None, the table URL will be set to a default URL based on the survey and filter_name. Default is None.
units (Literal['nm','A'], optional) – Denotes whether the wavelength units of the table are nanometers (‘nm’) or Angstroms (‘A’). By default ‘A’. Does not affect the output units of the class, only the interpretation of the provided passband table.
force_download (bool, optional) – If True, the transmission table will be downloaded even if it already exists locally. Default is False.

classmethod from_sncosmo(survey: str, filter_name: str, bandpass=None, **kwargs) → Passband[source]

Create a Passband object from an sncosmo.Bandpass object.

Parameters:

survey (str) – The survey to which the passband belongs: eg, “LSST”.
filter_name (str) – The filter_name of the passband: eg, “u”.
bandpass (sncosmo.Bandpass or str) – The bandpass object from which to create the Passband object.
**kwargs – Additional keyword arguments (unused)

References

snocosmo.Bandpass: https://sncosmo.readthedocs.io/en/stable/api/sncosmo.Bandpass.html

classmethod from_svo(full_filter_name, *, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001, **kwargs) → Passband[source]

Create a Passband object from the SVO [1], [2], [3] Filter Profile Service.

References

Parameters:

full_filter_name (str) – The full name of the survey and filter in the SVO database in the form of “{FACILITY}/{INSTRUMENT}.{FILTER}”, e.g., “SLOAN/SDSS.u”.
delta_wave (float or None, optional) – The grid step of the wave grid, in angstroms. It is typically used to downsample transmission using linear interpolation. Default is 5 angstroms. If None the original grid is used.
trim_quantile (float or None, optional) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of the area under the transmission curve.
force_download (bool, optional) – If True, the transmission table will be downloaded even if it already exists locally. Default is False.
**kwargs – Additional keyword arguments to pass to the Passband constructor.

static load_transmission_table(table_path: str | pathlib.Path, *, wave_units: Literal['nm', 'A'] = 'A', **kwargs) → numpy.ndarray[source]

Load a transmission table from a file in either VOTable of ASCII format.

ASCII tables must have 2 columns: wavelengths and transmissions; wavelengths must be strictly increasing.

Parameters:

table_path (str or Path) – The path to the transmission table file.
wave_units (Literal['nm','A'], optional) – Denotes whether the wavelength units of the table are nanometers (‘nm’) or Angstroms (‘A’). By default ‘A’. Does not affect the output units of the class, only the interpretation of the provided passband table.
**kwargs (dict) – Additional keyword arguments to pass to the reader method.

Returns:

A 2D array of wavelengths (in Angstroms) and transmissions.

Return type:

np.ndarray

process_transmission_table(*, delta_wave: float | None = 5.0, trim_quantile: float | None = 0.001) → None[source]

Process the transmission table, transforming it to the desired wave grid and and computing a normalized system response from the throughput table.

Parameters:

delta_wave (Optional[float] = 5.0) – The grid step in Angstroms of the wave grid. Default is 5.0 Angstroms.
trim_quantile (Optional[float] = 1e-3) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of rows.

static interpolate_transmission_table(table: numpy.ndarray, delta_wave: float | None) → numpy.ndarray[source]

Interpolate the transmission table to a new wave grid.

Parameters:

table (np.ndarray) – A 2D array of wavelengths (in Angstroms) and transmissions.
delta_wave (float or None) – The grid step in Angstroms of the wave grid.

Returns:

The 2D interpolated array of wavelengths (in Angstroms) and transmissions.

Return type:

np.ndarray

static trim_transmission_by_quantile(table: numpy.ndarray, trim_quantile: float | None) → numpy.ndarray[source]

Trim the transmission table so that it only includes the central (100 - 2*trim_quartile)% of rows.

E.g., if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of rows.

Parameters:

table (np.ndarray) – A 2D array of wavelengths (in Angstroms) and transmissions.
trim_quantile (float) – The quantile to trim the transmission table by. For example, if trim_quantile is 1e-3, the transmission table will be trimmed to include only the central 99.8% of rows. Must be greater than or equal to 0 and less than 0.5.

Returns:

A 2D array of wavelengths (in Angstroms) and transmissions.

Return type:

np.ndarray

static compute_system_response_table(transmission_table: numpy.ndarray) → numpy.ndarray[source]

Calculate the value of phi_b for all wavelengths in a transmission table.

This is eq. 8 from “On the Choice of LSST Flux Units” (Ivezić et al.):

φ_b(λ) = S_b(λ)λ⁻¹ / ∫ S_b(λ)λ⁻¹ dλ

where S_b(λ) is the system response of the passband. Note we use transmission table as our S_b(λ).

Parameters:: transmission_table (np.ndarray) – A 2D array of wavelengths (in Angstroms) and throughput values.
Returns:: A 2D array of wavelengths (in Angstroms) and normalized system response values.
Return type:: np.ndarray
Raises:: ValueError – If the transmission table is the wrong size or the calculated denominator is zero.

fluxes_to_bandflux(flux_density_matrix: numpy.ndarray) → numpy.ndarray[source]

Calculate the bandflux for a given set of flux densities.

This is eq. 7 from “On the Choice of LSST Flux Units” (Ivezić et al.):

F_b = ∫ f(λ)φ_b(λ) dλ

where f(λ) is the flux density of an object at the top of the atmosphere, and φ_b(λ) is the normalized system response for given band b.”

Parameters:: flux_density_matrix (np.ndarray) – A 2D or 3D array of flux densities. If the array is 2D it contains a single sample where the rows are the T times and columns are M wavelengths in Angstroms. If the array is 3D it contains S samples and the values are indexed as (sample_num, time, wavelength).
Returns:: bandfluxes – A 1D or 2D array. If the flux_density_matrix contains a single sample (2D input) then the function returns a 1D length T array where each element is the bandflux at the corresponding time. Otherwise the function returns a size S x T array where each entry corresponds to the value for a given sample at a given time.
Return type:: np.ndarray

plot(*, ax=None, figure=None, color=None, plot_transmission=False) → None[source]

Plot the passband.

Parameters:

ax (matplotlib.pyplot.Axes or None, optional) – Axes, None by default.
figure (matplotlib.pyplot.Figure or None) – Figure, None by default.
color (str or None, optional) – The color of the curve.
plot_transmission (bool) – Plot the loaded transmission table instead of the normalized system response. Default is False (which plots the normalized system response).