`castor_etc.utils.conversions`

Unit conversion utilities

castor_etc.conversions provides utility methods to convert between different units and quantities.

Common units (also see https://pysynphot.readthedocs.io/en/latest/units.html):

fnu :: erg/s/cm^2/Hz
flam :: erg/s/cm^2/A
photnu :: photons/s/cm^2/Hz
photlam :: photons/s/cm^2/A

Module Contents

Functions

`calc_photon_energy`	Calculates the energy of a photon in ergs given its wavelength or frequency. Useful for converting between erg and photon units.
`convert_freq_wavelength`	Converts between frequency and wavelength for light in a vacuum.
`flam_to_photlam`	Converts from flam (erg/cm^2/s/A) to photlam (photon/cm^2/s/A). See https://www.stsci.edu/~strolger/docs/UNITS.txt.
`fnu_to_photlam`	Converts from fnu (erg/cm^2/s/Hz) to photlam (photon/cm^2/s/A). See <https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_
`fnu_to_flam`	Converts from fnu (erg/cm^2/s/Hz) to flam (erg/cm^2/s/A). See <https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_
`flam_to_fnu`	Converts from flam (erg/cm^2/s/A) to fnu (erg/cm^2/s/Hz). See <https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_\lambda" to "F_
`convert_rel_abs_mag`	Converts between relative and absolute magnitudes.
`flux_to_mag`	Calculates the relative or absolute magnitude of a source and its uncertainty given the monochromatic flux of the source. This can also be used to convert counts to magnitudes if the photometric zero point is calibrated to 1 electron/s.
`mag_to_flux`	Converts magnitude to flux. The units of the flux will depend on the magnitude system. This can also be used to convert magnitudes to counts if the photometric zero point is calibrated to 1 electron/s.
`convert_AB_ST_mag`	Converts AB magnitude to ST magnitude and vice versa. See the derivation (up to Eq. (7)) in Casagrande & VandenBerg (2014): https://ui.adsabs.harvard.edu/abs/2014MNRAS.444..392C/abstract
`flam_to_AB_mag`	Convert a spectrum in flam (erg/s/cm^2/A) to an AB magnitude. Follows Eq. (2) of Bessell & Murphy (2012) https://ui.adsabs.harvard.edu/abs/2012PASP..124..140B/abstract.
`convert_electron_flux_mag`	Convert between electron rates (electron/s), flux in “fnu” units (erg/s/cm^2/Hz), flux in “flam” units (erg/s/cm^2/angstrom), and magnitudes (AB mags). To convert to/from electron/s, this function uses photometric zero points, which implicitly assumes the inputs are over the entire passband. For example, do NOT use this function to convert geocoronal emission line flux to electron/s.

API

castor_etc.utils.conversions.calc_photon_energy(wavelength=None, frequency=None, wavelength_err=0.0, frequency_err=0.0): Calculates the energy of a photon in ergs given its wavelength or frequency. Useful for converting between erg and photon units.

Parameters

wavelength, frequency :: scalar or astropy.Quantity or array The wavelength and frequency of the photon; only one of these should be provided. If values are scalars, wavelength is assumed to be in angstrom and frequency in hertz.

wavelength_err, frequency_err :: scalar or astropy.Quantity or array The uncertainty in the wavelength and uncertainty; only one of these should be provided. If values are scalars, wavelength_err is assumed to be in angstrom and frequency_err in hertz.

Returns

energy, energy_err :: scalar or array The energy of the photon and its uncertainty, in ergs (1 erg = 10^-7 joule).

castor_etc.utils.conversions.convert_freq_wavelength(data, to='wavelength', output_unit=u.AA): Converts between frequency and wavelength for light in a vacuum.

Parameters

data :: scalar or astropy.Quantity or array The frequency of wavelength data to convert. If values are scalars, they are assumed to be in Hz for frequencies and in angstroms for wavelengths.

to :: “wavelength” or “frequency” The quantity to convert the input data to.

output_unit :: astropy.Quantity The unit of the returned, converted data.

Returns

converted_data :: scalar or array The converted data.

castor_etc.utils.conversions.flam_to_photlam(flam, wavelength): Converts from flam (erg/cm^2/s/A) to photlam (photon/cm^2/s/A). See https://www.stsci.edu/~strolger/docs/UNITS.txt.

Parameters

flam :: array The flux in flam.

wavelength :: array of scalars or astropy.Quantity The corresponding wavelengths of the flux. If values are scalars, they are assumed to be in angstroms.

Returns

photlam :: array The flux in photlam.

castor_etc.utils.conversions.fnu_to_photlam(fnu, wavelength)

Converts from fnu (erg/cm^2/s/Hz) to photlam (photon/cm^2/s/A). See
<https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_

u” to “f_\lambda”).

Parameters
----------
  fnu :: array
    The flux in fnu.

  wavelength :: array of scalars or `astropy.Quantity` array
    The corresponding wavelengths of the flux. If values are scalars, they are assumed
    to be in angstroms.

Returns
-------
  photlam :: array
    The flux in photlam.

castor_etc.utils.conversions.fnu_to_flam(fnu, wavelength, fnu_err=0.0, wavelength_err=0.0)

Converts from fnu (erg/cm^2/s/Hz) to flam (erg/cm^2/s/A). See
<https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_

u” to “F_\lambda”).

Parameters
----------
  fnu :: array of scalar
    The flux in fnu.

  wavelength :: scalar, `astropy.Quantity`, scalar array, or`astropy.Quantity` array
    The corresponding wavelengths of the flux. If values are scalars, they are assumed
    to be in angstroms. If not an array, wavelength should be the pivot wavelength of
    the passband.

  fnu_err :: scalar or array of scalars
    The absolute uncertainty in fnu. If a scalar, the same uncertainty is applied to
    all fnu values.

  wavelength_err :: scalar or `astropy.Quantity`
                    or array of scalars or `astropy.Quantity` array
    The absolute uncertainty in wavelength. If scalar(s), wavelength_err is assumed to
    be in angstroms. If not an array, wavelength_err should be the uncertainty in the
    pivot wavelength of the passband.

Returns
-------
  flam, flam_err :: arrays of floats
    The flux in flam and its uncertainty.

castor_etc.utils.conversions.flam_to_fnu(flam, wavelength, flam_err=0.0, wavelength_err=0.0)

Converts from flam (erg/cm^2/s/A) to fnu (erg/cm^2/s/Hz). See
<https://hea-www.harvard.edu/~pgreen/figs/Conversions.pdf> ("F_\lambda" to "F_

u”).

Parameters
----------
  flam :: array of scalar
    The flux in flam.

  wavelength :: array of scalars or `astropy.Quantity` array
    The corresponding wavelengths of the flux. If values are scalars, they are assumed
    to be in angstroms.

  flam_err :: array of scalars
    The absolute uncertainty in flam.

  wavelength_err :: array of scalars or `astropy.Quantity` array
    The absolute uncertainty in wavelength. If values are scalars, they are assumed
    to be in angstroms.

Returns
-------
  fnu, fnu_err :: arrays of floats
    The flux in fnu and its uncertainty.

castor_etc.utils.conversions.convert_rel_abs_mag(mag, dist, mag_err=0.0, dist_err=0.0, to='abs'): Converts between relative and absolute magnitudes.

Parameters

mag :: scalar or array The relative or absolute magnitudes.

dist :: scalar or astropy.Quantity or array The distance to the source. If values are scalars, they are assumed to be in parsecs.

mag_err :: scalar or array The uncertainty in the relative or absolute magnitudes.

dist_err :: scalar or astropy.Quantity or array The uncertainty in the distance to the source. If values are scalars, they are assumed to be in parsecs.

to :: “abs” or “rel” If “abs”, convert input magnitudes to absolute magnitudes. If “rel”, convert input magnitudes to relative magnitudes.

Returns

new_mag, rel_mag_err :: scalar or array The converted magnitudes and their uncertainties.

castor_etc.utils.conversions.flux_to_mag(flux, flux_err=0.0, zpt=-48.6, calc_abs=False, dist=None, dist_err=0.0): Calculates the relative or absolute magnitude of a source and its uncertainty given the monochromatic flux of the source. This can also be used to convert counts to magnitudes if the photometric zero point is calibrated to 1 electron/s.

Parameters

flux, flux_err :: scalar or arrays The monochromatic flux and its uncertainty. The unit of the flux depends on the magnitude system. For example, zpt=-48.60 corresponds to the AB magnitude system and the flux will be in units of erg/s/cm^2/Hz. Likewise, zpt=-21.10 corresponds to the ST magnitude system and the flux will be in units of erg/s/cm^2/A.

zpt :: scalar The zero point of the magnitude system.

calc_abs :: bool If True, calculate the absolute magnitude; also requires the dist parameter to be provided. If False, calculate the relative magnitude.

dist, dist_err :: scalar or astropy.Quantity or array The distance to the source and its uncertainty. If values are scalars, they are assumed to be in parsecs. dist and dist_err are ignored if calc_abs is False.

Returns

mag, mag_err :: float or array The relative or absolute magnitude and its uncertainty.

castor_etc.utils.conversions.mag_to_flux(mag, mag_err=0.0, zpt=-48.6): Converts magnitude to flux. The units of the flux will depend on the magnitude system. This can also be used to convert magnitudes to counts if the photometric zero point is calibrated to 1 electron/s.

Parameters

mag, mag_err :: scalar or arrays The magnitudes and their uncertainties

zpt :: scalar The zero point of the magnitude system. For example, zpt=-48.60 corresponds to the AB magnitude system and the flux will be in units of erg/s/cm^2/Hz. Likewise, zpt=-21.10 corresponds to the ST magnitude system and the flux will be in units of erg/s/cm^2/A.

Returns

flux, flux_err :: scalar or arrays The monochromatic flux and its uncertainty. The unit of the flux depends on the magnitude system. For example, zpt=-48.60 corresponds to the AB magnitude system and the flux will be in units of erg/s/cm^2/Hz. Likewise, zpt=-21.10 corresponds to the ST magnitude system and the flux will be in units of erg/s/cm^2/A.

castor_etc.utils.conversions.convert_AB_ST_mag(mag, wavelength, to='ABmag'): Converts AB magnitude to ST magnitude and vice versa. See the derivation (up to Eq. (7)) in Casagrande & VandenBerg (2014): https://ui.adsabs.harvard.edu/abs/2014MNRAS.444..392C/abstract

Parameters

mag :: scalar or arrays The magnitude(s) to convert.

wavelength :: scalar or astropy.Quantity or array of scalars or astropy.Quantity array If a single value, this is the pivot wavelength of the passband. If an array, these should be the wavelengths at which the magnitude is measured. If scalar(s), wavelength is assumed to be in angstrom.

to :: “ABmag” or “STmag” If “ABmag”, convert input magnitudes and their uncertainties to AB magnitudes. If “STmag”, convert input magnitudes and their uncertainties to ST magnitudes.

Returns

converted_mag :: scalar or arrays The input magnitude(s) converted into the desired magnitude system.

castor_etc.utils.conversions.flam_to_AB_mag(wavelengths, flam, response): Convert a spectrum in flam (erg/s/cm^2/A) to an AB magnitude. Follows Eq. (2) of Bessell & Murphy (2012) https://ui.adsabs.harvard.edu/abs/2012PASP..124..140B/abstract.

Parameters

wavelengths :: array of floats or astropy.Quantity array The wavelengths over which to integrate the spectrum. If an array of floats, it is assumed to be in units of angstrom.

flam :: array of floats The spectral flux density at the given wavelengths, in units of erg/s/cm^2/A.

response :: array of floats The system response function at the given wavelengths. This represents the throughput of the whole optical path and should include the detector quantum efficiencies (i.e., converts from photons to electrons).

Returns

ab_mag :: float The AB magnitude of the spectrum.

castor_etc.utils.conversions.convert_electron_flux_mag(var1, var1_type, var2_type, var1_err=0.0, phot_zpt=None, wavelengths=None, wavelengths_err=0.0): Convert between electron rates (electron/s), flux in “fnu” units (erg/s/cm^2/Hz), flux in “flam” units (erg/s/cm^2/angstrom), and magnitudes (AB mags). To convert to/from electron/s, this function uses photometric zero points, which implicitly assumes the inputs are over the entire passband. For example, do NOT use this function to convert geocoronal emission line flux to electron/s.

Parameters

var1 :: scalar or array The electron rate (electron/s), flux (in “fnu” or “flam” units), or AB magnitude.

var1_type, var2_type :: “electron”, “fnu”, “flam”, or “mag” The type of the first and second variable.

var1_err :: scalar or array The uncertainty in var1.

passband :: “uv”, “u”, or “g” The passband of the variables. Required if var1_type or var2_type is “electron” and phot_zpt is None, ignored otherwise.

phot_zpt :: scalar The photometric zero point of the passband. This should be the AB magnitude required to produce 1 electron/s in the passband. Required if var1_type or var2_type is “electron” and passband is None, ignored otherwise. Will override any default zero points.

wavelengths, wavelengths_err :: scalar or array or astropy.Quantity or astropy.Quantity array The wavelengths and their uncertainties corresponding to the data represented by var1. Required if var1_type or var2_type is “flam”, ignored otherwise. Alternatively, if passband is specified and wavelengths is None, then the pivot wavelength of the passband will be used (the pivot wavelength is typically used if var1 is a quantity integrated over the whole passband). If scalar value(s), wavelengths and wavelengths_err are assumed to be in angstroms.

Returns

var2, var2_err :: scalar or array of scalars The converted var1 values and their uncertainties.

castor_etc.utils.conversions

Unit conversion utilities

Module Contents

Functions

API

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

`castor_etc.utils.conversions`