eniric 1.0.0rc2

Eniric: Extended NIR Information Content

ENIRIC - Extended Near InfraRed Information Content

Eniric is a Python 3 software to compute the theoretical Radial Velocity (RV) precision of stellar spectra. Eniric is an overhaul and extension to the code used in Figueria et al. 2016 to analysis the precision of M-dwarf stars. Extending the performance and usability, it is able to be used on any synthetic spectra from the PHOENIX-ACES and BT-Settl (CIFIST2001-2015) libraries.

Checkout the wiki here!

Features:

Eniric contains a number of features to transform and prepare the spectra (observed and synthetic).

• Spectral broadening
  • Rotational
  • Instrumental
• Atmospheric transmission masking
• Relative RV precision
  • The RV precision can be calculated relative to a specified SNR per pixel in the center of a spectroscopic band. The default as used in the Figueira et al. 2016 is a SNR of 100 at the center of the J-band.
• Spectral re-sampling
  • n pixels per FWHM
• Band selection
  • Analysis in individual spectroscopic bands.
• Incremental quality & precision
• Synthetic libraries available
  • Available through [Starfish]'s() grid_tools.
    • PHOENIX-ACES
    • BT-Settl

Installation

Currently to install Eniric you need to clone the repo:

git clone https://github.com/jason-neal/eniric
cd eniric
pip install -r requirements.txt
python setup.py develop

A pip installable version is in the works...

You also need to manually install Starfish

git clone [e-mail]:iancze/Starfish.git
cd Starfish
python setup.py build_ext --inplace
python setup.py develop
cd ..

see here for more information about installing Starfish.

Requirements for Eniric :

The latest versions are pinned in requirements.txt

• astropy
• joblib>=0.12.3
• matplotlib
• multiprocess
• numpy
• pandas
• pyyaml
• scipy
• tqdm

Extra requirements for Starfish:

• corner
• cython
• h5py
• scikit-learn

If you are not going to use Eniric to analyze synthetic spectra (PHOENIX-ACES/BT-Settl) then you may get away with not installing it (some tests with xfail).

Preparation

Configuration

Eniric uses a config.yaml file which is required in the current directory to specify some paths, such as the location the the synthetic spectral library.

You can use the config.yaml to specify custom wavelength ranges to use

bands: 
  all: [..., myband]  # add myband to all list

custom_bands:
    myband: [1.5, 1.6] # micron

You can then pass myband to the band arguments in Eniric scripts/functions.

This based off Starfish and although many keywords are needed to be present for Starfish to run they are not used for Eniric's usage of Starfish and are fine left blank.

Atmospheric data:

To perform telluric masking and account for the transmission of Earth's atmosphere a telluric spectra is required. Eniric includes the telluric spectra uses in Figueira et al. 2016, averaged over 2014. To automatically prepare the telluric masks, splitting into bands and applying the barycentric expansion run the following scripts:

• split_atmmodel.py
• bary_shift_atmmodel.py

These will split the large telluirc spectra into the bands specified in the config.yaml so that the opening and slicing of the large telluric spectrum is not performed continually.

To change the telluric line cutoff depth you to 4% can pass (default = 2%) you can pass it like this

`split_atmmodel.py --cutoff-depth 4`

You can specify your own telluric mask instead. By keeping it in the same format and setting atmmodel parameters in config.yaml you can make use of the Atmosphere class which can perform the mask cutoff and doppler shifting.

Or you can manually apply your own masking function as the mask parameter to the rv_precision function.

Usage

You can now calculate the theoretical RV precision for any PHOENIX-ACES model. You will need to configure the path to the phoenix models in ´config.yaml´

e.g.

phoenix_precision.py -t 3900 -l 4.5, -m 0.5 -r 100000 -v 1.0 -b J K

Will calculate the RV precision in the J and K-band of the PHOENIX-ACES spectra with parameters [Teff=3900K, logg=4.5, [Fe/H]=0.5] observed at a resolution of 100,000 and rotating with 1.0 km/s. For more details on the command line arguments to use see the wiki or type

phoenix_precision.py -h

The Readme below this point needs amended....

Outline

The code works in two main stages, "spectral preparation" and "precision calculation".

Spectrum preparation

eniric/nIRanalysis.py

This stage takes in the raw PHOENIX-ACES spectral models and transforms them, saving the results of this computation as .dat files.

It includes:

• Conversion from flux to photon counts.
• Resolution convolution
• Re-sampling

Some scripts are given in eniric_scripts to run this preparation over all desired parameters automatically. You will have to modify the paths to things.

Precision Calculations

python eniric_scripts/nIR_precision.py

This takes in the processed spectra and performs the precision calculations for all 3 conditions outlined in the original paper.

• Cond1. Total information
• Cond2. +/-30km/s telluric line > 2% masking
• Cond3. Perfect telluric correction with variance correction

It also scales the flux level to a desired SNR level in a desired band, see below, as this affects the RV precision calculated. By default this is a SNR of 100 in the J band.

Band SNR Scaling.

By default, in accordance with the initial paper, each spectra band is normalized to 100 SNR in the center of the J band.

This now does this automatically by measuring the SNR in 1 pixel resolution (3 points) in the center of the band. And scales accordingly. This adds a spectral model dependent factor on the RV precision. To get around you can manually specify the SNR level to normalize to and which specific band to normalize to. (it can be itself for instance).

Instructions

Create an empty dir to hold your analysis. Create data dir with re-sampled, results, phoenix_dat Copy config.yaml and adjust the paths relative to what you created and to the raw phoenix spectra.

eniric_scripts/prepare_spectra.py - This opens the phoenix flux spectra, add wavelength axis in microns and converts flux to photon counts. It saves this in the phoenix_dat dir. (The copy of wavelengths does waste space.)

eniric_scripts/nIR_run.py - Perform the resolution and rotational convolution on the prepared spectra.

This also does the re-sampling.

e.g. python ../Codes/eniric/eniric_scripts/nIR_run.py -s M0 M3 M6 M9 -b Y J H K -v 1.0 5.0 10.0 -R 60000 80000 100000 --sample_rate 3

Background

The origin of this code was used in Figueira et al. 2016.

P. Figueira, V. Zh. Adibekyan, M. Oshagh, J. J. Neal, B. Rojas-Ayala, C. Lovis, C. Melo, F. Pepe, N. C. Santos, M. Tsantaki, 2016,
Radial velocity information content of M dwarf spectra in the near-infrared,
Astronomy and Astrophysics, 586, A101

It had a number of efficiency issues with convolution which were improved upon

To reproduce the updated results for Figueira et al. 2016 run

phoenix_precision.py -t 3900 3500 2800 2600 -l 4.5, -m 0.5 -r 60000 80000 100000 -v 1.0 5.0 10.0 -b Z Y J H K