WikiStart: photdocs.txt

----- Documentation for Phot\average_magnitudes.pro -----
 NAME:
      AVERAGE_MAGNITUDES

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      average magnitude measurements (with direct bootstrap if number of
      measurements ge NB_DATA_BOOT)

 CATEGORY:
      photometrics

 INPUTS:
      need text input file with :
        - magnitude file name

 REQUIREMENTS:
       data read in magnitude file (in OBS_PATH/DATA directory)
       must be in ASCII format and contain (in this order, 1 spectral band
       per row) :
        - central wavelength, nber of mag to average, individual magnitudes
        and errors

 OUTPUTS:
       data written in mean magnitude file (in OBS_PATH/DATA directory)
       are (in this order) :
        - wavelength, weighted mean mag and unbiaeed stdev

 LOCAL PROCEDURE CALLED:
        RESET_PLOT

 LOCAL FUNCTION USED:
        EXTRACT_PROHEADER
        GET_OUTLIER_FENCES
        WAVG
        WSTDEV
        WSTERR

 LOCAL SYSTEM VARIABLE USED:
        NB_DATA_BOOT
        OBS_PATH
        SPIDAST_PATH

 REVISION HISTORY:
       Written by pcr 2006/05/30
       last modification by pcr 2010/12/12

----- Documentation for Phot\complete_flux_data.pro -----
 NAME:
      COMPLETE_FLUX_DATA

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      complete flux data with bandpasses and flux accuracies

 CATEGORY:
      photometrics

 INPUTS:
      needs text input file (in OBS_PATH/INP/ directory) with :
        - input flux data file name
        - input band data file name
        - correction factor for resolution (=1 if no correction)

 REQUIREMENTS:
      data read in flux file (in subdirectory of OBS_PATH/)
      must be in ASCII format and contain (in this order, 1 spectral band per row) :
        - wavelength, flux, error on flux (optionaly)

      data read in band file (in ALL_DATA_PATH/ directory)
      must be in ASCII format and contain (in this order, 1 bandpass per row) :
        - min and max wavelengths, corresponding resolutions,
        photometric accuracies (in percentage, if null use flux errors of
        input flux file)

       SWS AOT-1 resolution correction factor according to Lorente 1998
       (http://iso.esac.esa.int/users/expl_lib/SWS/aot1.ps)
       with speed 4 (6500s) used as reference (the most reliable):
         speed 1 (1200s) : R(1)/R(4)=0.38
         speed 2 (1900s) : R(2)/R(4)=0.31
         speed 3 (3600s) : R(3)/R(4)=0.58

      input/output wavelengths and bandwidths must be in same unit
      as well as fluxes and flux errors

 OUTPUTS:
      data written in output file (in same subdirectory of OBS_PATH/)
      are in same format and order with :
        - wavelength and spectral bandwidth, flux and error on flux

 LOCAL PROCEDURE CALLED:
        RESET_PLOT

 LOCAL FUNCTION USED:
        EXTRACT_PROHEADER
       TRAP

 LOCAL SYSTEM VARIABLE USED:
        ALL_DATA_PATH
        NB_DATA_MAX
        NB_RES_STEP
        OBS_PATH
        SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2007/10/02
      last modification by pcr 2010/07/21

----- Documentation for Phot\convert_lim_data.pro -----
 NAME:
      CONVERT_LIM_DATA

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      convert limb-darkened relative spectral radiance to absolute spectral
      radiance (at given spectral resolution).
      If necessary use spectral fits of limb-darken parameters to
      extrapolate radiance outside input spectral range.

 CATEGORY:
      photometrics

 INPUTS:
      need text input file (in OBS_PATH/INP/ directory) with:
        - exitance file name (input, .spec or .flux, if 'none' use radiance
        data only)
        - relative radiance file name (input, .lim or .itf)
        - min and max final wavelengths [mum]
        - nber of final radiance data per wavelength element (nb_int,
        if <0 => uses max. nber of values per wavel. in input radiance data)
        - polynomial degrees used for fits (in same row) :
            of the spectral distrib of the limb-darken to uniform-disk conversion factor
            of the radial distrib of the radiance (1:linear limb-darken, 2:quadratic LD...)
            of the spectral distrib of the limb-darken coeff(s)
           of the spectral distrib of the hanning-drop power
        - reference spectral line table and limb-darkening coefficient table for a given filter
       (in ALL_DATA/directory, 'none' if not needed)
       - optionaly : final spectral resolution at mean wavelength

 REQUIREMENTS:
      data read in the exitance file (.spec extension, in SYNTHE_PATH directory)
      must be in ASCII format and contain 2 columns of data:
        - wavelength [AA = 10^-4 mum], exitance [erg/cm^2/s/AA = 10*W/m^2/mum]

      data read in exitance file (.flux extension, in SYNTHE_PATH directory)
      must be in ASCII format and contain 3 columns of data:
        - wavelength [AA], line relative depth =
        (F(continuous)-F)/F(continuous), F/PI [erg/cm^2/s/AA] (flux must
        be multiplied by PI to fit MARCS exitance)

      data read in relative radiance file (in SYNTHE_PATH directory, name with
      first 4 characters = temperature [K], 'g' char followed with logg [cm/s^2],
      'z' with log(Fe/H) [Sun], 't' with microturbulent velocity [km/s],
      .lim or .itf extension) must be in ASCII format and contain :

      .lim files (computed by A. Jorissen)
         first line :
             - values of the linear radius [cm] : first value must be
             R(Tau Ross=1E-6) and last value must be R(Tau Ross=1),
             which are the only values to be used
         then for each spectral channel the following 3 lines :
         first line :
             - wavelength [AA], absolute intensity at center I0
             [erg/cm^2/s/AA/sr], F/PI [erg/cm^2/s/AA]
         second line :
             - wavelength, number of values, relative impact parameters
             sqrt(1-mu^2) (=1 at external radius)
         third line :
             - wavelength, number of values, relative intensity I(mu)/I0
             (=1 at center,=0 at external)

      .itf files (computed by K. Eriksson)
             - wavelength [AA] + (N+1) values of absolute intensity
           [erg/cm^2/s/AA/sr], for mu=1.0(center), 1-1/N...1/N, 0.0(limb)

      data read in line table (in ALL_DATA_PATH/directory)
      must be in ASCII format and contain :
        - wavelength [mum] and element identification

      data read in ld-coeff table (in ALL_DATA_PATH/directory)
      must be in ASCII format and contain :
             - Teff [K], logg [cm/s^2], log(M/H) [Sun], VT [km/s], 
            ld-coeff a1...a4 of non-linear law of Claret A&A 363, 1081 (2000) 
            in a given filter

      non-linear law : I(mu)/I(1)=1-a1*(1-mu^0.5)-a2*(1-mu)-a3*(1-mu^1.5)
                                 -a4*(1-mu^2)
      where I(1) is the specific intensity at the center of the disk,
      mu=cos(theta), theta being the angle between the line of sight 
      and the emergent intensity,
      or               I(mu)/I(1)=(1-a1+a2+a3+a4)*(1-b1*mm-b2*mm^2-b3*mm^3-b4*mm^4)
      where mm=mu^0.5, and b1=a1/(a1+a2+a3+a4-1), b2=a2/(a1+a2+a3+a4-1), 
                           b3=a3/(a1+a2+a3+a4-1), b4=a4/(a1+a2+a3+a4-1)

 OUTPUTS:
      data written in absolute radiance file (.limb extension, in SYNTHE_PATH
      directory) are in ASCII format and contain nb_int+1 colums of data:
      first line:
             - Rosseland to LD diameter conversion factor , relative impact
             parameters (nb_int values between 0. and 1.)
      then:
             - wavelength [mum], nb_int values of absolute radiance [W/m^2/mum/sr]

 LOCAL PROCEDURE CALLED:
      COV2COR
      ENGELKE
      LD_POLY_FIT
      LD_POLY_FUNCT
      PLANCK
      POLY_BOOT
      RESET_PLOT

 LOCAL FUNCTION USED:
      EXTRACT_PROHEADER
      GAUSSIAN
      GET_OUTLIER_FENCES
      MIN_PDR_RADIUS
      TRAP

 LOCAL SYSTEM VARIABLE USED:
      ALL_DATA_PATH
      EPSILON
      NB_DATA_BOOT
      NB_RES_STEP
      OBS_PATH
      PLOT_DEV
      SPEC_RES
      SPIDAST_PATH
      SYNTHE_PATH

 REVISION HISTORY:
      Written by pcr 2007/10/15
      last modification by pcr 2011/01/21

----- Documentation for Phot\create_spec.pro -----
 NAME:
      CREATE_SPEC

 PURPOSE:
      create synthetic blackbody/Engelke spectral radiant exitance file

 CATEGORY:
      photometrics

 INPUTS:
      need text input file with:
        - minimum wavelength (in microns)
        - maximum wavelength (in microns)
        - resolution power (lambda/bandwith) (if null => MARCS_RES)
        - effective temperature (in K)
       - function to use for calculation ('planck' or 'engelke')

 OUTPUTS:
      data written in output file are in same format as MARCS data i.e.:
        - wavelength (in Angstroems = 10^-4 mu) and exitance
        (in erg.s^-1.cm^-2.A^-1 = 10 W.m^-2.mu^-1)

 LOCAL PROCEDURE CALLED:
      ENGELKE
      PLANCK
      RESET_PLOT

 LOCAL FUNCTION USED:
      EXTRACT_PROHEADER

 LOCAL SYSTEM VARIABLE USED:
      OBS_PATH
      MARCS_RES
      SPIDAST_PATH
      SYNTHE_PATH

 REVISION HISTORY:
      Written by pcr 2006/02/07
      last modification by pcr 2010/03/06

----- Documentation for Phot\extinction.pro -----
 NAME:
      EXTINCTION

 PURPOSE:
      Calculate visual interstellar extinction due to the Milky Way.
      This code is described in AJ 114, 2043-2053 (1997).

 CATEGORY:
      photometrics

 LOCAL PROCEDURE CALLED:
        NONE

 INPUTS:
   L      = Galactic longitude (degrees)    0 <= L <  360
   B      = Galactic latitude (degrees)   -90 <= B <=  90
   D      = Source distance (in kpc)        0 <= D
   RM     = A0/E(B-V) = mean galactic extinction
            where A0 = 1.5 magnitudes per kpc

 OUTPUTS:
   AVT    = Total visual extinction (magnitudes), using available procedures.
   SAVT   = Total extinction error (magnitudes), using available procedures.
   AVC    = Visual extinction correction (mag), using available procedures.
            The corrected extinction AVT+AVC removes suspected systematics.
   JMAX   = Number of procedures used to calculate extinction.
   AV(i)  = Extinction calculated by the iTH procedure.
   SAV(i) = Error calculated by the iTH procedure.
     Specific procedures used to calculate the extinction are returned
     via AV(i): If AV(i) has a value not equal to -99, then the ith
     study has been used in calculating extinction.
     i=0 is from Fitzgerald, AJ 73, 983 (1968).
     i=1 is from Neckel and Klare, A&A Supp 42, 251 (1980).
     i=2 is from Berdnikov & Pavlovskaya, Sov. Astron. Lett. 17, 215 (1991).
     i=3 is from Arenou et al., A&A 258, 104 (1992).
     i=4 is from Chen et al., A&A 336, 137 (1998).
     i=5 is from Drimmel & Spergel, ApJ 556, 181 (2001).
     i=6 is from Penprase, ApJ. Supp. 83, 273 (1992),
                 Magnani et al., ApJ. 295, 402 (1985),
                 Keto & Myers, ApJ. 304, 466 (1986),
                 Desert et al., Ap.J. 334, 815 (1988),
                 Odenwald, Ap.J. 325, 320 (1988),
                 Hughes et al., A.J. 105, 571 (1993),
                 Kenyon et al., A.J. 108, 1872 (1994),
                 Cernis, ApSS 166, 315 (1990),
                 Cernis, Baltic Astron. 2, 214 (1993),
                 Rossano, AJ, 83, 234 (1978),
                 Rossano, AJ, 83, 241 (1978),
                 Kutner et al., ApJ, 215, 521 (1977).

   All studies have been modified to statistically account for
     unsampled regions.

 LOCAL FUNCTION USED:
       COSD
       SIND
       TAND
       GET_OUTLIER_FENCES
        WSTDEV

 LOCAL SYSTEM VARIABLE USED:
       ALL_DATA_PATH
       NB_DATA_BOOT

 REVISION HISTORY:
      Written (v. 2.0.5, May 13, 1999) by Jon Hakkila, Jeannette Myers,
      Brett Stidham, & Dieter Hartmann.
      Changes implemented since version 1.0 (Dec. 2, 1996):
      Updated error analysis for the Fitzgerald procedure.
      Fixed a coding error in the Fitzgerald procedure that caused
       extinction out of the Galactic plane to be overestimated at
       distances larger than 1 kpc.
      Fixed cell boundaries & extinction in Neckel & Klare procedure.
      More accurate angular cloud boundaries for the high-Galactic
       clouds analyzed in the high-latitude study (formerly the Penprase
       procedure). This procedure now also identifies additional high-
       Galactic latitude clouds.
      Systematic underrepresentation of extinction is corrected by using
       an additional correction term.
      Correction term now provides reasonable corrections slightly
       above and below Galactic plane beyond 5 kpc.
      Correction of Arenou procedure provided by Alain Jorissen (Mar. 19, 2008)
      Correction of Chen procedure added by Pierre Cruzalèbes (Mar. 25, 2008)
      Correction of Drimmel procedure added by Pierre Cruzalèbes (Sept. 17, 2009)
      last modification by pcr 2010/12/12

----- Documentation for Phot\interstellar_correct.pro -----
 NAME:
      INTERSTELLAR_CORRECT

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
       correct magnitudes for Galactic interstellar extinction

 CATEGORY:
      photometrics

 INPUTS: 
      need text input file with :
        - magnitude file name
        - basic data file name
        - wavelength-dependent extinction file name (ADPS, from
        Fitzpatrick, PASP 111, 63 (1999))
        - mean value of Galactic extinction (Rv=2.1, 3.1 or 5.0)

 REQUIREMENTS:
      data read in magnitude file (in subdirectory of OBS_PATH/)
      must be in ASCII format and contain (in this order, 1 spectral band
      per row) :
        - mean wavelength and equivalent width [mum], magnitude and error

      basic data file (in subdirectory of OBS_PATH/) must be in
      standard FITS format and contain the following ASCII lines with:
      RAEP0           = 'dd.ddddddd'   / Right Ascension (J2000) (deg)
      DECEP0          = '+-dd.dddddd'  / Declination (J2000) (deg)
      PARALLAX     =         ppp.pp   / Parallax (deg)
      PARA_ERR =          e.ee    / Error on Parallax (deg)

      data read in extinction file (in ALL_DATA_PATH/ directory)
      must be in ASCII format and contain (in this order, 1 spectral band
      per row) :
        - wavelength [AA] and extinction
      (extinctions are calculated for the mean value of Galactic extinction)

 OUTPUTS:
      data written in corrected magnitude file (in the same subdirectory
      of OBS_PATH/) are (in this order, 1 spectral band per row) :
        - wavelength and width, corrected magnitude and error

 LOCAL PROCEDURE CALLED:
      EULER
      EXTINCTION
      RESET_PLOT

 LOCAL FUNCTION USED:
      EXTRACT_PROHEADER

 LOCAL SYSTEM VARIABLE USED:
      ALL_DATA_PATH
      FORMAT_OUT
      MAX_DATA_HEADER
      MAX_REL_ERR
      NB_MAX_PARAM
      OBS_PATH
      SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2008/03/18
      last modification by pcr 2010/06/16

----- Documentation for Phot\Jy2Wm2mu.pro -----
 NAME:
      JY2WM2MU

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      convert flux measurements [Jy] into fluxes [W/m^2/mum]

 CATEGORY:
      photometrics

 INPUTS:
      need text input file (in OBS_PATH/INP/ directory) with :
        - input flux [Jy] file name
 
 REQUIREMENTS:
      data read in Jy flux file (in subdirectory of OBS_PATH/)
      must be in ASCII format and contain (in this order, 
      1 spectral band per row) :
        - mean wavelength and equivalent bandwidth [mum], flux and error [Jy]

 OUPUTS:
      data written in output flux file (in the same subdirectory of OBS_PATH/)
      are in same format and order and contain fluxes [W/m^2/mum]

 LOCAL PROCEDURE CALLED:
        RESET_PLOT

 LOCAL FUNCTION USED:
        EXTRACT_PROHEADER

 LOCAL SYSTEM VARIABLE USED:
        OBS_PATH
        SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2006/05/30
      last modification by pcr 2010/02/10

----- Documentation for Phot\magnitude2flux.pro -----
 NAME:
      MAGNITUDE2FLUX

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      convert magnitude measurements into fluxes in given spectral bands

 INPUTS:
      need text input file (in OBS_PATH/INP/ directory) with :
        - input magnitude file name
        - zero-mag flux file name

 REQUIREMENTS:
      data read in input magnitude file (in subdirectory of OBS_PATH/)
      must be in ASCII format and contain (in this order, 1 spectral band
      per row) :
        - wavelength and bandwidth, magnitude, error on mag

      data read in input zero-mag flux file (in ALL_DATA_PATH/ directory)
      must be in ASCII format and contain (in this order, 1 spectral band
      per row) :
        - effective wavelength and bandwidth (in same unit), zero-mag flux
        and error (in same unit)

 OUTPUTS:
      data written in output flux file (in the same subdirectory of OBS_PATH/)
      are (in this order, 1 spectral band per row) :
        - wavelength and width (of mag file), flux and error on flux
      (spectral ranges of mag and zero-mag files must overlap
      output fluxes are in same unit than input zero-mag fluxes)

 LOCAL PROCEDURE CALLED:
        RESET_PLOT

 LOCAL FUNCTION USED:
        EXTRACT_PROHEADER
        TRI_STDEV

 LOCAL SYSTEM VARIABLE USED:
        ALL_DATA_PATH
        MAX_REL_ERR
        OBS_PATH
        SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2006/05/30
      last modification by pcr 2010/06/09

----- Documentation for Phot\make_sed.pro -----
 NAME:
      MAKE_SED

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      make spectral energy distribution from flux files
      sorted in ascending spectral order
      between lambda_min and lambda_max

 CATEGORY:
      photometrics

 INPUTS:
      need text input file (in OBS_PATH/INP/ directory) with :
        - number of flux file(s) to concatenate
        - flux file name(s)
        - lambda_min and lambda_max [mu]

 REQUIREMENTS:
      data read in flux files (in subdirectory of OBS_PATH/)
      must be in ASCII format and contain (in this order, 1 spectral band
      per row) :
        - central wavelength, spectral bandwidth, flux, error on flux
      (wavelengths and bandwidths must be in the same unit
      as well as fluxes and flux errors)

 OUTPUTS:
      data written in output flux file (in the same subdirectory of OBS_PATH/)
      are in same format

 LOCAL PROCEDURE CALLED:
        RESET_PLOT

 LOCAL FUNCTIOn USED:
        EXTRACT_PROHEADER

 LOCAL SYSTEM VARIABLE USED:
        OBS_PATH
        PLOT_DEV
        SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2006/12/11
      last modification by pcr 2010/04/29

----- Documentation for Phot\scale_spectrum.pro -----
 NAME:
      SCALE_SPECTRUM

 AUTHOR:
      pierre.cruzalebes@oca.eu

 PURPOSE:
      scale one or many spectrum parts with a broadband flux
      after possible correction according to Cohen et al., AJ 104, 2030 (1992)

 CATEGORY:
      photometrics

 INPUTS:
      need text input file (in OBS_PATH/INP/ directory) with :
        - input broadband flux file name
        - broadband relative system response file name
        - nber of input spectrum file(s) and flag for bandwidth
          calculation (0=bandwidth/1=resolution, in same row)
        - input spectrum file name(s) (in same row)
        - spectral bandwidth(s) or resolution(s) (in same row)
        - input correction factor file name ('none' if no correction)

 REQUIREMENTS:
      data read in broadband flux file (in OBS_PATH/ subdirectory)
      must be in ASCII format and contain (in this order,
      1 spectral band per row) :
        - central wavelength and spectral bandwidth, flux
         and error on flux

      data read in broadband response file (in ALL_DATA_PATH/ directory)
      must be in ASCII format and contain (in this order, 
      1 wavelength per row) :
        - wavelength, relative system response
      (see http://irsa.ipac.caltech.edu/IRASdocs/exp.sup/ch2/tabC5.html)

      data read in spectrum file(s) (in the same OBS_PATH/ subdirectory)
      must be in ASCII format and contain (in this order,
      1 spectral band per row) :
        - wavelength, flux and error on flux

      data read in input correction factor file (in ALL_DATA_PATH/ directory)
      must be in ASCII format and contain (in this order,
      1 wavelength per row) :
        - wavelength, factor, sigma

      input/output wavelengths and bandwidths must be in same unit
      as well as fluxes and flux errors

 OUTPUTS:
      data written in output scaled LRS file (in the same OBS_PATH/ subdirectory)
      are in the same format and order with :
        - central wavelength and spectral bandwidth, flux and error on flux

 LOCAL PROCEDURE CALLED:
        REGUTRAP
        RESET_PLOT

 LOCAL FUNCTIOn USED:
        EXTRACT_PROHEADER

 LOCAL SYSTEM VARIABLE USED:
       ALL_DATA_PATH
        OBS_PATH
        SPIDAST_PATH

 REVISION HISTORY:
      Written by pcr 2010/04/24
      last modification by pcr 2010/04/25