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 (see d1200g in the example below).

  • A custom instrument configuration can be instantiated by calling InstConfig directly with the desired parameters (see my_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 or float: This applies a S/N that is constant with wavelength (see d1200g below).

  • A np.ndarray: This applies a wavelength-depend S/N that is interpolated onto the wavelength grid of the instrumental configuration (see my_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.