A Basic Example¶
Before getting started, we recommend that new Chem-I-Calc users read Sandford et al. (In Press) — at least Sections 1-3, and 4.1 — or our abridged summary: Scientific/Statistical Background.
0. Install Chem-I-Calc and Prerequisites¶
If you have not already, please follow the instructions in Installing Chem-I-Calc to both install the Chem-I-Calc package and download the requisite data files.
We find that the exploratory nature of forecasting chemical abundance precision with Chem-I-Calc lends itself well to an interactive Python (iPython) environment in a Jupyter Notebook. This, however, is not a requirement, and the Chem-I-Calc package can just as easily be used in a python script if desired.
1. Initialize Observing Scenario¶
1a. Set Reference Star¶
Most users will likely want to instantiate a ReferenceSpectra
object from a pre-computed reference star
that reasonably represents the characteristics of the observed star(s).
For this example, we consider a RGB star with \(\log{(Z)} = -1.5\) as our reference star.
from chemicalc import reference_spectra as ref
RGB = ref.ReferenceSpectra(reference='RGB_m1.5')
For more information, see Reference Stars.
1b. Set Spectrograph Configuration¶
There are two ways to instantiate an InstConfig
.
One of the many pre-configured instrument setups included in Chem-I-Calc can be instantiated using
AllInst.get_spectrograph
(seed1200g
in the example below).A custom instrument configuration can be instantiated by calling
InstConfig
directly with the desired parameters (seemy_spec
in the example below).
from chemicalc import instruments as inst
d1200g = inst.AllInst.get_spectrograph('DEIMOS 1200G')
my_spec = inst.InstConfig(name='My Spectrograph',
res=5000, # Resolving Power
samp=3, # Pixels / Resolution Element
start=6000, # Blue Wavelength Bound (in Angstrom)
end=10000, # Red Wavelength Bound (in Angstrom)
)
For more information, see Instrument Configurations.
1c. Set Spectrograph Signal/Noise¶
Before we calculate the CRLBs, we must also set the Signal/Noise (S/N) of our observation using the
set_snr
method.
This method can take the following types of arguments:
An
int
orfloat
: This applies a S/N that is constant with wavelength (seed1200g
below).A
np.ndarray
: This applies a wavelength-depend S/N that is interpolated onto the wavelength grid of the instrumental configuration (seemy_spec
below).An ETC query from
chemicalc.s2n
(e.g.,Sig2NoiseDEIMOS
): See ETC Queries for more details.
import numpy as np
d1200g.set_snr(100) # Set constant S/N of 100
my_snr = np.vstack([np.linspace(my_spec.start_wavelength, my_spec.end_wavelength, 100), # wavelength array
np.linspace(50, 100, 100) # S/N array
])
my_spec.set_snr(my_snr) # Set wavelength-dependent S/N
Note
Technically this does not have to occur before Steps 2 and 3, it just must be done before step 4 when the CRLBs are actually computed. In fact, if you wish to investigate the impact of the S/N on the CRLB for a given instrument, you only need to loop over this Step (1c) and Step 4 — Steps 2 and 3 do not need to be repeated for each calculation
For more information, see Setting the Signal/Noise.
2. Convolve Reference Spectra to Instrument Resolution¶
Next, we convolve the high-resolution (\(R \sim 300000\)) reference spectra down to the resolving power of our instrument setups by passing our InstConfig
object to the convolve
method of our ReferenceSpectra
object.
RGB.convolve(d1200g)
RGB.convolve(my_spec)
Note
If the wavelength grid of the instrument is large, this may be somewhat computationally taxing.
3. Calculate Gradient Spectra¶
Next, we calculate the partial derivatives of the reference spectrum with respect to the stellar labels using the convolve
method.
This method takes as an argument either the name of an instrument setup (e.g., "DEIMOS 1200G"
) or a
InstConfig
object (e.g., my_spec
).
RGB.calc_gradient("DEIMOS 1200G")
RGB.calc_gradient(my_spec)
4. Calculate CRLBs¶
Before calculating the CRLBs, we use init_crlb_df
to
initialize an empty pd.DataFrame
with indices corresponding to the stellar labels of
ReferenceSpectra
.
Then we calculate the CRLBs using calc_crlb
for each
InstConfig
and store the results in a column of the CRLB DataFrame.
from chemiclac.crlb import init_crlb_df
CRLB_example = init_crlb_df(RGB)
CRLB_example['DEIMOS 1200G'] = calc_crlb(RGB, d1200g)
CRLB_example['My Spectrograph'] = calc_crlb(RGB, my_spec)
For more information, see Calculating CRLBs.
5. Apply Cutoff and Sort CRLBs¶
Using sort_crlb
we sort the DataFrame of CRLBs in order of decreasing precision and set all CRLBs above a cutoff value (here 0.3 dex) to np.nan
. Setting the argument fancy_labels=True
replaces the labels for effective temperature, surface gravity, and microturbulent velocity with LaTeX formatted labels for plotting.
from chemiclac.crlb import sort_crlb
CRLB_example = sort_crlb(CRLB_example, cutoff=0.3, fancy_labels=True)
6. Plot CRLBs¶
Finally we can plot the CRLBs for our observing scenario!
from chemiclac.plot import plot_crlb
fig = plot_crlb(CRLB_example,
labels='Example CRLBs\n$\log(Z)=-1.5$ RGB',
cutoff=0.3, cutoff_label_yoffset=0.02,
ylim=(0.009, 1.7))
For more information, see Plotting with Chem-I-Calc.