Bandpass Filters

class galsim.Bandpass(throughput, wave_type, blue_limit=None, red_limit=None, zeropoint=None, interpolant='linear', _wave_list=None, _tp=None)[source]

Simple bandpass object, which models the transmission fraction of incident light as a function of wavelength, for either an entire optical path (e.g., atmosphere, reflecting and refracting optics, filters, CCD quantum efficiency), or some intermediate piece thereof. Bandpasses representing individual components may be combined through the * operator to form a new Bandpass object representing the composite optical path.

Bandpasses are callable, returning dimensionless throughput as a function of wavelength in nm.

Bandpasses are immutable; all transformative methods return new Bandpasses, and leave their originating Bandpasses unaltered.

Bandpasses require blue_limit and red_limit attributes, which may either be explicitly set at initialization, or are inferred from the initializing LookupTable or 2-column file.

Outside of the wavelength interval between blue_limit and red_limit, the throughput is returned as zero, regardless of the throughput input parameter.

Bandpasses may be multiplied by other Bandpasses, functions, scalars, or SED instances. The product of a Bandpass with an SED is a new SED.

The Bandpass effective wavelength is stored in the python property effective_wavelength. We use throughput-weighted average wavelength (which is independent of any SED) as our definition for effective wavelength.

For Bandpasses defined using a LookupTable, a numpy.array of wavelengths, wave_list, defining the table is maintained. Bandpasses defined as products of two other Bandpasses will define their wave_list as the union of multiplicand wave_list values, although limited to the range between the new product blue_limit and red_limit. (This implementation detail may affect the choice of integrator used to draw a ChromaticObject.)

The input parameter, throughput, may be one of several possible forms:

  1. a regular python function (or an object that acts like a function)

  2. a LookupTable

  3. a file from which a LookupTable can be read in

  4. a string which can be evaluated to a function of wave via eval('lambda wave : '+throughput), e.g.:

    throughput = '0.8 + 0.2 * (wave-800)'

The argument of throughput will be the wavelength in units specified by wave_type. (See below.) The output should be the dimensionless throughput at that wavelength. (Note we use wave rather than lambda, since lambda is a python reserved word.)

The argument wave_type specifies the units to assume for wavelength and must be one of ‘nm’, ‘nanometer’, ‘nanometers’, ‘A’, ‘Ang’, ‘Angstrom’, or ‘Angstroms’, or an astropy distance unit. (For the string values, case is unimportant.) If given, blue_limit and red_limit are taken to be in these units as well.

Note that the wave_type parameter does not propagate into other methods of Bandpass. For instance, Bandpass.__call__ assumes its input argument is in nanometers.

Finally, a Bandpass may have zeropoint attribute, which is a float used to convert flux (in photons/s/cm^2) to magnitudes:

mag = -2.5*log10(flux) + zeropoint

You can either set the zeropoint at initialization, or via the withZeropoint method. Note that the zeropoint attribute does not propagate if you get a new Bandpass by multiplying or dividing an old Bandpass.

Parameters:

  • throughput – Function defining the throughput at each wavelength. See above for valid options for this parameter.

  • wave_type – The units to use for the wavelength argument of the throughput function. See above for details.

  • blue_limit – Hard cut off of bandpass on the blue side. [default: None, but required if throughput is not a LookupTable or file. See above.]

  • red_limit – Hard cut off of bandpass on the red side. [default: None, but required if throughput is not a LookupTable or file. See above.]

  • zeropoint – Set the zero-point for this Bandpass. Here, this can only be a float value. See the method withZeropoint for other options for how to set this using a particular spectrum (AB, Vega, etc.) [default: None]

  • interpolant – If reading from a file, what interpolant to use. [default: ‘linear’]

__call__(wave)[source]

Return dimensionless throughput of bandpass at given wavelength in nanometers.

Note that outside of the wavelength range defined by the blue_limit and red_limit attributes, the throughput is assumed to be zero.

Parameters:

wave – Wavelength in nanometers. (Either a scalar or a numpy array)

Returns:

the dimensionless throughput.

calculateEffectiveWavelength(precise=False)[source]

Calculate, store, and return the effective wavelength for this bandpass.

We define the effective wavelength as the throughput-weighted average wavelength, which is SED-independent. Units are nanometers.

Parameters:

precise – Optionally use a more precise integration method when the bandpass uses a LookupTable rather than the normal trapezoid rule. [default: False]

property effective_wavelength

The effective wavelength of the Bandpass.

An alias for self.calculateEffectiveWavelength().

thin(rel_err=0.0001, trim_zeros=True, preserve_range=True, fast_search=True, preserve_zp=True)[source]

Thin out the internal wavelengths of a Bandpass that uses a LookupTable.

If the bandpass was initialized with a LookupTable or from a file (which internally creates a LookupTable), this function removes tabulated values while keeping the integral over the set of tabulated values still accurate to the given relative error.

That is, the integral of the bandpass function is preserved to a relative precision of rel_err, while eliminating as many internal wavelength values as possible. This process will usually help speed up integrations using this bandpass. You should weigh the speed improvements against your fidelity requirements for your particular use case.

By default, this routine will preserve the zeropoint of the original bandpass by assigning it to the new thinned bandpass. The justification for this choice is that when using an AB zeropoint, a typical optical bandpass, and the default thinning rel_err value, the zeropoint for the new and thinned bandpasses changes by 10^-6. However, if you are thinning a lot, and/or want to do extremely precise tests, you can set preserve_zp=False and then recalculate the zeropoint after thinning.

Parameters:

  • rel_err – The relative error allowed in the integral over the throughput function. [default: 1.e-4]

  • trim_zeros – Remove redundant leading and trailing points where f=0? (The last leading point with f=0 and the first trailing point with f=0 will be retained). Note that if both trim_leading_zeros and preserve_range are True, then the only the range of x after zero trimming is preserved. [default: True]

  • preserve_range – Should the original range (blue_limit and red_limit) of the Bandpass be preserved? (True) Or should the ends be trimmed to include only the region where the integral is significant? (False) [default: True]

  • fast_search – If set to True, then the underlying algorithm will use a relatively fast O(N) algorithm to select points to include in the thinned approximation. If set to False, then a slower O(N^2) algorithm will be used. We have found that the slower algorithm tends to yield a thinned representation that retains fewer samples while still meeting the relative error requirement, and may also be somewhat more robust when computing an SED flux through a Bandpass when a significant fraction of the integrated flux passes through low throughput bandpass light leaks. [default: True]

  • preserve_zp – If True, the new thinned Bandpass will be assigned the same zeropoint as the original. If False, the new thinned Bandpass will have a zeropoint of None. [default: True]

Returns:

the thinned Bandpass.

truncate(blue_limit=None, red_limit=None, relative_throughput=None, preserve_zp='auto')[source]

Return a bandpass with its wavelength range truncated.

This function truncate the range of the bandpass either explicitly (with blue_limit or red_limit or both) or automatically, just trimming off leading and trailing wavelength ranges where the relative throughput is less than some amount (relative_throughput).

This second option using relative_throughput is only available for bandpasses initialized with a LookupTable or from a file, not when using a regular python function or a string evaluation.

This function does not remove any intermediate wavelength ranges, but see thin() for a method that can thin out the intermediate values.

When truncating a bandpass that already has an assigned zeropoint, there are several possibilities for what should happen to the new (returned) bandpass by default. If red and/or blue limits are given, then the new bandpass will have no assigned zeropoint because it is difficult to predict what should happen if the bandpass is being arbitrarily truncated. If relative_throughput is given, often corresponding to low-level truncation that results in little change in observed quantities, then the new bandpass is assigned the same zeropoint as the original. This default behavior is called ‘auto’. The user can also give boolean True or False values.

Parameters:

  • blue_limit – Truncate blue side of bandpass at this wavelength in nm. [default: None]

  • red_limit – Truncate red side of bandpass at this wavelength in nm. [default: None]

  • relative_throughput – Truncate leading or trailing wavelengths that are below this relative throughput level. (See above for details.) Either blue_limit and/or red_limit should be supplied, or relative_throughput should be supplied – but relative_throughput should not be combined with one of the limits. [default: None]

  • preserve_zp – If True, the new truncated Bandpass will be assigned the same zeropoint as the original. If False, the new truncated Bandpass will have a zeropoint of None. If ‘auto’, the new truncated Bandpass will have the same zeropoint as the original when truncating using relative_throughput, but will have a zeropoint of None when truncating using ‘blue_limit’ and/or ‘red_limit’. [default: ‘auto’]

Returns:

the truncated Bandpass.

withZeropoint(zeropoint)[source]

Assign a zeropoint to this Bandpass.

A bandpass zeropoint is a float used to convert flux (in photons/s/cm^2) to magnitudes:

mag = -2.5*log10(flux) + zeropoint

Note that the zeropoint attribute does not propagate if you get a new Bandpass by multiplying or dividing an old Bandpass.

The zeropoint argument can take a variety of possible forms:

  1. a number, which will be the zeropoint

  2. a galsim.SED. In this case, the zeropoint is set such that the magnitude of the supplied SED through the Bandpass is 0.0

  3. the string ‘AB’. In this case, use an AB zeropoint.

  4. the string ‘Vega’. Use a Vega zeropoint.

  5. the string ‘ST’. Use a HST STmag zeropoint.

Parameters:

zeropoint – See above for valid input options

Returns:

new Bandpass with zeropoint set.