Getting Started¶
Loading a grid¶
StarKit computes a model spectrum by interpolating linearly between the
spectra of a model grid stored in an HDF5 file. Available Test Grids
lists grids that can be downloaded, and Input/Output Documentation describes how to build one.
The examples on this page use phoenix_t4000_10000_w3000_9000_r3000.h5, a
PHOENIX grid from 3000 to 9000 Å, which is also in the docs/examples
directory of the repository. Its metadata gives a resolving power
\(R = 3000\), but its spectra have \(R = 1500\), the result of a bug
in the PHOENIX grid builder described in BUGS.md:
>>> from starkit.gridkit import load_grid
>>> grid = load_grid('phoenix_t4000_10000_w3000_9000_r3000.h5',
... wavelength_type='vacuum')
>>> grid
<SpectralGrid(teff=4000., logg=3., mh=0.)>
The grid is an astropy.modeling model with one parameter per
grid dimension, here teff (K), logg (log g, with g in
cm s-2) and mh ([M/H], dex). The
parameters start at the values of the first spectrum in the grid file.
wavelength_type is 'air' or 'vacuum'; if it differs from the
convention of the grid, StarKit converts the wavelengths. Without it, the
convention of the grid is used and a warning is logged.
The range of each parameter is:
>>> grid.param_names
('teff', 'logg', 'mh')
>>> grid.get_grid_extent()
[(4000.0, 10000.0), (3.0, 5.0), (-1.0, 0.0)]
Evaluating the grid¶
Set the parameters and call the grid to obtain the spectrum:
>>> grid.teff = 5780.
>>> grid.logg = 4.4
>>> grid.mh = 0.0
>>> wavelength, flux = grid()
wavelength and flux are numpy arrays in the units of the grid, given by
grid.wavelength.unit and grid.fluxes.unit (Å and
erg s-1 Å-1 for this grid). Parameter values outside the grid
are accepted, but the flux is then NaN at every wavelength.
To plot the spectrum:
>>> import matplotlib.pyplot as plt
>>> plt.plot(wavelength, flux)
The notebook Plotting the spectrum interactively plots the spectrum with sliders for the grid parameters.
Operations on the model spectrum¶
Operations take a wavelength and a flux array and return modified arrays.
They are also astropy models, so their parameters can be fitted together with
the grid parameters. The operations in starkit.base.operations are listed
below; import each one from its module by name, for example
from starkit.base.operations.stellar import RadialVelocity, since
RadialVelocity and Distance are not imported by
from starkit.base.operations.stellar import *.
Operation |
Parameters |
Effect |
|---|---|---|
|
|
Convolves with the rotational broadening profile of Gray, The
Observation and Analysis of Stellar Photospheres. Create it with
|
|
|
Multiplies the wavelengths by \(\sqrt{(1 + \beta) / (1 - \beta)}\), with \(\beta = v_\mathrm{rad} / c\). |
|
|
Multiplies the wavelengths by \(1 + \beta\). |
|
|
Applies the Cardelli, Clayton & Mathis (1989) extinction law between 0.091 and 3.33 µm; the flux outside this range is not changed. |
|
|
Divides the flux by \(4 \pi d^2\), which is correct only for a
grid of luminosity density (erg s-1 Å-1). Many
grids, including the test grid above, hold surface flux, and with them
|
|
|
Convolves with a Gaussian to resolving power |
|
none |
Converts the spectrum to magnitudes in a set of filters, assuming the
flux is in erg s-1 cm-2 Å-1 at the observer
(see Grid Flux Units). The filters are SVO filter IDs or
|
For example, a Doppler shift of 20 km/s:
>>> from starkit.base.operations.stellar import DopplerShift
>>> doppler = DopplerShift(vrad=20.)
>>> new_wavelength, new_flux = doppler(wavelength, flux)
Combining operations¶
The | operator passes the output of one model to the next
(see combining models in the
astropy documentation):
>>> model = grid | doppler
>>> model
<CompoundModel(teff_0=5780., logg_0=4.4, mh_0=0., vrad_1=20.)>
The parameter names of the combined model end in the position of the model they belong to. Further operations are added the same way:
>>> from starkit.base.operations.stellar import (RotationalBroadening,
... CCM89Extinction)
>>> rotation = RotationalBroadening.from_grid(grid, vrot=200.)
>>> extinction = CCM89Extinction(a_v=1.0)
>>> model = grid | rotation | doppler | extinction
>>> model
<CompoundModel(teff_0=5780., logg_0=4.4, mh_0=0., vrot_1=200., limb_darkening_1=0.6, vrad_2=20., a_v_3=1., r_v_3=3.1)>
>>> model.vrot_1 = 300.
>>> wavelength, flux = model()
Assembling a model¶
assemble_model builds the combined model from parameter names. Each
keyword adds the operation that has a parameter of that name, with that
parameter as the starting value:
>>> from starkit import assemble_model
>>> model = assemble_model(grid, vrot=300., vrad=20., a_v=0.3)
>>> print(model)
Model: CompoundModel
Inputs: ()
Outputs: ('wavelength', 'flux')
Model set size: 1
Expression: [0] | [1] | [2] | [3]
Components:
[0]: <SpectralGrid(teff=5780., logg=4.4, mh=0.)>
[1]: <RotationalBroadening(vrot=300., limb_darkening=0.6)>
[2]: <DopplerShift(vrad=20.)>
[3]: <CCM89Extinction(a_v=0.3, r_v=3.1)>
Parameters:
teff_0 logg_0 mh_0 vrot_1 limb_darkening_1 vrad_2 a_v_3 r_v_3
------ ------ ---- ------ ---------------- ------ ----- -----
5780.0 4.4 0.0 300.0 0.6 20.0 0.3 3.1
The keywords are vrot, vrad, a_v, r_v, distance and R.
filter_set and mag_type ('vega' by default) add Photometry.
delta_lambda adds InstrumentDeltaLambdaConstant, a Gaussian of
constant FWHM in wavelength, but with numpy 2.5 its evaluation stops with
TypeError: only 0-dimensional arrays can be converted to Python scalars.
The operations are applied in the order rotation, Doppler shift, extinction,
distance, instrumental resolution, whatever the order of the keywords.
vrad selects DopplerShift; to use RadialVelocity, combine the
operations with |. Grid parameters are not accepted as keywords and stop
assemble_model with a ValueError; set them on the returned model.
Without the stellar keywords (vrot, vrad, a_v, r_v,
distance), assemble_model returns the grid itself, or the grid
followed by the instrumental operations or Photometry. When
filter_set is given, the extinction (a_v and r_v) is applied to
the magnitudes only, not to a spectrum.
Comparing a model with an observed spectrum¶
An observed spectrum is given to StarKit as an SKSpectrum1D, made from
wavelength, flux and uncertainty arrays:
>>> from astropy import units as u
>>> from starkit.fix_spectrum1d import SKSpectrum1D
>>> spectrum = SKSpectrum1D.from_array(
... wavelength=obs_wavelength * u.angstrom,
... flux=obs_flux * u.Unit('erg / (s cm2 Angstrom)'),
... uncertainty=obs_uncertainty)
The model is interpolated onto the observed wavelengths using their numerical
values, so the observed wavelengths must be in the wavelength unit of the grid
(Å for the grids StarKit builds), and the grid must be loaded with the
wavelength_type of the observed spectrum. The interpolation is linear and
does not integrate over the observed pixels.
With spectrum, assemble_model adds the interpolation onto the observed
wavelengths. With normalize_npol it also multiplies the model by the
polynomial in wavelength, of that degree, that best matches the model to the
observed flux, weighted by the uncertainties. The polynomial absorbs the
continuum shape and the flux scale, so the observed spectrum need not be flux
calibrated:
>>> model = assemble_model(grid, spectrum=spectrum, vrad=20.,
... normalize_npol=3)
>>> model
<CompoundModel(teff_0=5780., logg_0=4.4, mh_0=0., vrad_1=20.)>
>>> model_wavelength, model_flux = model()
model_wavelength is the observed wavelength array, and model_flux is
the model on the observed wavelengths, scaled to the observed flux.
The interpolation and normalization have no free parameters. For spectra in
several parts, such as echelle orders or detector chips, normalize_parts
takes a list of slices or index arrays into the observed spectrum, and each
part is normalized with its own polynomial; normalize_npol is then a
single degree or a list with one degree per part.
Fitting describes how to fit the model parameters to the observed spectrum.