1. Set-Up
1.1. JSON Parameterfile
The heart of Twinkle lies in the input parameter file, which is in JSON format. This file is essential for configuring Twinkle, including specifying the data folder structure, the names of relevant data files, the photometric bands used to fit the stellar spectral energy distribution (SED), plotting options, and more.
You can find an example JSON parameter file for Twinkle here: JSON Parameter File.
The JSON parameter file is organized as a dictionary. It contains boolean values, as well as dictionaries whose members are booleans, strings, arrays, integers, or floats. Below is the full JSON file, followed by descriptions of each section:
{
"longwave_Bool": false,
"W3Adapt" : false,
"W2Adapt" : false,
"fitphot" : true,
"scalephot": true,
"changekeys": true,
"satcheck": true,
"folders":
{
"topdir": "twinkle-master",
"codedir": "twinkle",
"supportdir": "Inputs_and_Models"
},
"files":
{
"starfile": "sample_stardata_simple.txt",
"input_stars" : "select_stars.txt",
"bv_colorfile": "EMamajek_MSColors.txt",
"write2file" : false,
"write_sed" : false
},
"plot":
{
"plot_any" : true,
"plot_grid" : false,
"plot_single" : true,
"pRow" : 4,
"pCol" : 3,
"plotsize" : [8.78, 10.65],
"ylim_up" : 1e-6,
"ylim_low" : 1e-14,
"xmax" : 150
},
"spec_sample":
{
"wave_min":2000,
"wave_max": 4e7,
"gridpts" : 10000
},
"phot":
{
"mags2use0_original" : ["BJ","VJ","J2M","H2M","Ks2M","W1","W2","W3","W4","HPACS100_flux","HPACS160_flux"],
"mags4Phot0_original" : ["BJ","VJ","J2M","H2M","Ks2M","W1","W2"],
"mags4scale0_original" : ["BJ","VJ","J2M","H2M","Ks2M"],
"mags4Dust0" : ["W3","W4","HPACS160_flux","HPACS100_flux"],
"mag4DustWFC" : ["W3","W4","MIPS24"],
"scaleSEDbands" : ["W1","W2"],
"Remove_RedStars" : ["BJ","VJ"],
"Exfunc" : "blackbody",
"modifiedBB_lam0" : "W3"
},
"WISE_excess":
{
"W13_cut": 2.0,
"W23_cut": 2.0,
"W12_cut": 4
},
"comments":
{
"stinfo_file": "File that contains all information for input stars.",
"stinfo_topdir": "Directory name that holds all the stellar information",
"stcolor_dir": "Directory name that holds empirical relation information",
"input_stars" : "filename of stars in single column ascii format.",
"bv_colorfile": "filename of empirical B and V colors & things.",
"write2file" : "boolean that determines whether to write out results to file",
"write_sed" : "boolean that determines whether to write out SED to file.",
"longwave_Bool": "boolean that determines whether to plot longer than 30um data",
"W3Adapt" : "boolean that determines whether to use W3 to fit photopshere.",
"W2Adapt" : "boolean that deteremines whether to use W2 to fit photosphere.",
"wave_min": "min wavelength in angstroms to calculate SED.",
"wave_max": "max wavelength in angstroms to calculate SED.",
"gridpts" : "SED resolution.",
"mags2use0_original" : "Array of strings of all photometry used in session.",
"mags4Phot0_original" : "Array of strings of photometry used in photospheric fit.",
"mags4scale0_original" : "Array of strings of photometry used in scaling raw photosphere.",
"mags4Dust0" : "Array of strings of photometry used to calculate blackbody",
"mag4DustWFC" : "Array of strings of ",
"scaleSEDbands" : "Array of strings of photometryused to scale final SED.",
"Remove_RedStars" : "Array of strings of bands to remove for latest type stars.",
"Exfunc" : "blackbody of modified blackbody.",
"modifiedBB_lam0" : "Central wavelength band for modified blackbody calculation.",
"fitphot": "whether to fit the photosphere or not",
"scalephot": "Whether to re-scale the fitted stellar SED to a set of particular bands for whatever reason.",
"changekeys": "Whether to replace the WISE saturated corrected photometry keywords to standard WISE keywords."
},
}
1.1.2. folders | files
This section contains the names of relevant directories and files for running the code, as well as booleans for writing data to file. In parantheses are the current names listed in the example parameter file.
Directory names:
topdir: The top-level directory for the data (twinkle-master).supportdir: Directory for support files (Inputs_and_Models).
Empirical File Names:
input_user_starfile: Filename for stellar input data (sample_stardata.xlsx).input_stars_sheet: Excel sheet to use in theinput_user_starfile.bv_colorfile: Empirical color file (EMamajek_MSColors.txt).
The names of all the parameters so far can be changed to whatever your heart desires.
Write booleans parameters:
write2file: Boolean indicating whether to write to a file.write_sed: Boolean indicating whether to write SED data to a file.
1.1.3. plot
The plot section contains options for visualizing the stellar data and SED.
plot_any: Boolean to enable or disable plotting.plot_grid: Boolean to enable grid plots.plot_single: Boolean to enable single plots.pRowandpCol: Grid dimensions for the plot (rows and columns - ints).plotsize: Dimensions of the plot (width, height - floats).ylim_upandylim_low: The upper and lower limits for the plot’s y-axis.xmax: Maximum value for the x-axis.
1.1.4. spec_sample
The spec_sample section defines parameters for sampling the spectrum.
wave_min: Minimum wavelength in angstroms (e.g., 2000Å - float).wave_max: Maximum wavelength for calculations (Å - float).gridpts: Number of grid points to sample across the spectrum (int).
1.1.5. phot
The phot section contains photometric band arrays used for various calculations. as well as two boolean parameters.
Wavelength array parameters:
mags2use0_original: Photometry bands used in the session.mags4Phot0_original: Photometry bands used for photospheric fits.mags4scale0_original: Bands used for scaling the raw photospheric spectrum for guessing the initial fit.mags4Dust0: Bands used to calculate blackbody from excess flux.mag4DustWFC: Bands for WFC dust calculations.scaleSEDbands: Bands used to scale the final SED.Remove_RedStars: Bands to not include for late-type stars.
Each of these is an array of strings of photometric bands that the code will use in different scenarios.
For example, if I set:
{
"mags2use0_original" : ["BJ","VJ","J2M","H2M","Ks2M","W1","W2","W3","W4","HPACS160_flux","HPACS100_flux"],
}
Then the code will allow the use of the Johnson B, and V bands, 2MASS J, H, Ks, and WISE All-Sky bands 1 through 4 in the simulation.
If you set mags4Phot0_original to only use the optical and short-wave IR bands, then those are the bands that will be used to fit the photospheric data.
Important
You can insert any string combination of band descriptors into the different phot parameters in the parameterfile, so long as it also exists in mags2use0_original.
Important
The photometric descriptors used in the string arrays can be found in the /Inputs_and_Models/RSR/Filters_README.txt and is listed below. This file also contains information on the data sources for these relative spectral response curves. Captilization matters of each file matters.
You can use these filters for the moment. Their corresponding response
functions are in ./SupportFiles/RSR/.
To specify their use, they need to be added as a string in the "phot"
section of the sed_paramfile.json
========================================================================
Table of Contents:
------------------
I. File Info
II. Available Filters
III. AB Mag Conversion
IV. Band-relevant info
========================================================================
I. File Info
ALL RSR'S ARE STRICTLY THAT.. ALL LAMBDA*RSR has been divided out
Header portion in each RSR File: #!N0[0,f]/ N1[1,f]/ N2[2,f]/ N3[3,f]/ N4[4,f]/ N5[5,f]/
N0 = Isophotal wavelength (Angstroms)
N1 = vega zero point flux in erg/s/cm^2/Angstrom
N2 = uncertainty in vega zero point flux in erg/s/cm^2/Angstrom
N3 = Isophotal frequency (Hz)
N4 = vega zero point flux in erg/s/cm^2/Hz
N5 = uncertainty in vega zero point flux in erg/s/cm^2/Hz
========================================================================
II. Available Filters
Band Identifiers Description
--------------- ---------------------------
W1 WISE BAND 1 (3.4 um)
W2 WISE BAND 2 (4.6 um)
W3 WISE BAND 3 (~12 um)
W4 WISE BAND 4 (~22 um)
MIPS24 Spizter/MIPS 24 um
MIPS70 Spizter/MIPS 70 um
MIPS160 Spizter/MIPS 160 um
J2M 2MASS J
H2M 2MASS H
Ks2M 2MASS Ks
UB Bessel U
BB Bessel B
VB Bessel V
RB Bessel R
IB Bessel I
UJ Johnson U
BJ Johnson B
VJ Johnson V
RJ Johnson R
IJ Johnson I
VT Tycho V
BT Tycho B
Hp Hipparcos
IRAS60 IRAS 60
IRAS100 IRAS 100
IRAS25 IRAS 25
IRAS12 IRAS 12
HPACS70 Herschel/PACS 70
HPACS100 Herschel/PACS 100
HPACS160 Herschel/PACS 160
Akari90 Akari 90 um
Akari9 Akari 9 um IRCW
Akari18 Akari 18 um IRCLW
HNIRC2 Keck NIRC2 H
KpNIRC2 Keck NIRC2 Kp
LpNIRC2 Keck NIRC2 Lp
MSXA MSX A
MSXC MSX C
MSXD MSX D
MSXE MSX E
IDENIS DENIS I BAND
JDENIS DENIS J BAND
KSDENIS DENIS Ks BAND
GGAIA GAIA G BAND
========================================================================
III. AB Mag Conversion
AB mag conversion:
http://www.astro.utoronto.ca/~patton/astro/mags.html
http://www.aerith.net/astro/color_conversion.html
http://casa.colorado.edu/~ginsbura/filtersets.htm__
========================================================================
IV. Band Relevant Info
2MASS:
x: wavelength (microns)
y: relative spectral response
U,B,V,I:
x: wavelength (angrstoms)
y: Relative spectral response
Johnson zero points from http://www.stsci.edu/hst/observatory/documents/isrs/scs8.rev.pdf
Taken from
http://spiff.rit.edu/classes/phys440/lectures/filters/filters.html
WISE:
w1,w2,w3,w4
x:wavelength (microns)
y:rsr (not normalized)
# Relative Spectral Response per erg (Equal-Energy); Jarrett et al. 2011
taken from http://wise2.ipac.caltech.edu/docs/release/allsky/expsup/sec4_4h.html#WISEZMA
The following RSRs are modified RSRs from Brown+2014
The monochromatic flux densities are changed based on
the new vega AB mag = 6.66
truncated W4:
Identical to lab RSR except it has zero transmission lambda<21.1 microns
stretched W4:
Identiacal to lab except all the wavelengths have been revised upward by 3.3% (i.e., ∆λ = 0.033λ)
IRAS:
60
x:wavelength(Angstrom)
y:rsr
SPITZER:
MIPS: FROM http://irsa.ipac.caltech.edu/data/SPITZER/docs/mips/calibrationfiles/spectralresponse/
Lambda in microns
wavelength is the one gien in MIPS handbook
HERSCHEL:
from SVO profile service
pivot wavelength used
angstroms
AKARI:
from SVO profile service
wavelength in angstrom
Using lam_eff for wavelength: 90
using lam_pivot for wavelength: 18,9
NIRC2:
http://svo2.cab.inta-csic.es/svo/theory/fps3/index.php?id=Keck/NIRC2.H&&mode=browse&gname=Keck&gname2=NIRC2#filter
filter data from NIRC2 website.
central wavelength and zero point is from SVO
DENIS, GAIA, MSX:
from SVO profile service
pivot wavelength used.
1.1.6. WISE_excess
The WISE_excess section defines WISE photometry cuts for identifying excess in infrared bands:
W13_cut: Cutoff for W1 and W3 excess.W23_cut: Cutoff for W2 and W3 excess.W12_cut: Cutoff for W1 an d W2 excess.
1.2. Data Files and Folder Structure
1.2.1. Directory Structure
Once you’ve installed Twinkle and it is included in your path, you’ll need to set-up your working-folder which will contain input data to model the stellar spectral energy distribution of a given target, and the empirical data the code will use to perform that calculation.
You can download the current data and folders from the Github project page. The twinkle package need not be in your working directory as long as it’s in your PYTHONPATH.
The data should be in the structure shown in the first panel below. The code will use information from the folders and files elements of the JSON parameterfile to identify which folder to pull data from. The color-coding in the below directory structure is as follows:
- Folder name from the parameter file
- Static folder names
- File name from the parameter file
You need to make sure that folders/topdir points to where the folder is on your machine.
todo: make paramfile auto-read from directory structure.
['folders']['topdir'] ├── Twinkle Tutorial.ipynb ├── paramfile.json ├── ['folders']['supportdir'] │ ├── ['files']['bv_colorfile'] │ ├── StellarInputFiles/ │ │ ├── Input_StarFile_Description.xlsx │ │ └── ['files']['starfile'] │ ├── StellarGridModels/ │ │ ├── ATLAS9/ │ │ │ ├── README.txt │ │ │ ├── km05/ │ │ │ │ ├── km05_10000.fits │ │ │ │ ├── km05_10500.fits │ │ │ │ . │ │ │ │ . │ │ │ │ . │ │ │ │ ├── km05_9500.fits │ │ │ │ └── km05_9750.fits │ │ │ └── kp00/ │ │ │ ├── kp00_10000.fits │ │ │ ├── kp00_10500.fits │ │ │ . │ │ │ . │ │ │ . │ │ │ ├── kp00_9500.fits │ │ │ └── kp00_9750.fits │ │ └── NextGen/ │ │ ├── lteNextGen_10000.0_3.5_0.0.txt │ │ ├── lteNextGen_10000.0_4.0_0.0.txt │ │ ├── lteNextGen_10000.0_4.5_0.0.txt │ │ . │ │ . │ │ . │ │ └── lteNextGen_9800.0_5.5_0.0.txt │ │ └───└── RSR/ ├── Akari90.dat ├── Akari_IRCL18W.dat ├── Akari_IRCS9W.dat . . . ├── W1_WISE.dat ├── W2_WISE.dat ├── W3_WISE.dat ├── W4_WISE.dat └── Filters_ReadME.txt
For example, if we take the values of the files and folders dictionaries in the example parameter file on this page, the directory structure will look like the image below. Now, you might ask, why is the Inputs_and_Models folder under the folders/supportdir a variable? Why would you need to change that name.
Sure. You could ask that.
** can topdir be made to be a a file path?**
twinkle-master ├── Twinkle Tutorial.ipynb ├── paramfile.json ├── Inputs_and_Models/ │ ├── EMamajek_MSColors.txt │ ├── StellarInputFiles/ │ │ ├── Input_StarFile_Description.xlsx │ │ └── user_input_stardata.xlsx │ ├── StellarGridModels/ │ │ ├── ATLAS9/ │ │ │ ├── README.txt │ │ │ ├── km05/ │ │ │ │ ├── km05_10000.fits │ │ │ │ ├── km05_10500.fits │ │ │ │ . │ │ │ │ . │ │ │ │ . │ │ │ │ ├── km05_9500.fits │ │ │ │ └── km05_9750.fits │ │ │ └── kp00/ │ │ │ ├── kp00_10000.fits │ │ │ ├── kp00_10500.fits │ │ │ . │ │ │ . │ │ │ . │ │ │ ├── kp00_9500.fits │ │ │ └── kp00_9750.fits │ │ └── NextGen/ │ │ ├── lteNextGen_10000.0_3.5_0.0.txt │ │ ├── lteNextGen_10000.0_4.0_0.0.txt │ │ ├── lteNextGen_10000.0_4.5_0.0.txt │ │ . │ │ . │ │ . │ │ └── lteNextGen_9800.0_5.5_0.0.txt │ │ └───└── RSR/ ├── Akari90.dat ├── Akari_IRCL18W.dat ├── Akari_IRCS9W.dat . . . ├── W1_WISE.dat ├── W2_WISE.dat ├── W3_WISE.dat ├── W4_WISE.dat └── Filters_ReadME.txt
1.2.1.1. [‘folders’][‘topdir’] | (e.g., twinkle-master/)
Top-level directory that contains all the input and empirical data Twinkle will use for the simulation.
1.2.1.2. Twinkle Tutorial.ipynb
Jupyter notebook tutorial that will help you get started.
1.2.1.3. [‘folders’][‘supportdir’] | (e.g., Inputs_and_Models/)
This folder contains the synthetic stellar grid models, relative spectral response (RSR) files, empirical stellar color relations, and descriptions of input data.
1.2.1.4. RSR/
Relative spectral response (RSR) data corresponding to the identifiers in the available photometric filters file (link to table above).
1.2.1.5. [‘files’][‘bv_colorfile’] | (e.g., EMamajek_MSColors.txt)
This file contains empirical color relations for all stellar spectral types. The data is taken from Dr. Eric Mamajek’s carefully maintained color tables.
The file used by Twinkle can be found on the github page.
Warning
Dr. Eric Mamajek’s tables are constantly being updated, and the table used by the simulation may be outdated. Take this into consideration when using the table on Github.
1.2.1.6. [‘files’][‘starfile’] | (e.g., user_input_stardata.xlsx)
This file is an excel file containing data for each star whose SED you wish to model. Each row contains physical and photometric information for a single star, and the columns correspond to different features for the star. Information on how to build the starfile can be found on the User Input File page.
1.2.1.7. [‘files’][‘input_stars_sheet’]
Your excel file can have multiple sheets, and you can specify which sheet to use from this parameter.
1.2.1.8. Input_StarFile_Description.xlsx
File containing descriptions of the meta data for the stellar input data the code will use in the grid model fitting. Here’s the link.
You can also check out the contents on the User Input File page here
1.2.1.9. StellarGridModels/
Contains atmospheric stellar grid models. Links to the models (ATLAS9 and NextGen) on the Github page are here.
Description to the atmopsheric models can be found on the Model Data page.
1.2.1.10. ATLAS9/
These are the Kurucz Atlas 9 models and are in FITS format. More information can be found in the ATLAS9 section on the Model Data page.
1.2.1.11. NextGen/
These are the NextGen atmospheric models (Hauschildt et al. 1999) models. More information can be found in the NexstGen section on the Model Data page.
1.1.1. comments
The comments section contains metadata descriptions for various elements in the parameter file. These also describe the elements that are not under the top-level keys:
longwave_bool,W3Adapt,W2Adapt,fitphot,scalephot,changekeys,satcheck.