EZ_Ages code documentation
----------------------------------

Contents:

Code Input
Code Output
Adjustable Code Parameters
Basic Algorithm
Known Problems
Code Usage Examples

----------------------------------
----------------------------------


Code Input:
----------------------------------

datafile:  The file containing the Lick index measurements, as produced
           by Lick_EW.  If you have measured indices using your own routine, 
	   it is critical that the input data file is in the same format
	   AS IF IT HAD BEEN PRODUCED BY LICK_EW.  This means:

	   *   The file must have a column for ALL of the Lick indices, 
	       in order: HdA, HdF, CN1, CN2, Ca4227, G4300, HgA, HgF, Fe4383,
	       Ca4455, Fe4531, C4668, Hb, Fe5015, Mg1, Mg2, Mgb, Fe5270, 
	       Fe5335, Fe5406, Fe5709, Fe5782, NaD, TiO1, TiO2.  For Lick
	       indices that are missing or not measurable, the column should
	       still be included with the value 'NaN' to indicate that this
	       index is not measured.

	   *   The first line should label the columns for all of the 
	       indices.

	   *   Starting with line 2, lines should alternate, with the
	       name of the galaxy on the first line and the indices as
	       measured for that galaxy on the following line.   

	   *   Index values should be separated by EITHER white space (ie. 
	       space or tab) OR commas, but not both -- due to changes in the 
	       astrolib routine READCOL, values separated by commas AND spaces
	       will be read as two values and you will get a data formatting 
	       error 

	   In general, data input file formatting errors will produced the 
	   following message (if you get this, check the formatting of your
	   self-generated file or use Lick_EW to measure the Lick indices):

	   %READCOL: ERROR - No valid lines found for specified format 
	   Conflicting data structures: structure tag,HDELTAA

errorfile: (Optional input)  If you have measured errors for the Lick index 
           inputs, they are included here.  The formatting is the same as 
	   for the datafile, as described above.  Formatting errors will 
	   in the errorfile will produce the same error message as that for
	   the datafile. 

weights.dat: A sort of "hidden" input file is the 'weights.dat' file that comes
           with the EZ_Ages bundle and is stored in the EZ_Ages directory.  
	   This file allows the user to specify which Lick indices (or a 
	   weighted combination of Lick indices) to use in the abundance 
	   fitting.  The default version of weights.dat that comes with 
	   EZ_Ages used Hbeta and the mean of Fe5270 and Fe5335 to measure
	   ages and [Fe/H], Mgb to fit for [Mg/Fe], C4668 to fit for [C/Fe], 
	   CN2 to fit for [N/Fe], and Ca4227 to fit for [Ca/Fe].  These
	   choices can be changed by editing the 'weights.dat' file.  Using
	   different combinations of indices gives some indication of how 
	   robust the fitting method is to which indices are chosen for the 
	   fits. 
	   
	   NOTE: Do NOT use G4300 to fit [C/Fe]. This index saturates at
	   moderate metallicity (ie. [Fe/H] ~ -1.0) and is therefore not
	   useful for most galaxies.  In any case, the Deltabund model cannot 
	   handle metallicities below [Fe/H] ~ -1.3 so the range in which 
	   G4300 could be useful is very small.
	   
	   NOTE: When using Fe5015, be sure that there is no contaminating
	   emission in the input spectrum.  Fe5015 is strongly affected by 
	   [OIII]5007 emission, making it unreliable for use with galaxies
	   that contain emission lines.

Code Output
--------------

*.out      The main output file has the same name as the input datafile, with
           the appended tag '.out'.  This file contains the best-fitting set
	   of abundances for each input set of Lick indices.  The columns of 
	   the output file include the abundances fit by EZ_Ages, along with 
	   the values of [O/Fe], [Si/Fe], [Na/Fe], [Cr/Fe], [Ti/Fe], isochrone,
	   and imf that were used in the fit, followed by the age
           measured from Hb, the age measured from HgF, and the age
           measured from HdF (these are computed from grid inversion
           of the named Balmer line and the Fe line specified in
           'weights.dat' (by default ).  In order the output
           columns are: Age, [Fe/H], [Mg/Fe], [C/Fe], [N/Fe], [Ca/Fe],
           [O/Fe], [Na/Fe], [Si/Fe], [Cr/Fe], [Ti/Fe], isochrone, imf,
           age_hb, age_hg, age_hd 

*.out_err  (Optional) If an errorfile was provided to EZ_Ages, the code 
           estimates errors for the abundances and ages produced by the fit,
	   and stores these in an output file with the same name as the input
	   datafile, with the appended tag '.out_err'.  Because the responses 
	   of the Lick indices to age and metallicity are non-linear, we 
	   calculate errors above and below the measured value separately.  
	   Errors below and above the measured values are listed in the error 
	   output file as -Age_err and +Age_err, etc. and are labelled 
	   appropriately.

*_check.ps As a simple reality check that EZ_Ages has not produced a crazy 
           result (and to see what is going on with unusual data), EZ_Ages
	   automatically generates a set of index-index plots for each input
	   set of Lick indices.  These files have the same name as the input
	   datafile, with the appended tag '_check.ps'.  For each set of Lick
	   indices, a set of index-index plots are shown which include all of 
	   the indices modelled by deltabund.  

	   In each plot, the model grid shown is the deltabund model with the 
	   best-fitting set of abundances as determined by EZ_Ages.  The solid 
	   lines (constant [Fe/H]) show, from left to right, [Fe/H]=-1.3, 
	   [Fe/H]=-0.7, [Fe/H]=-0.4, [Fe/H]=0.0 and [Fe/H]=+0.2 for the solar-
	   scale isochrone and [Fe/H]=-0.8, [Fe/H]=-0.4, [Fe/H]=0.0, and 
	   [Fe/H]=+0.3 for the alpha-enhanced isochrone.  The dotted lines 
	   (constant age) show, from top to bottom, 1.2, 1.5, 2.5, 2.8, 3.5,
	   5.0, 7.0, 10.0, and 14.1 Gyr ages.


Adjustable Code Parameters
---------------------------

imf:       You will be prompted for a choice of IMF exponent.  The code 
           currently allows 3 options: 1.35 (Salpeter), 0 (power-law), 
	   and 4 (dwarf-rich, for 47 Tuc and other mass segregated systems).
	   This can also be specified at the command line by including 
	   imf=*value* in the initial call to EZ_Ages.

isochrone: You will be prompted for a choice of isochrone.  The code currently
           allows 2 options: 1 (Solar-scale abundances) and 2 (alpha-enhanced).
	   The Solar-scale isochrone is the Girardi et al. (2000) isochrone.  
	   The alpha-enhanced isochrone is from Salasnich et al. (2000), with 
	   average [a/Fe] = +0.42 but with different enhancement for different
	   elements, for instance [O/Fe] = +0.5.  WARNING: It was mentioned
	   in a conversation at the conference "Fine Tuning Stellar Population
	   Models" (June 26-30, 2006) that there is a problem with the 
	   Salasnich et al. 2000 alpha-enhanced isochrone, but this has not 
	   been confirmed and we have no further details.  Use at your own 
	   risk.  This can also be specified at the command line by including
	   iso=*value* in the initial call to EZ_Ages.

age and [Fe/H] tolerances: You will be prompted for an age tolerance and an 
           [Fe./H] tolerance.  EZ_Ages determines the best-fitting set of 
	   abundances by changing the abundance ratios until the age and [Fe/H]
	   values measured in all index-index plots match within the specified
	   tolerance.  The smaller the tolerance, the more tightly the 
	   abundance ratios are constrained, but the longer it takes to find a
	   good fit.  We tend to use an age tolerance of 0.2 Gyr and an [Fe/H]
	   tolerance of 0.02 or 0.01, small enough values that they are well 
	   within the uncertainties of the models and the data measurement
	   errors.  These can also be specified at the command line by 
	   including age_tol=*value* and fe_tol=*value* in the initial call to
	   EZ_Ages.

[O/Fe], [Si/Fe], [Na/Fe], [Cr/Fe], and [Ti/Fe]: The SSP model which is behind
           EZ_Ages is described in Schiavon 2007 (in preparation) and is the 
	   FORTRAN code 'deltabund'.  Deltabund allows the user to vary all
	   of the abundance ratios fit by EZ_Ages, and also the abundances 
	   listed above, which are NOT fit by EZ_Ages.  EZ_Ages allows the user
	   to specify values for these abundances which are included in 
	   deltabund but which it cannot fit, and they will be part of the 
	   final abundance mix.  The user can specify values at the command 
	   line by including o_fe=*value*, si_fe=*value*, na_fe=*value*, 
	   cr_fe=*value*, and/or ti_fe=*value* in the initial call to EZ_Ages.
	   
	   Any abundance which is not set at the command line will be set
	   to its default value by EZ_Ages.  Default values are:
	 
	   * [O/Fe] is set to match the chosen input isochrone (ie. [O/Fe]=0 
	     for the Solar-scale isochrone and [O/Fe]=0.5 for the alpha-
	     enhanced isochrone.
	   
	   * [Cr/Fe] is set to Solar (ie. [Cr/Fe]=0) because it is an Fe-peak
	     element.

	   * [Si/Fe], [Na/Fe], and [Ti/Fe] are set to track [Mg/Fe], so 
	     EZ_Ages fits for the [Mg/Fe] abundance, keeping [Si/Fe] = [Na/Fe] 
	     = [Ti/Fe] = [Mg/Fe] at all times.

Basic Algorithm
-------------------

The algorithm is described in detail in Graves & Schiavon (2008,
astro-ph/0803.1483), which shoulds be considered required reading for
anyone using the code.  EZ_Ages is effectively a wrapper code for the
FORTRAN stellar population model "Deltabund" of Ricardo Schiavon
(2007).  Both these works should be cited in any paper using EZ_Ages.  

The FORTRAN Deltabund code takes as input a set of abundance ratios,
and offers the user a choice of isochrone (Solar-scale or
alpha-enhanced) and a choice of IMF slope (1.35 for Salpeter, 0 for
power-law, 4 for steep IMF used in mass-segregated objects like 47
Tuc).  Deltabund then computes a set of model Lick indices for the
chosen abundance ratio, imf, and isochrone.  The model indices are
produced for a range of ages (1.2-17.9 Gyr) and iron abundances (-1.3
< [Fe/H] < +0.2 for the solar-scale isochrone, -0.8 < [Fe/H] < +0.3
for the alpha- enhanced isochrone).  These model index grids can be
used to produce the index-index grids commonly used in the literature
to determine stellar population parameters.  The abundances that are
taken into account by Deltabund are: [C/Fe], [N/Fe], [O/Fe], [Mg/Fe],
[Ca/Fe], [Si/Fe], [Na/Fe], [Cr/Fe] and [Ti/Fe], using the index
response functions of Korn, Maraston, & Thomas (2005).

NOTE: DELTABUND AND EZ_AGES COMPUTE ALL MODELS AT FIXED [FE/H], NOT
FIXED TOTAL METALLICITY.  CHANGING ABUNDANCE RATIOS OF OTHER ELEMENTS
DOES NOT CHANGE [FE/H].

EZ_Ages takes as input a set of measured Lick indices and used Deltabund to 
determine the best-fitting set of abundances.  It does this by using the Lick
indices that respond most strongly to a given abundance to determine that 
abundance, under the assumption that certain indices are dominated by a 
particular abundance.  EZ_Ages fits for [Mg/Fe], [C/Fe], [N/Fe], and [Ca/Fe] 
because these are the abundances that can be reliably recovered from the 
existing Lick indices.  [O/Fe], [Si/Fe], [Na/Fe], [Cr/Fe], and [Ti/Fe] are
supplied by the user, or set to default values as described above in 
"Adjustable Code Parameters".  

The algorithm goes like this:

1. Getting Fiducial Age and [Fe/H]

EZ_Ages begins by setting all abundance to Solar values (ie. 0.0).
Using the input IMF and isochrone, it calls Deltabund to produce a
solar-scale model.  The model predictions for a range of ages and
[Fe/H] make a grid in index-index space.  EZ_Ages uses an index-index
grid from a Balmer line and an Fe line (set by "weights.dat", see
"Code Input" above), and performs grid inversion to obtain a
"fiducial" age and [Fe/H] value for the galaxy.  Balmer and Fe lines
are chosen because they are sensitive to the age and [Fe/H] of the
galaxy but to first order are INSENSITIVE to other abundance
variations.  (Grids are in all cases constructed with the Balmer line
on the y-axis and the metal line in question on the x-axis.)

NOTE: Previous versions of EZ_Ages allowed fitting of data points that
fell outside the total grid boundaries, as long as their error bars
overlapped with the grid.  In practice, this has been found to make
the code too unstable (i.e., lots of crashes), and we decided we
shouldn't encourage such things in any case.  This feature is no
longer available to the public (if you *really* need to use it, contact
Genevieve and she *might* let you use the old "dirty" version, as long
as she is convinced that you know you're doing something dangerous and
you won't over-interpret your results in an embarrassing way...)

2. Fitting for [Mg/Fe]

EZ_Ages now compares the data values of the Balmer line and an Mg line
(Mg2 or Mgb, as set by "weights.dat") with the model grid of values
produced by Deltabund.  If the value of [Fe/H] measured from the
Balmer-Mg index-index grid matches the fiducial [Fe/H] within the
specified tolerance (see "Adjustable Code Parameters"), then the input
value of [Mg/Fe] used to compute the Deltabund model is a good match.

If the value of [Fe/H] from Balmer-Mg does NOT match, or if it falls
off the grid, EZ_Ages determines the direction of the discrepancy.  If
the Balmer-Mg value of [Fe/H] is too high(low) or falls off the
right(left) side of the grid, EZ_Ages raises(lowers) the value of
[Mg/Fe] that is used as input to Deltabund.  Deltabund then computes a
new set of model index values for the new [Mg/Fe] abundance.  This
process is repeated until the [Fe/H] value from the Balmer-Mg grid
matches the fiducial [Fe/H], within the specified tolerance.

At each step, [Mg/Fe] is incremented by 0.04 dex.  If this incremental
process "overshoots" the fiducial value, EZ_Ages halves the size of
the increment and shifts back in the other direction. If this
overshooting happens multiple times (as can happen when the [Fe/H]
tolerance is set too low), EZ_Ages will stop when the increment has
been decreased to 0.005 dex.  

The resulting value of [Mg/Fe] that produces a match to the fiducial
is taken to be the best-fitting Mg abundance.

Note that if the data point falls ABOVE or BELOW the model grid,
modifying [Mg/Fe] cannot bring it back onto the grid and EZ_Ages will
produce a null value 'NaN' for [Mg/Fe].  In practice this should not
happen because the same Balmer line is used for each stage of the
fitting process.

3. Fitting for [C/Fe], [N/Fe], and [Ca/Fe]

To fit for [C/Fe], EZ_Ages goes through the same process as described
above for fitting [Mg/Fe], using the C4668 index and the same Balmer
line to construct the index-index grid. It again moves the grids left
or right by adjusting [C/Fe] until the measured [Fe/H] matches the
fiducial.

EZ_Ages uses one of the CN indices (either CN1 or CN2) to fit for
[N/Fe].  This can only be done if [C/Fe] has already been determined
by C4668.  If a fit has been found for [C/Fe], then EZ_Ages uses the
same grid-shifting process with a CN line and a Balmer line to fit for
[N/Fe].

Lastly, EZ_Ages uses Ca4227 to fit for [Ca/Fe].  Because Ca4227 can be
strongly affected by the presence of a CN line in its red
pseudocontinuum region, EZ_Ages only fits for [Ca/Fe] if abundances
have been successfully fit for both [C/Fe] and [N/Fe].  The process is
again the same as described above.

4. Iteration

Because EZ_Ages and Deltabund are operating at fixed [Fe/H] and NOT at
fixed total metallicity, the effect of abundance ratios on the Balmer
and Fe lines are small.  However, to take include these small effect,
after finding a full set of best-fitting abundances, EZ_Ages iterates
the process, starting with new fiducials for age and [Fe/H] using the
abundances determined by the first iteration.  This is because,
although the Balmer lines and the Fe lines are relatively insensitive
to non-Solar abundance ratios, they are slightly affected by some
abundances.

EZ_Ages iterates the fitting process in order to get a
self-consistent set of abundance ratios.  It stops when either nothing
changes between iterations, or until it has iterated 4 times in order
to prevent infinite loops that fluctuate up and down between two
abundance values.  In practice, 3 iterations appear to be all that are
necessary to produce stable results.

5. Error Estimates

After the full set of best-fitting abundances has been determined,
EZ_Ages estimates errors for the ages and abundances it has produced.
This is only done if measurement errors for the Lick index
measurements have been provided as input.  Estimated errors are due to
the uncertainties caused by measurement ONLY.  Uncertainties in the
models are not included (ie. those due to isochrone uncertainties or
errors in the index response functions).  For abundances (such as
[Ca/Fe]) that depend on the fitting of other abundances, errors are
propagated through. Errors above and below the measured values are
calculated separately because the index-index grids are non-linear
(particularly in age).

Age and [Fe/H] errors: To estimate the error in the measured ages and
[Fe/H] values, EZ_Ages uses the Balmer-Fe index-index grid based on
the best-fitting abundances.  Grid inversion is used to estimate the
age and [Fe/H] for the data point located at (Fe + Fe_err, Balmer +
Balmer_err), and at (Fe - Fe_err, Balmer - Balmer_err). These ages and
[Fe/H] values are assumed to span the 1-sigma range of allowed values
and are taken as the errors in age and [Fe/H].

[Mg/Fe] and [C/Fe] errors: For both [Mg/Fe] and [C/Fe], there are two
sources of error: measurement uncertainties in the Mg and C4668 indices
used to determine the abundance, and also uncertainties due to the
non-zero error in the fiducial values for age and [Fe/H] which are
being matched in the grid-shifting process.  The uncertainties in the
[Mg/Fe] abundance due to the error in measuring Mgb (or Mg2) are
determined by re-doing the grid-shifting process for Mgb + Mgb_err and
Mgb - Mgb_err (or similar for Mg2) to produce the values of [Mg/Fe]
that span the range possible Mgb values.  The error due to
uncertainties in the fiducial [Fe/H] are determined by re-doing the
grid-shifting with the measured Mgb value to match the fiducial +/-
[Fe/H] error to see how much changing the fiducial changes the
resulting value of [Mg/Fe].  Finally, these two sources of error are
assumed to be uncorrelated, and the errors are summed in quadrature to
produce a total error in the measured [Mg/Fe] abundance.  The same
process is applied to [C/Fe].

[N/Fe] and [Ca/Fe]: For these abundances, there are three sources of
error: the two described for [Mg/Fe] and [C/Fe] (that is, index
measurement errors and uncertainties in the fiducial), and an
additional source of error because they depend on other abundances.
[N/Fe] also depends on the value of [C/Fe] because it is fit using CN,
and [Ca/Fe] depends on both [C/Fe] and [N/Fe], as manifested in the
range of possible CN linestrengths in the models produced by [C/Fe]
and [N/Fe] in collaboration.  These third sources of error are
estimated in a similar fashion to those produced by fiducial
uncertainties, and then the three sources of error are summed in
quadrature to estimate the total error in the abundances.

Hb, HgF, and HdF Ages errors: At the end, EZ_Ages goes back and
computes ages using all three Balmer lines (if available), regardless
of what the chosen Balmer line was for fitting.  It also computes
errors for these ages.  The errors are computed as described above for
the fiducial age (i.e., they are treated as being independent of
abundance pattern errors) with one exception: HgF is fairly sensitive
to carbon, thus errors due to uncertainties in [C/Fe] are added in
quadrature, as described above.  

The error measurements described here do a good job of matching the
results of a full Monte-Carlo error simulation (see Figure 2 of Graves
& Schiavon 2008).  If anything, they seem to slightly overestimate the
errors in noisy data.  Errors in the various stellar population
parameters are CORRELATED, as shown in Figure 3 of Graves & Schiavon,
so this should be taken into account when interpreting results.  

6. A Sanity Check

A good way to check that the abundances produced by EZ_Ages are a
reasonable match to the data is to examine the output file *_check.ps
that is generated automatically by EZ_Ages.  For each input set of
Lick indices, a full set of index-index grids is produced.  The grids
are computed using the best-fit model abundances.  If the model is a
perfect fit to the data, the data points will always lie in the same
place in age-[Fe/H] space, regardless of the indices plotted.  A check
on the robustness of EZ_Ages to the set of Lick indices chosen in
'weights.dat' is to look at the plots for other lines that were NOT
used in the fit.  The *_check.ps file can also be helpful in
diagnosing problems when EZ_Ages is not producing good results.  For
instance, if your data is consistently falling off the grid, this
should show up in the *_check.ps plots (unless your data is so far off
the grid that it doesn't show up on the plots at all!)


Known Problems
-------------------

1. Alpha-enhanced isochrone - At the recent conference "Fine Tuning Stellar
   Population Models", there was some conversation about whether or not there
   might be an error in the Salasnich et al. 2000 alpha-enhanced isochrone.  
   We have no further information at present, but warn the user that this 
   isochrone may be unreliable.  

2. Discrepancy between [C/Fe] as measured by G4300 vs. C4668 - DO NOT USE 
   G4300 to measure [C/Fe].  This index saturates at fairly low metallicity
   ([Fe/H] ~ -1.0) and is therefore not useful for most galaxies.  C4668 
   should produce more reliable results.  


Code Usage Examples
-----------------------

Once you have measured indices using LICK_EW (or your own index-
measuring code, you can find the best-fitting set of model abundances 
using EZ_AGES.  At the IDL prompt, type:

   EZ_AGES, 'measured_indices.txt'

where 'input_indices.txt' is the name of the file output by LICK_EW.
If there in a file of index errors measured by LICK_EW, you include
that as 

     errorfile = 'measured_indices.txt_err' 

The code will prompt you for the IMF and isochrone to use when 
modelling.  It will also ask for age and [Fe/H] "tolerances" to use in
the fit.  This basically means how close the age and [Fe/H] values
measured from non-Fe metal lines have to match the balmer-iron age and
[Fe/H] before the code should consider to have found the right match
for the enhancement ratio.  You want this to be smaller than the
inherent error in the models so that the fitting doesn't contribute to
the overall error, but the smaller it is, the longer the code takes to
run.  I usually use and age tolerance of 0.2 Gyr and an [Fe/H]
tolerance of 0.02 or 0.01 dex. 

The code produces 2 output files, plus an error output file if 
index measurment errors were provided.  The first has the name 
'measured_indices.txt.out', which has the ages and abundances 
from the best fitting model for each spectrum.  The other file 
is a postscript file 'measured_indices.txt_check.ps' that plots 
the grids for the best fitting model against the data for each 
input spectrum.  If the point is plotted in red, that set of 
indices was used in the model fit.  If the point is plotted in 
green, that set of indices was not used in the model fit.  There 
are 3 pages of plots for each input spectrum.

EZ_Ages does not try to fit the abundances [O/Fe], [Na/Fe], [Si/Fe],
[Cr/Fe], or [Ti/Fe], although these are parameters used by the
underlying Schiavon 2007 SSP model.  As defaults, [O/Fe] is set to
match the abundance pattern of the chosen isochrone, [Cr/Fe] is set to
solar (ie. [Cr/Fe] = 0) and Na, Si, and Ti are all assumed to track
Mg, so [Na/Fe] = [Si/Fe] = [Ti/Fe] = [Mg/Fe].  You can override these
defaults by specifying an abundance for any of these elements, with
the optional inputs:

    o_fe = 
    cr_fe = 
    na_fe = 
    si_fe = 
    ti_fe = 

Example:

    EZ_AGES, 'measured_indices.txt', $
              errorfile = 'measured_indices.txt_err', $
	      o_fe = 0.3, cr_fe = 0.1, na_fe = 0.2, $
	      si_fe = 0.4, ti_fe = 0.5

Any abundance that is not specified is assigned the default value.

Additional Options: 

Rather than waiting to be prompted for your choice of IMF, isochrone,
and other model parameters, you can optionally enter them at the
command line, with the options:

    EZ_AGES, 'measured_indices.txt', $
              errorfile = 'measured_indices.txt_err', $
	      imf = 1.35, isochrone = 1, age_tol = 0.2, $
	      fe_tol = 0.05