Magnitudes and other Logarithmic Units¶
Magnitudes and logarithmic units such as dex
and dB
are used the
logarithm of values relative to some reference value. Quantities with such
units are supported in astropy
via the Magnitude
,
Dex
, and Decibel
classes.
Creating Logarithmic Quantities¶
One can create logarithmic quantities either directly or by multiplication with a logarithmic unit. For instance:
>>> import astropy.units as u, astropy.constants as c, numpy as np
>>> u.Magnitude(10.)
<Magnitude 10. mag>
>>> u.Magnitude(10 * u.ct / u.s)
<Magnitude 2.5 mag(ct / s)>
>>> u.Magnitude(2.5, "mag(ct/s)")
<Magnitude 2.5 mag(ct / s)>
>>> 2.5 * u.mag(u.ct / u.s)
<Magnitude 2.5 mag(ct / s)>
>>> u.Dex((c.G * u.M_sun / u.R_sun**2).cgs)
<Dex 4.438067627303133 dex(cm / s2)>
>>> np.linspace(2., 5., 7) * u.Unit("dex(cm/s2)")
<Dex [2. , 2.5, 3. , 3.5, 4. , 4.5, 5. ] dex(cm / s2)>
Above, we make use of the fact that the units mag
, dex
, and
dB
are special in that, when used as functions, they return a
LogUnit
instance
(MagUnit
,
DexUnit
, and
DecibelUnit
,
respectively). The same happens as required when strings are parsed
by Unit
.
As for normal Quantity
objects, one can access the value with the
value
attribute. In addition, one can convert easily
to a Quantity
with the physical unit using the
physical
attribute:
>>> logg = 5. * u.dex(u.cm / u.s**2)
>>> logg.value
5.0
>>> logg.physical
<Quantity 100000. cm / s2>
Converting to different units¶
Like Quantity
objects, logarithmic quantities can be converted to different
units, be it another logarithmic unit or a physical one:
>>> logg = 5. * u.dex(u.cm / u.s**2)
>>> logg.to(u.m / u.s**2)
<Quantity 1000. m / s2>
>>> logg.to('dex(m/s2)')
<Dex 3. dex(m / s2)>
For convenience, the si
and
cgs
attributes can be used
to convert the Quantity
to base S.I. or c.g.s units:
>>> logg.si
<Dex 3. dex(m / s2)>
Arithmetic and Photometric Applications¶
Addition and subtraction work as expected for logarithmic quantities, multiplying and dividing the physical units as appropriate. It may be best seen through an example of a very simple photometric reduction. First, calculate instrumental magnitudes assuming some count rates for three objects:
>>> tint = 1000.*u.s
>>> cr_b = ([3000., 100., 15.] * u.ct) / tint
>>> cr_v = ([4000., 90., 25.] * u.ct) / tint
>>> b_i, v_i = u.Magnitude(cr_b), u.Magnitude(cr_v)
>>> b_i, v_i
(<Magnitude [1.19280314, 2.5 , 4.55977185] mag(ct / s)>,
<Magnitude [1.50514998, 2.61439373, 4.00514998] mag(ct / s)>)
Then, the instrumental BV color is simply:
>>> b_i  v_i
<Magnitude [ 0.31234684, 0.11439373, 0.55462187] mag>
Note that the physical unit has become dimensionless. The following step might be used to correct for atmospheric extinction:
>>> atm_ext_b, atm_ext_v = 0.12 * u.mag, 0.08 * u.mag
>>> secz = 1./np.cos(45 * u.deg)
>>> b_i0 = b_i  atm_ext_b * secz
>>> v_i0 = v_i  atm_ext_b * secz
>>> b_i0, v_i0
(<Magnitude [1.36250876, 2.33029437, 4.39006622] mag(ct / s)>,
<Magnitude [1.67485561, 2.4446881 , 3.83544435] mag(ct / s)>)
Since the extinction is dimensionless, the units do not change. Now suppose the first star has a known ST magnitude, so we can calculate zero points:
>>> b_ref, v_ref = 17.2 * u.STmag, 17.0 * u.STmag
>>> b_ref, v_ref
(<Magnitude 17.2 mag(ST)>, <Magnitude 17. mag(ST)>)
>>> zp_b, zp_v = b_ref  b_i0[0], v_ref  v_i0[0]
>>> zp_b, zp_v
(<Magnitude 18.56250876 mag(s ST / ct)>,
<Magnitude 18.67485561 mag(s ST / ct)>)
Here, ST
is a shorthand for the ST zeropoint flux:
>>> (0. * u.STmag).to(u.erg/u.s/u.cm**2/u.AA)
<Quantity 3.63078055e09 erg / (Angstrom cm2 s)>
>>> (21.1 * u.STmag).to(u.erg/u.s/u.cm**2/u.AA)
<Quantity 1. erg / (Angstrom cm2 s)>
Note
at present, only magnitudes defined in terms of luminosity or flux are implemented, since those that do not depend on the filter the measurement was made with. They include absolute and apparent bolometric [M15], ST [H95] and AB [OG83] magnitudes.
Now applying the calibration, we find (note the proper change in units):
>>> B, V = b_i0 + zp_b, v_i0 + zp_v
>>> B, V
(<Magnitude [17.2 , 20.89280314, 22.95257499] mag(ST)>,
<Magnitude [17. , 21.1195437 , 22.51029996] mag(ST)>)
We could convert these magnitudes to another system, e.g., ABMag, using appropriate equivalency:
>>> V.to(u.ABmag, u.spectral_density(5500.*u.AA))
<Magnitude [16.99023831, 21.10978201, 22.50053827] mag(AB)>
Suppose we also knew the intrinsic color of the first star, then we can calculate the reddening:
>>> B_V0 = 0.2 * u.mag
>>> EB_V = (B  V)[0]  B_V0
>>> R_V = 3.1
>>> A_V = R_V * EB_V
>>> A_B = (R_V+1) * EB_V
>>> EB_V, A_V, A_B
(<Magnitude 0.4 mag>, <Quantity 1.24 mag>, <Quantity 1.64 mag>)
Here, one sees that the extinctions have been converted to quantities. This
happens generally for division and multiplication, since these processes
work only for dimensionless magnitudes (otherwise, the physical unit would have
to be raised to some power), and Quantity
objects, unlike logarithmic
quantities, allow units like mag / d
.
Note that one can take the automatic unit conversion quite far (perhaps too far, but it is fun). For instance, suppose we also knew the bolometric correction and absolute bolometric magnitude, then we can calculate the distance modulus:
>>> BC_V = 0.3 * (u.m_bol  u.STmag)
>>> M_bol = 5.46 * u.M_bol
>>> DM = V[0]  A_V + BC_V  M_bol
>>> BC_V, M_bol, DM
(<Magnitude 0.3 mag(bol / ST)>,
<Magnitude 5.46 mag(Bol)>,
<Magnitude 10. mag(bol / Bol)>)
With a proper equivalency, we can also convert to distance without remembering the 55log rule:
>>> radius_and_inverse_area = [(u.pc, u.pc**2,
... lambda x: 1./(4.*np.pi*x**2),
... lambda x: np.sqrt(1./(4.*np.pi*x)))]
>>> DM.to(u.pc, equivalencies=radius_and_inverse_area)
<Quantity 1000. pc>
Numpy functions¶
For logarithmic quantities, most numpy functions and many array methods do not make sense, hence they are disabled. But one can use those one would expect to work:
>>> np.max(v_i)
<Magnitude 4.00514998 mag(ct / s)>
>>> np.std(v_i)
<Magnitude 2.33971149 mag>
Note
This is implemented by having a list of supported ufuncs in
units/function/core.py
and by explicitly disabling some
array methods in FunctionQuantity
.
If you believe a function or method is incorrectly treated,
please let us know.
Dimensionless logarithmic quantities¶
Dimensionless quantities are treated somewhat specially, in that, if needed,
logarithmic quantities will be converted to normal Quantity
objects with the
appropriate unit of mag
, dB
, or dex
. With this, it is possible to
use composite units like mag/d
or dB/m
, which cannot easily be
supported as logarithmic units. For instance:
>>> dBm = u.dB(u.mW)
>>> signal_in, signal_out = 100. * dBm, 50 * dBm
>>> cable_loss = (signal_in  signal_out) / (100. * u.m)
>>> signal_in, signal_out, cable_loss
(<Decibel 100. dB(mW)>, <Decibel 50. dB(mW)>, <Quantity 0.5 dB / m>)
>>> better_cable_loss = 0.2 * u.dB / u.m
>>> signal_in  better_cable_loss * 100. * u.m
<Decibel 80. dB(mW)>
[M15]  Mamajek et al., 2015, arXiv:1510.06262 
[H95]  E.g., Holtzman et al., 1995, PASP 107, 1065 
[OG83]  Oke, J.B., & Gunn, J. E., 1983, ApJ 266, 713 
Reference/API¶
astropy.units.function.logarithmic Module¶
Classes¶
LogUnit ([physical_unit, function_unit]) 
Logarithmic unit containing a physical one 
MagUnit ([physical_unit, function_unit]) 
Logarithmic physical units expressed in magnitudes 
DexUnit ([physical_unit, function_unit]) 
Logarithmic physical units expressed in magnitudes 
DecibelUnit ([physical_unit, function_unit]) 
Logarithmic physical units expressed in dB 
LogQuantity 
A representation of a (scaled) logarithm of a number with a unit 
Magnitude 

Decibel 

Dex 
Variables¶
STmag 
ST magnitude: STmag=21.1 corresponds to 1 erg/s/cm2/A 
ABmag 
AB magnitude: ABmag=48.6 corresponds to 1 erg/s/cm2/Hz 
M_bol 
Absolute bolometric magnitude: M_bol=0 corresponds to L_bol0=3.0128e+28 J / s 
m_bol 
Apparent bolometric magnitude: m_bol=0 corresponds to f_bol0=2.51802e08 kg / s3 
Class Inheritance Diagram¶
astropy.units.photometric Module¶
This module defines magnitude zero points and related photometric quantities.
The corresponding magnitudes are given in the description of each unit
(the actual definitions are in logarithmic
).
Unit  Description  Represents  Aliases  SI Prefixes 

AB 
AB magnitude zero flux density (magnitude ABmag ). 
\(\mathrm{3.6307805 \times 10^{20}\,\frac{erg}{Hz\,s\,cm^{2}}}\)  ABflux 
No 
Bol 
Luminosity corresponding to absolute bolometric magnitude zero (magnitude M_bol ). 
\(\mathrm{3.0128 \times 10^{28}\,W}\)  L_bol 
No 
bol 
Irradiance corresponding to appparent bolometric magnitude zero (magnitude m_bol ). 
\(\mathrm{2.3975101 \times 10^{25}\,\frac{W}{pc^{2}}}\)  f_bol 
No 
mgy 
Maggies  a linear flux unit that is the flux for a mag=0 object.To tie this onto a specific calibrated unit system, the zero_point_flux equivalency should be used.  maggy 
Yes  
ST 
ST magnitude zero flux density (magnitude STmag ). 
\(\mathrm{3.6307805 \times 10^{9}\,\frac{erg}{\mathring{A}\,s\,cm^{2}}}\)  STflux 
No 
Functions¶
zero_point_flux (flux0) 
An equivalency for converting linear flux units (“maggys”) defined relative to a standard source into a standardized system. 