synthesizer.instruments.filters¶

A module holding all photometric transmission filter functionality.

There are two main types of filter object in Synthesizer. Indivdual filters described by a Filter object and Filters grouped into a FilterCollection. These objects house all the functionality for working with filters with and without a grid object.

Example usage:

filt = Filter("generic/filter.1", transmission=trans, new_lam=lams)
filt = Filter("top_hat/filter.1", lam_min=3000, lam_max=5500)
filt = Filter("top_hat/filter.2", lam_eff=7000, lam_fwhm=2000)
filt = Filter("JWST/NIRCam.F200W", new_lam=lams)
filters = FilterCollection(
    filter_codes=fs,
    tophat_dict=tophats,
    generic_dict=generics,
    new_lam=lams
)

Functions

synthesizer.instruments.filters.UVJ(new_lam=None)[source]¶

Return a FilterCollection of UVJ top hat filters.

Parameters:

new_lam (array-like, float) – The wavelength array for which each filter’s transmission curve is defined.

Returns:

FilterCollection: A FilterCollection containing top hat UVJ filters.

Classes

class synthesizer.instruments.filters.Filter(filter_code, transmission=None, lam_min=None, lam_max=None, lam_eff=None, lam_fwhm=None, new_lam=None, hdf=None)[source]¶

A container for a filter’s transmission curve and wavelength array.

A filter can either be retrieved from the SVO database, made from specific top hat filter properties, or made from a generic filter transmission curve and wavelength array.

Also contains methods for calculating basic filter properties taken from here (page 42 (5.1))

filter_code¶

The full name defining this Filter.

Type:: string

observatory¶

The name of the observatory

Type:: string

instrument¶

The name of the instrument.

Type:: string

filter_¶

The name of the filter.

Type:: string

filter_type¶

A string describing the filter type: “SVO”, “TopHat”, or “Generic”.

Type:: string

lam_min¶

If a top hat filter: The minimum wavelength where transmission is nonzero.

Type:: Quantity

lam_max¶

If a top hat filter: The maximum wavelength where transmission is nonzero.

Type:: Quantity

lam_eff¶

If a top hat filter: The effective wavelength of the filter curve.

Type:: Quantity

lam_fwhm¶

If a top hat filter: The FWHM of the filter curve.

Type:: Quantity

svo_url¶

If an SVO filter: the url from which the data was extracted.

Type:: string

t¶

The transmission curve.

Type:: array-like, float

lam¶

The wavelength array for which the transmission is defined.

Type:: Quantity, array-like, float

nu¶

The frequency array for which the transmission is defined. Derived from self.lam.

Type:: Quantity, array-like, float

original_lam¶

The original wavelength extracted from SVO. In a non-SVO filter self.original_lam == self.lam.

Type:: Quantity, array-like, float

original_nu¶

The original frequency derived from self.original_lam. In a non-SVO filter self.original_nu == self.nu.

Type:: Quantity, array-like, float

original_t¶

The original transmission extracted from SVO. In a non-SVO filter self.original_t == self.t.

Type:: array-like, float

Tpeak()[source]¶

Calculate the peak transmission.

For an SVO filter this uses the transmission from the database.

Returns:

float: The peak transmission.

apply_filter(arr, lam=None, nu=None, verbose=True, nthreads=1, integration_method='trapz')[source]¶

Apply the transmission curve to any array.

Applies this filter’s transmission curve to an arbitrary dimensioned array returning the sum of the array convolved with the filter transmission curve along the wavelength axis (final axis).

If no wavelength or frequency array is provided then the filters rest frame frequency is assumed.

To apply to llam or flam, wavelengths must be provided. To apply to lnu or fnu frequencies must be provided.

Parameters:

arr (array-like, float) – The array to convolve with the filter’s transmission curve. Can be any dimension but wavelength must be the final axis.
lam (unyt_array/array-like, float) – The wavelength array to integrate with respect to. Defaults to the rest frame frequency if neither lams or nus are provided.
nu – (unyt_array/array-like, float) The frequency array to integrate with respect to. Defaults to the rest frame frequency if neither lams or nus are provided.
verbose (bool) – Are we talking?
nthreads (int) – The number of threads to use in the integration. If -1 then all available threads are used. Defaults to 1.
integration_method (str) – The method to use in the integration. Can be either “trapz” or “simps”. Defaults to “trapz”.

Returns:

float: The array (arr) convolved with the transmission curve and summed along the wavelength axis.

Raises:

ValueError – If the shape of the transmission and wavelength array differ the convolution cannot be done.
InconsistentArguments – If integration_method is an incompatible option an error is raised.

bandw()[source]¶

Calculate the bandwidth.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The bandwidth.

clip_transmission()[source]¶

Clip transmission curve between 0 and 1.

Some transmission curves from SVO can come with strange upper limits, the way we use them requires the maxiumum of a transmission curve is at most 1. So for one final check lets clip the transmission curve between 0 and 1

fwhm()[source]¶

Calculate the FWHM.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The FWHM of the filter.

max()[source]¶

Calculate the longest wavelength with transmission >0.01.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The maximum wavelength at which transmission is nonzero.

meanwv()[source]¶

Calculate the mean wavelength.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: Mean wavelength.

min()[source]¶

Calculate the shortest wavelength with transmission >0.01.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The minimum wavelength at which transmission is nonzero.

mnmx()[source]¶

Calculate the minimum and maximum wavelengths.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The minimum wavelength.
float: The maximum wavelength.

pivT()[source]¶

Calculate the transmission at the pivot wavelength.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: Transmission at pivot wavelength.

pivwv()[source]¶

Calculate the pivot wavelength.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: Pivot wavelength.

rectw()[source]¶

Calculate the rectangular width.

For an SVO filter this uses the wavelength and transmission from the database.

Returns:

float: The rectangular width.

property transmission¶: Alias for self.t.

class synthesizer.instruments.filters.FilterCollection(filter_codes=None, tophat_dict=None, generic_dict=None, filters=None, path=None, new_lam=None, fill_gaps=True, verbose=True)[source]¶

A container for multiple Filter objects.

Holds a collection of filters (Filter objects) and enables various quality of life operations such as plotting, adding, looping, len, and comparisons as if the collection was a simple list.

Filters can be derived from the SVO database , specific top hat filter properties or generic filter transmission curves and a wavelength array.

All filters in the FilterCollection are defined in terms of the same wavelength array.

In addition to creating Filter`s from user defined arguments, a HDF5 file of a `FilterCollection can be created and later loaded at instantiation to load a saved FilterCollection.

filters¶

A list containing the individual Filter objects.

Type:: dict, Filter

filter_codes¶

A list of the names of each filter. For SVO filters these have to have the form “Observatory/Instrument.Filter” matching the database, but for all other filter types this can be an arbitrary label.

Type:: list, string

lam¶

The wavelength array for which each filter’s transmission curve is defined.

Type:: Quantity, array-like, float

nfilters¶

The number of filters in this collection.

Type:: int

mean_lams¶

The mean wavelength of each Filter in the collection.

Type:: Quantity, array-like, float

pivot_lams¶

The mean wavelength of each Filter in the collection.

Type:: Quantity, array-like, float

calc_mean_lams()[source]¶

Calculate the mean wavelengths of all filters in the FilterCollection.

Returns:

mean_lams (ndarray, float): An array containing the rest frame mean wavelengths of each filter in the same order as self.filter_codes.

calc_pivot_lams()[source]¶

Calculate the pivot wavelengths of all filters in the FilterCollection.

Returns:

pivot_lams (ndarray, float): An array containing the rest frame pivot wavelengths of each filter in the same order as self.filter_codes.

find_filter(rest_frame_lam, redshift=None, method='pivot')[source]¶

Return the filter containing the passed rest frame wavelength.

Takes a rest frame target wavelength and returns the filter that probes that wavelength.

If a redshift is provided then the wavelength is shifted into the observer frame and the filter that probes that wavelength in the observed frame is returned.

Three Methods are provided to decide which filter to return:

“pivot” (default) - The filter with the closest pivot wavelength: is returned.
“mean” - The filter with the closest mean wavelength is: returned.
“transmission” - The filter with the peak transmission at the: wavelength is returned.

Parameters:

rest_frame_lam (unyt_quantity) – The wavelength to find the nearest filter to.
redshift (float) – The redshift of the observation. None for rest_frame, defaults to None.
method (str) – The method to decide which filter to return. Either “pivot” (default), “mean”, or “transmission”.

Returns:

synthesizer.Filter: The closest Filter in this FilterCollection. The filter-code of this filter is also printed.

Raises:

WavelengthOutOfRange – If the passed wavelength is out of range of any of the filters then an error is thrown.

get_non_zero_lam_lims()[source]¶

Find the minimum and maximum wavelengths with non-zero transmission.

Returns:

unyt_quantity: Minimum wavelength with non-zero transmission.
unyt_quantity: Maximum wavelength with non-zero transmission.

plot_transmission_curves(show=False, fig=None, ax=None, **kwargs)[source]¶

Plot the transmission curves of all filters in the FilterCollection.

Parameters:

show (bool) – Are we showing the output?

Returns:

fig (matplotlib.Figure): The matplotlib figure object containing the plot.
ax obj (matplotlib.axis): The matplotlib axis object containg the plot.

resample_filters(new_lam=None, lam_size=None, fill_gaps=False, verbose=True)[source]¶

Resample all filters onto a single wavelength array.

If no wavelength grid is provided then the wavelength array of each individual Filter will be combined to cover the full range of the FilterCollection. Any overlapping ranges will take the values from one of the overlapping filters, any gaps between filters can be filled with the minimum average resolution of all filters to ensure a continuous array without needlessly inflating the memory footprint of any lam sized arrays.

Alternatively, if new_lam is not passed, lam_size can be passed in which case a wavelength array from the minimum Filter wavelength to the maximum Filter wavelength will be generated with lam_size wavelength bins.

Warning

If working with a Grid without passing the Grid wavelength array to a FilterCollection the wavelengths arrays will not agree producing at best array errors and at worst incorrect results from broadband photometry calculations.

Parameters:

new_lam (array-like, float) – Wavelength array on which to sample filters. Wavelengths should be in Angstrom. Defaults to None and an array is derived.
lam_size (int) – The desired number of wavelength bins in the new wavelength array, if no explicit array has been passed.
fill_gaps (bool) – Are we filling gaps in the wavelength array? Defaults to False.
verbose (bool) – Are we talking?

select(*filter_codes)[source]¶

Return a FilterCollection containing the filters with the given codes.

Parameters:: filter_codes (list, string) – The filter codes of the desired filters.

unify_with_grid(grid, loop_spectra=False)[source]¶

Unify a grid with this FilterCollection.

This will interpolate the grid onto the wavelength grid of this FilterCollection.

Parameters:

grid (object) – The grid to be unified with this FilterCollection.
loop_spectra (bool) – Flag for whether to do the interpolation over the whole grid, or loop over the first axes. The latter is less memory intensive, but slower. Defaults to False.

write_filters(path)[source]¶

Write the current state of the FilterCollection to a HDF5 file.

Parameters:: path (str) – The file path at which to save the FilterCollection.