INITTAGS.txt

#
# History
#   2013nov25, DSNR, created
#   2013dec10, DSNR, updated for PPXF implementation; removed stellar
#                    z and sigma optimization tags, since PPXF does
#                    this
#   2013dec19, DSNR, changed MASKWIDTHS and PEAKINIT to hashes for
#                    consistency with other tags that initialize
#                    things according to which emission lines they
#                    apply to
#   2014jan17, DSNR, added TWEAKCNTFIT
#   2014jan29, DSNR, added DATEXT, VAREXT, DQEXT
#   2014feb17, DSNR, added PPXF_MAXDEG_ADDPOLY, removed ADDPOLY2TEMP
#   2014feb27, DSNR, added ZSYS_GAS, PLATESCALE, SPECRES
#   2014apr17, DSNR, added ARGSMAKEMAP
#   2014mayXY, DSNR, added FCNCHECKCOMP
#   2014may08, DSNR, added ARGSNORMNAD, ARGSPLTNORMNAD
#   2014may09, DSNR, added a bunch of NaD-related tags
#   2014may15, DSNR, added ARGSNADWEQ
#   2014may23, DSNR, moved ARGSMAKEMAP structure and NaD parameters 
#                    to their own variables
#   2014jul11, DSNR, updates to INITNAD and INITMAP structures
#   2015jun03, DSNR, added NAD_CONTCUTRANGE
#   2015jun08, DSNR, added continuum peak fitting tags
#

This file describes the parameters that are contained in the INITDAT,
INITMAPS, and INITNAD structures. These structures are created in the
initialization procedure and passed to IFSF, IFSFA, IFSF_MAKEMAPS,
IFSF_FITNAD, and other routines, and contain parameters that apply to
the dataset as a whole (e.g., the lines to be fit or an array
containing the initial redshift guesses for all spaxels). IFSF passes
INITDAT to IFSF_FITSPEC without changing it.

=======
INITDAT
=======

Tags are in alphabetical order.

Required structure tags from initialization procedure:

  fcninitpar: in, required, type=string
    Name of function for initializing emission lines.
  infile: in, required, type=string
    Filename (possibly including path) of input data cube.
  label: in, required, type=string
    Common label for output files.
  lines: in, required, type=strarr(nlines)
    Names of emission lines to fit.
  linetie: in, required, type=hash(lines)
    Name of emission line to which each emission line is tied
    (in redshift and linewidth).
  mapdir: in, required, type=string
    Directory for output maps.
  maxncomp: in, required, type=double
    Maximum number of components to fit.
  name: in, required, type=string
    Name of object.
  ncomp: in, required, type=hash(lines,ncols,nrows)
    For each spaxel and emission line, # of components to fit.
  outdir: in, required, type=string
    Directory for output .xdr file and analysis files (plots, lists).
  platescale: in, required, type=double
    Size of pixel in arcseconds.
  positionangle: in, required, type=double
    Position angle of IFS FOV, in degrees E of N.
  specres: in, required, type=double
    Spectral resolution of spectrograph in Angstroms, used for
    correcting linewidths for the instrumental profile. Code does not
    yet properly handle instruments with constant resolution in km/s,
    at least in this respect.
  zinit_stars: in, required, type=dblarr(ncols,nrows)
    Redshift used to shift any stellar templates to observed
    frame.
  zinit_gas: in, required, type=hash(lines,ncols,nrows,maxncomp)
    Initial redshift guesses for each spaxel, emission line, and
    component.
  zsys_gas: in, required, type=double
    Systemic redshift for gas, used for calculating velocities
    w.r.t. systemic.

Optional structure tags from initialization procedure:

  argscontfit: in, optional, type=structure
    Arguments for continuum fit routine.
    For PPXF: add_poly_degree: in, optional, type=integer, default=4
    	         Degree of additive polynomial.
  argsinitpar: in, optional, type=structure
    Arguments for parameter initialization routine.
  argslinefit: in, optional, type=structure
    Arguments for line fitting routine
  argslinelist: in, optional, type=structure
    Arguments for line selection routine
  argspltlin1: in, optional, type=structure
    Arguments for first line plot
  argspltlin2: in, optional, type=structure
    Arguments for second line plot
  batchdir: in, optional, type=str
    Path to location for storing temporary batch files for multicore
    processing.
  batchfile: in, optional, type=str
    Name of routine to loop over for multicore processing;
    should probably be the path to and name of IFSF_FITLOOP.
  datext: in, optional, type=integer, default=1
    Extension # for data plane in data cube.
  dividecont: in, optional, type=byte
    Set this param to divide the data by the continuum
    fit. Default is to subtract.
  dqext: in, optional, type=integer, default=3
    Extension # for dq plane in data cube.
  donad: in, optional, type=byte
    Run NaD analysis (normalization and finding weq) in IFSFA.
  emlkeeperr: in, optional, type=byte
    If set, keep the flux errors untouched even when the line is
    removed by EMLSIGCUT.
  emlsigcut: in, optional, type=double
    Threshold sigma for filtering individual emission lines in IFSFA.
  fcncheckcomp: in, optional, type=string
    Name of function for automatically testing significance of
    components.
  fcncontfit: in, optional, type=string
    Name of continuum fitting function. If not specified, no continuum
    is fit. If this equals 'ppxf,' then PPXF is used to fit the
    stellar velocity, velocity dispersion, and template weights. PPXF
    requires a template to be chosen and an initial guess for sigma
    (siginit_stars) to be specified.
  fcnlinefit: in, optional, type=string
    Name of line fitting function. Default: IFSF_MANYGAUSS
  fcnpltcont: in, optional, type=string
    Name of continuum plotting function. Default: IFSF_PLTCONT
  fcnpltlin: in, optional, type=string
    Name of line plotting function. Default: IFSF_PLTLIN
  fitran: in, optional, type=dblarr(2)
    Range of fitting, in observed frame. If not set, default is
    entire range of data / template intersection.
  keepnad: in, optional, type=string
    Set to not remove NaD region from fit.  If keepnad is not set, then
    the wavelength range [5850,5900] is multiplied by the stellar
    redshift in that spaxel and the errors in that range are set to
    the max. possible to minimize their weight in the fit.
  logfile: in, optional, type=string
    Log file; default is to output messages to STDOUT.
  loglam: in, optional, type=byte
    Set if data has constant log(lambda) dispersion.
  maskctran: in, optional, type=dblarr(2,nmaskreg)
    Mask continuum regions by hand during fitting. The first dimension holds
    the lower and upper wavelength of each region to mask.
  maskwidths: in, optional, type=hash(lines,maxncomp)
    Widths, in km/s, of regions to mask from continuum fit. If not
    set, routine defaults to a value specified in IFSF_FITSPEC
    for all lines and components.
  masksig_secondfit: in, optional, type=double
    During second call to IFSF_FITSPEC, best-fit emission line sigmas
    are multiplied by this value and set to 'maskwidths' parameter. If
    not set, routine defaults to a value specified in IFSF for all
    lines and components.
  nad_contcutrange: in, optional, type=dblarr(2)
    If keepnad is not set, then the wavelength range [5850,5900] is
    multiplied by the stellar redshift in that spaxel and the errors in that
    range are set to the max. possible to minimize their weight in the fit.
    Set this parameter to choose the (observed) wavelength range to exclude;
    this range is *not* multiplied by anything.
  noemlinfit: in, optional, type=dblarr(2)
    Fit continuum only.
  nomaskran: in, optional, type=dblarr(2)
    Wavelength region *not* to mask.
  peakinit: in, optional, type=hash(lines,maxncomp)
    Initial peak flux guesses.
  peakinit: in, optional, type=hash(lines,maxncomp)
    Initial peak flux guesses.
  ppxf_maxdeg_addpoly: in, optional, type=integer, default=4
    Highest degree of additive Legendre polynomial terms added to the
    stellar templates in PPXF. This is also the number of terms added,
    one per degree up to the maximum. Set to -1 to not include any
    additive polynomials.
  siginit_gas: in, optional, type=hash(lines,maxncomp)
    Initial line width guesses, in sigma and km/s.  If not
    set, routine defaults to a value specified in IFSF_FITSPEC
    for all lines and components.
  siginit_stars: in, optional, type=double
    Initial sigma value, in km/s, for a Gaussian kernel for
    convolving with stellar template. Convolution only performed
    if this param is set.
  startempfile: in, optional, type=structure
    File containing IDL save file (usually ending in .xdr) of
    stellar templates. Tags:
      lambda: in, required, type=dblarr(nwave)
      flux: in, required, type=dblarr(nwave,ntemplates)
  tweakcntfit: in, optional, type=dblarr(ncols,nrows,3,maxregions)
    Parameters for tweaking continuum fit with localized
    polynomials. For each of nregions regions, array contains lower
    limit, upper limit, and polynomial degree.
  vacuum: in, optional, type=byte
    Set this param to shift stellar templates from air to
    vacuum wavelengths.
  varext: in, optional, type=integer, default=2
    Extension # for variance plane in data cube.

========
INITMAPS
========

Required tags:
  nadabsweq_snrthresh: in, required, type=double
    Per-spaxel signal-to-noise threshold for plotting/analysis of NaD
    absorption line data. Required only if DONAD is set in INITDAT.
  nademweq_snrthresh: in, required, type=double
    The same as above, but for emission line data. Required only if
    DONAD is set in INITDAT and emission-line data is present.
  nademflux_cbint: in, required, type=double
    Color bar interval for mapping NaD emission line data. Required
    only if DONAD is set in INITDAT and emission-line data is present.

Misc. optional tags:
  argslinratmaps: in, optional, type=structure
    If set, line ratios are plotted. The following tags govern the
    image ...
  badnademp: in, optional, type=dblarr(ncols,nrows)
    Flags to ignore empirical NaD results. 0 = keep, 1 = ignore
  center_axes: in, optional, type=dblarr(2)
    Coordinates of the 0-point of the map axes. Defaults to the map
    center. Also used to define the radius maps (MAP_R, etc).
  center_nuclei: in, optional, type=dblarr(2)
    Coordinates of the galaxy nucleus, for plotting and computation of
    the rotation center for aligning continuum images with the IFS
    data. Defaults to CENTER_AXES.
  fcn_oplots: in, optional, type=string
    Name of ancillary procedure for further plotting. This routine has
    INITDAT, INITMAPS, and PLOTINFO as its required parameters. (See
    IFSF_MAKEMAPS for contents of PLOTINFO.) Data can be passed from
    IFSF_MAKEMAPS to this routine by specifying the names of variables
    in IFSF_MAKEMAPS as keyword parameters and by listing them as
    string variables in the array TAGS_OPLOTS (see below).
  fluxfactor: in, optional, type=double
    Factor by which emission-line fluxes are multiplied.
  fluxunfactor: in, optional, type=double
    Factor by which ...
  fluxunits: in, optional, type=string
  noemlinfit: in, optional, type=byte
    Set this switch if the spectrum was not first processed with
    IFSF.
  rangefile:  in, optional, type=string
    Full path and file name for file to manually set color scale
    ranges for plots.
  tags_oplots: in, optional, type=strarr
    See FCN_OPLOTS.

Optional tags for continuum images:

  ebv: in, optional, type=structure
     Parameters controlling how E(B-V) is calculated.
     calc: in, optional, type=strarr
       List of keys in EMLFLX hash governing 
  col: in, optional, type=structure
     If set, IFS continuum color image is created. The following
     tags govern the image.
     sumrange: in, required, type=dblarr(4)
       Lower and upper wavelength limits for summing together the blue
       and red continuum regions.
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
  ct: in, optional, type=structure
     If set, IFS continuum image is created. The following
     tags govern the image.
     beta: in, optional, type=double
       Beta parameter if stretch = 5 (ASINH).
     domedian: in, optional, type=byte
       Use the (median x (# of pixels)) to compute total of continuum, rather
       than the average, if there's too much junk data.
     fitifspeak: in, optional, type=byte
       Whether or not to fit nuclear peak of IFS continuum data.
     fitifspeakwin_kpc: in, optional, type=double
       Width of (square) window in kpc for doing peak fitting.
     sumrange: in, required, type=dblarr(2)
       Lower and upper wavelength limits for summing the continuum.
     sumrange_hstcomp: in, optional, type=dblarr(2)
       Lower and upper wavelength limits for summing the continuum
       (for comparing to HST images).
     sumrange_lab: in, optional, type=string
       Set to 'microns' to print continuum region labels in microns
       (instead of A, the default).
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
  hst: in, optional, type=structure
     If set (along with hstbl and/or hstrd), HST continuum image is
     loaded and plotted. The following tags govern the image.
     fithstpeak: in, optional, type=byte
       Whether or not to fit nuclear peak of HST data at native
       resolution that has been trimmed and rotated to match IFS data.
     fithstpeakwin_kpc: in, optional, type=double
       Width of (square) window in kpc for doing peak fitting.
     fithstpeakconv: in, optional, type=byte
       Whether or not to fit nuclear peak of HST data that has been
       trimmed, rotated, seeing-convolved, and resampled to match IFS
       data.
     fithstpeakconvwin_kpc: in, optional, type=double
       Width of (square) window in kpc for doing peak fitting.
     refcoords: in, required, type=intarr(2)
       Coordinates of reference point for aligning HST and IFS images.
     subim_sm: in, required, type=double
       Size of one side of (square) small subimage in arcseconds.
     subim_big: in, required, type=double
       Size of one side of (square) big subimage in arcseconds.
     smoothfwhm: in, required, type=double
       FWHM of Gaussian smoothing kernel, in pixels.
  hstbl: in, optional, type=structure
     If set (along with hst), blue HST continuum image is loaded and
     plotted. The following tags govern the image.
     file: in, required, type=string
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs_big,_sm,_fov: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     photflam: in, required, type=double
       Value for computing photometric parameters; from image header.
       Presently required only for computing a color image.
     photplam: in, required, type=double
       Value for computing photometric parameters; from image header.
       Presently required only for computing a color image.
  hstblsm: in, optional, type=structure
     If set (along with hstbl and hst), smoothed blue HST continuum
     image is created and plotted. The following tags govern the
     image.
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs_big,_sm,_fov: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
  hstrd: in, optional, type=structure
     If set (along with hst), red HST continuum image is loaded and
     plotted. The following tags govern the image.
     file: in, required, type=string
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     photflam: in, required, type=double
       Value for computing photometric parameters; from image header.
       Presently required only for computing a color image.
     photplam: in, required, type=double
       Value for computing photometric parameters; from image header.
       Presently required only for computing a color image.
  hstrdsm: in, optional, type=structure
     If set (along with hstrd and hst), smoothed red HST continuum
     image is created and plotted. The following tags govern the
     image.
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
  hstcol: in, optional, type=structure
     If set (along with hstrd and hstbl), HST continuum color
     image is created and plotted. The following tags govern the
     image.
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
     ncbdiv: in, required, type=int
       Number of color bar divisions for color maps.
  hstcolsm: in, optional, type=structure
     If set (along with hstrd, hstbl, hstrdsm, and hstblsm), smoothed
     HST continuum color image is created and plotted. The following
     tags govern the image.
     scllim: in, required, type=dblarr(2)
       Lower and upper flux limits for byte scaling.
     sclargs: in, required, type=structure
       Optional arguments for byte scaling routine (CGIMGSCL). If no
       arguments, then input a dummy tag.
     stretch: in, required, type=int
       Function for byte scaling data. See CGIMGSCL for a list of
       possible values.
     ncbdiv: in, required, type=int
       Number of color bar divisions for color maps.
  xsec: in, optional, type=structure
     If set, computes cross sections in the CVDF velocity or flux map
     of choice.
     line: in, required, type=strarr
     tag: in, required, type=strarr
       Which CVDF property to X-section (vpk, v50, fpk, etc.)
     angle: in, required, type=dblarr
       Angle CCW from +y axis.
     length: in, required, type=dblarr
       Total length of X-section in spaxels.




=======
INITNAD
=======

Required parameters:
  fcninitpar: in, required, type=string
    Name of function for initializing NaD + HeI fit.
  heitie: in, required, type=dblarr(ncols,nrows)
    Emission line to use for initializing fit of HeI 5876. If set to a
    null string (''), no line is fit. If set to 'HeI5876', the fit is
    not tied to another line. If set to another line that was fit with
    IFSF (using the string name specified in IFSF_LINELIST), the
    number of components, central line wavelength(s), and line
    width(s) are fixed and the line fluxes are allowed to vary.
  maxncomp: in, required, type=int
    Maximum number of HeI, NaD absorption, or NaD emission components.
  mcniter: in, required, type=int
    Number of iterations in Monte Carlo error simulations.
  nadabs_siginit: in, required, type=dblarr(ncols,nrows,maxncomp)
    Initial sigma guesses for NaD absorption line fits.
  nadabs_siglim: in, required, type=dblarr(2)
    Limits to sigma for NaD absorption.
  nadabs_zinit: in, required, type=dblarr(ncols,nrows,maxncomp)
    Initial redshift guesses for NaD absorption line fits.
  nadem_siginit: in, required, type=dblarr(ncols,nrows,maxncomp)
    Initial sigma guesses for NaD emission line fits.
  nadem_siglim: in, required, type=dblarr(2)
    Limits to sigma for NaD emission.
  nadem_zinit: in, required, type=dblarr(ncols,nrows,maxncomp)
    Initial redshift guesses for NaD emission line fits.
  nnadabs: in, required, type=intarr(ncols,nrows)
    Number of NaD absorption components to fit.
  nnadem: in, required, type=intarr(ncols,nrows)
    Number of NaD emission components to fit.

Optional parameters:
  argsinitpar: in, optional, type=structure
    Arguments for initializing NaD + HeI fit.
  argsnadweq: in, optional, type=structure
    Arguments for computing NaD equivalent width.
    autoindices: out, optional, type=intarr(4)
      Array indices for lower and upper wavelength limits for
      automatically discovered NaD absorption and emission lines. Set
      to 1 as input to retrieve output.
    autowavelim: in, optional, type=dblarr(4)
      Lower and upper wavelength limits for automatically searching
      for NaD absorption and emission lines.
  argsnormnad: in, optional, type=structure
    Arguments for normalization of NaD continuum. 
    fitranlo: in, optional, type=dblarr(2)
      Lower and upper wavelength limits of lower range for NaD
      continuum fit. Presently, lower limit of HeI+NaD profile fit
      range defaults to lower limit of this range. Default:
      (1+z)*[5810,5865]
    fitranhi: in, optional, type=dblarr(2)
      Lower and upper wavelength limits of upper range for NaD
      continuum fit. Presently, upper limit of HeI+NaD profile fit
      range defaults to lower limit of this range. Default:
      (1+z)*[5905,5960]
  argspltfitnad: in, optional, type=structure
    Arguments for plotting NaD fit.
    yran: in, optional, dblarr(2)
      Flux range to plot.
  argspltnormnad: in, optional, type=structure
    Arguments for plotting normalization of NaD continuum.
    fitranlo: in, optional, type=dblarr(2)
      See argsnormnad.
    fitranhi: in, optional, type=dblarr(2)
      See argsnormnad.
    pltran: in, optional, dblarr(2)
      Wavelength range to plot.
  fcnfitnad: in, optional, type=string
    Name of function for initializing NaD + HeI fit.
  hei_fix: in, optional, type=bytarr(ncols,nrows,maxncomp,3)
    Array of fix/free flags for HeI line parameters. 0=free, 1=fix
  hei_siginit: in, optional, type=dblarr(ncols,nrows,maxncomp)
    Initial sigma guesses for HeI emission line fits. Needed if HeI
    is fit without being tied to fits of other lines.
  hei_zinit: in, optional, type=dblarr(ncols,nrows,maxncomp)
    Initial redshift guesses for HeI emission line fits. Needed if HeI
    is fit without being tied to fits of other lines.
  heitiecol: in, optional, type=intarr(ncols,nrows)
    Column number of spaxel to which to tie the HeI fit.
  heitierow: in, optional, type=intarr(ncols,nrows)
    Row number of spaxel to which to tie the HeI fit.
  nadabs_fix: in, optional, type=bytarr(ncols,nrows,maxncomp,4)
    Array of fix/free flags for NaD absorption line parameters. 0=free, 1=fix
  nadabs_cfinit: in, required, type=dblarr(ncols,nrows,maxncomp), default=0.5d
    Initial covering factor guesses for NaD absorption line fits.
  nadabs_tauinit: in, required, type=dblarr(ncols,nrows,maxncomp), default=0.5d
    Initial tau guesses for NaD absorption line fits.
  nadem_finit: in, optional, type=dblarr(ncols,nrows,maxncomp), default=0.1d
    Initial flux peak guesses for NaD emission line fits.
  nadem_fitinit: in, optional, type=byte
    Flag to enable a "first fit" of NaD emission only; wavelengths
    blueward of the emission region detected with IFSF_CMPNADWEQ are
    set to 1.
  nadem_fix: in, optional, type=bytarr(ncols,nrows,maxncomp,4)
    Array of fix/free flags for NaD emission line parameters. 0=free, 1=fix
  nadem_rinit: in, optional, type=dblarr(ncols,nrows,maxncomp), default=1.5d
    Initial flux ratio guesses for NaD emission line fits.
  nhei: in, optional, type=intarr(ncols,nrows)
    Number of HeI components to fit. Needed if HeI is fit without
    being tied to fits of other lines.
  noemlinfit: in, optional, type=byte
    Set this switch if the spectrum was not first processed with
    IFSF.
  taumax: in, optional, type=double, default=5
    Optical depth upper limit for NaD fitting.