TABLE OF CONTENTS

1. SOLAR_IRRADIANCE_FCDR/bin_average.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   bin_average

PURPOSE

   The bin_average.pro is a function that performs time averaging of data records.

DESCRIPTION

   The bin_average.pro is a function that performs time averaging of data records. The data records 
   are assumed to be a list of structures where the first element is time in Modified Julian Date (MJD)
   and the second element is the value to be averaged. All other structure elements are ignored.  
   'bin' 

INPUTS

   records   - The data records (a list of structures) containing the Modified Julian Date and the value to be averaged
   bin       - Designates the time averaging.  It is either 'year' or 'month' or 'day'. The default is 'day'.

OUTPUTS

   averaged  - An IDL hash mapping of the iso time to the average of the values in the records for that time bin.

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=bin_average(records, bin)

2. SOLAR_IRRADIANCE_FCDR/bin_ssi.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   bin_ssi.pro

PURPOSE

   The bin_ssi.pro function is called from the routine, process_irradiance.pro.  It bins the 
   Solar Spectral Irradiance into a variable-sized wavelength grid as defined in get_spectral_bins.pro.
   The wavelength grid is as follows:
   1 nm from 115 to 750
   5 nm from 750 to 5000
   10 nm from 5000 to 10000
   50 nm from 10000 to 100000

DESCRIPTION

   The bin_ssi.pro function uses wavelength grid information (number of bands, bandcenters, and bandwidths),
   and bins the Solar Spectral Irradiance onto the wavelength grid, defined by bandcenter and 
   bandwidth. 

INPUTS

   model_params  - a structure containing wavelength values of modeled SSI on 
     lambda      - wavelength (nm; in 1-nm bins)
   spectral_bins - a structure containing the desired wavelength grid information of the output SSI:
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid. 
   ssi           - a structure containing the modeled SSI:
     nrl2        - the NRL2 modeled Solar Spectral Irradiance at 1 nm spectral resolution
     nrl2unc     - the uncertainty of the modeled Solar Spectral Irradiance

OUTPUTS

   ssi_bin      - a structure containing the following variables:
     nrl2bin    - the binned NRL2 modeled Solar Spectral Irradiance, on a variable wavelength grid
     nrl2binunc - the uncertainty of the modeled Solar Spectral Irradiance, binned for the variable wavelength grid
     nrl2binsum - the sum of the binned irradiance (equal to nrl2bin * bandwidth).  

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=bin_ssi(model_params, spectral_bins, ssi)

3. SOLAR_IRRADIANCE_FCDR/compute_ssi.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   compute_ssi.pro

PURPOSE

   The compute_ssi.pro procedure is a function called by the routine,process_irradiance,pro,
   to compute Solar Spectral Irradiance using multiple regression coefficients specific to 
   the NRLSSI2 model and given values for the sunspot darkening function and the facular brightening function.

DESCRIPTION

   The compute_ssi.pro function calculates the Solar Spectral Irradiance (SSI) for a specific day, given
   values for the sunspot darkening and the facular brightening function using a 2-component multiple regression formula.
 
   Variable Definitions:
   I(k,t) it the spectral (k) and time-dependency (t) of SSI.
   delta_I_F(k,t) is similarly described, but for SSI, and is also spectrally dependent 
   delta_I_S(t) is similarly described, but for SSI, and is also spectrally dependent
   I_Q is the SSI of the adopted Quiet Sun reference spectrum.
   
   2-Component Regression formulas: 
   I(k,t) = I_Q + delta_I_F(t) + delta_I_S(t)
   
   Quantifying time and spectrally-dependent SSI (I) Irradiance variation from Faculae (F) and Sunspot (S):
   delta_I_F(k,t) = c_F(k) + d_F(k) * [F(t) - F_Q] + e_F * [F(t) - F_Q]
   delta_I_S(k,t) = c_S(k) + d_S(k) * [S(t) - S_Q] + e_S * [S(t) - S_Q]
   
   Coefficients for faculae and sunspots:
   The c(k), and d(k) coefficients for faculae and sunspots are specified (determined using multiple linear regression) 
   and supplied with the algorithm. These coefficients best reproduce the detrended SSI irradiance variability (removal of 81-day running mean) 
   measured by SORCE SIM. 
   Note, the c_F and c_S coefficient is nominally zero so that when F=F_Q and S=S_Q, then I=I_Q.
   The additional wavelength-dependent terms in the spectral irradiance facular and sunspot components evaluated with the 
   e coefficients provide small adjustments to ensure that 1) the numerical integral over wavelength of the solar spectral irradiance is 
   equal to the total solar irradiance, 2) the numerical integral over wavelength of the time-dependent SSI irradiance variations from
   faculae and sunspots is equal to the time-dependent TSI irradiance variations from the faculae and sunspots. 
   
   Additional explanation of coefficients used to model solar spectral irradiance: 
   A relationship of solar spectral irradiance variability to sunspot darkening and facular brightening determined using observations of 
   solar rotational modulation: instrumental trends are smaller over the (much) shorter rotational times scales than during the solar cycle. 
   For each 1 nm bin, the observed spectral irradiance and the facular brightening and sunspot darkening indices are detrended by 
   subtracting 81-day running means. Multiple linear regression is then used to determine the relationships of the detrended time series:
   
   I_detrend_mod(k,t) = I_mod(k,t) - I_smooth(k,t)
                      = c(k) + d_F_detrend(k) * [F(t) - F_smooth(t)] + d_S_detrend(k) * [S(t) - S_smooth(t)]
                      
   Variable Definitions:
   I_mod(k,t) = the spectral (k) and time (t) dependecies of the modeled spectral irradiance, I_mod.
   I_smooth(k,t) = the spectral and time dependences of the smoothed (i.e. after subtracting 81-day running mean) from observed spectral irradiance.
   F_smooth(t) = the time dependency of the smoothed (i.e. after subtracting 81-day running mean) from observed facular brightening index, F(t).
   S_smooth(t) = as above, but for the observed sunspot darkening index, S(t).
   
   The range of facular variability in the detrended time series is smaller than during the solar cycle which causes the coefficients
   of models developed from detrended time series to differ from those developed from non-detrended observations. To address this, total
   solar irradiance observations are used to numerically determine ratios of coefficients obtained from multiple regression using direct observations,
   with those obtained from multiple regression of detrended observations. Using a second model of TIM observations (using detrended observations) 
   was determined and the ratios of the coefficients for the two approaches were used to adjust the coefficients for spectral irradiance variations.
   
   For wavelengths > 295 nm, where both sunspots and faculae modulate spectral and total irradiance, 
   the d coefficients, d_F and d_S are estimated as:
   d_F(k) = d_F_detrend(k) * [b_F / b_F_detrend]
   d_S(k) = d_S_detrend(k) * [b_S / b_S_detrend]
   
   For wavelengths < 295 nm, where faculae dominate irradiance variability (d_S(k) ~ 0), the adjustments for 
   the coefficients are estimated using the Ca K time series, a facular index independent of Mg II index, and a proxy for UV
   spectral irradiance variability.
   
   Reference(s):
   Reference describing the solar irradiance variability due to linear combinations of sunspot darkening
   and facular brightening: 
      Fröhlich, C., and J. Lean, The Sun’s total irradiance: Cycles, trends
      and climate change uncertainties since 1976, Geophys. Res. Lett., 25, 4377‐4380, 1998.
   References describing the original NRLTSI and NRLSSI models are:
      Lean, J., Evolution of the Sun's Spectral Irradiance Since the Maunder Minimum, Geophys. Res. Lett., 27, 2425-2428, 2000.
      Lean, J., G. Rottman, J. Harder, and G. Kopp, SORCE Contributions to New Understanding of Global Change and Solar Variability,
      Solar. Phys., 230, 27-53, 2005.
      Lean, J. L., and T.N. Woods, Solar Total and Spectral Irradiance Measurements and Models: A Users Guide,
      in Evolving Solar Physics and the Climates of Earth and Space, Karel Schrijver and George Siscoe (Eds), Cambridge Univ. Press, 2010.
   Reference describing the extension of the model to include the extreme ultraviolet spectrum and the empirical capability to specify 
   entire solar spectral irradiance and its variability from 1 to 100,000 nm:
      Lean, J. L., T. N. Woods, F. G. Eparvier, R. R. Meier, D. J. Strickland, J. T. Correira, and J. S. Evans,
      Solar Extreme Ultraviolet Irradiance: Present, Past, and Future, J. Geophys. Res., 116, A001102, 
      doi:10.1029/2010JA015901, 2011.

INPUTS

   sb           - sunspot darkening indice
   mg           - facular brightening indice
   model_params - a structure containing NRL2 coefficients necessary to construct modeled TSI:
     lambda     - wavelength (nm; in 1-nm bins)
     iquiet     - the adopted solar spectral irradiance of the Quiet Sun
     ccoef      - the sum of the 'c' multiple regression coefficient for spectral facular brightening (equal to c_F(k), in above description)
                  and the 'c' multiple regression coefficient for spectral sunspot darkening (equal to c_S(k), in above description)
     dfaccoef   - the 'd' multiple regression coefficient for spectral facular brightening (equal to d_F(k), in above description);
                  obtained from regression against detrended spectral irradiance observations multiplied with the ratio of the 'b' coefficients
                  obtained from regression against total solar irradiance observations to that obtained from regression against detrended total 
                  solar irradiance observations.
     dspotcoef  - the 'd' multiple regression coefficient for spectral sunspot darkening (equal to d_S(k), in above description);
                  obtained from regression against detrended spectral irradiance observations multiplied with the ratio of the 'b' coefficients
                  obtained from regression against total solar irradiance observations to that obtained from regression against detrended total 
                  solar irradiance observations.  
     bfaccoef   - the 'b' multiple regression coefficient for bolometric facular brightening (equal to b_F, in above description)
     bspotcoef  - the 'b' multiple regression coefficient for bolometric sunspot darkening (equal to b_S, in above description)
     mgquiet    - the value of the facular brightening corresponding to quiet Sun (equal to F_Q, in above description)
     efaccoef   - the small, but nonzero, correction factor needed so the numerical integral over wavelength of the time-dependent 
                  SSI irradiance variations from faculae is equal to the time-dependent TSI irradiance variations from the faculae.
     espotcoef  - the small, but nonzero, correction factor needed so the numerical integral over wavelength of the time-dependent 
                  SSI irradiance variations from sunspots is equal to the time-dependent TSI irradiance variations from sunspots.             
     tsisigma   - the 1-sigma uncertainty estimates for the coefficients returned in the multiple linear 
                  regression of TSI. A 3-element array where first element contains the uncertainty in acoef (equal 
                  to a_F_unc in above description), the second element contains the uncertainty in bfaccoef (equal to 
                  b_F_unc in above description), and the third element contains the uncertainty in bspotcoef (equal to
                  b_S_unc in above description).
     mgu        - the relative uncertainty in change in facular brightening from its minimum value, mgquiet. Specified as 0.2 (20 %)
     sbu        - the relative uncertainty in change in sunspot darkening from its minimum value, '0'. Specified as 0.2 (20%)
     faccfunc   - the relative uncertainty estimate for the coefficients of spectral facular brightening obtained from multiple linear
                  regression of the detrended spectral observations, and detrended indices. Corrected by a scaling factor
                  derived from the ratio of linear regression coefficients from TSI observations and detrended TSI observations. 
                  Also accounts for autocorrelation.
     spotcfunc  - the relative uncertainty estimate for the coefficients of spectral sunspot darkening obtained from multiple linear
                  regression of the detrended spectral observations, and detrended indices. Corrected by a scaling factor
                  derived from the ratio of linear regression coefficients from TSI observations and detrended TSI observations. 
                  Also accounts for autocorrelation.
     qsigmafac  - the absolute uncertainty in the 'coeff0fac' factor 
     coeff0fac  - the regression coefficient that linearly relates the facular brightening index to the residual energy in the facular 
                  brightening index; only the 2nd element in the array (i.e. the "slope" coefficient) is used in the uncertainty propagation
     qsigmaspot - the absolute uncertainty in the small, but nonzero 'coeff0spot' factor 
     coeff0spot - the regression coefficient that linearly relates the sunspot darkening index to the residual energy in the sunspot darkening
                  index; only the 2nd element in the array (i.e. the "slope" coefficient) is used in the uncertainty propagation
     ccoefunc   - the absolute uncertainty in 'ccoef'

OUTPUTS

   ssi   - a structure containing the following variables:
     nrl2 - modeled solar spectral irradiance
     dfactot - spectrally integrated value of the facular brightening
     dspottot - spectrally integrated value of the sunspot darkening 
     nrl2tot - spectrally integrated value of the SSI, nrl2
     nrl2unc - spectrally dependent uncertainty in the modeled solar spectral irradiance

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=compute_ssi(sb, mg, model_params)

4. SOLAR_IRRADIANCE_FCDR/compute_sunspot_blocking.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   compute_sunspot_blocking.pro

PURPOSE

   The compute_sunspot_blocking.pro procedure computes the sunspot blocking function using a formula that weights the 
   heliographic area of the sunspot group corrected by the solar latitude (corrected for ecliptic plane variation) and longitude.

DESCRIPTION

   The compute_sunspot_blocking.pro procedure computes the sunspot blocking function using a formula that weights the 
   heliographic area of the sunspot group corrected by the solar latitude (corrected for ecliptic plane variation) and longitude.
   The calculation effectively sums the projected area of sunspot regions on the solar hemisphere and multiplies this by the 
   contrast of sunspots relative to the background (reference) Sun, taking into account variations with limb position on the solar disk.
   [Lean, J.L., Cook, J., Marquette, W., and Johannesson, A.: 1998, Astrophys. J., 492, 390-401].
   It does not include empirical corrections for the additional darkness of larger sunspot than smaller sunspots  
   [Brandt, P, N., Stix, M., and Wdinhardt, H.: 1994, Solar Phys. 152 (119)]. 
   
   Formula (from Lean et al., 1998):
   sunspot darkening = mu * (3*mu + 2)/2.0 * area , where mu = cos(latitute) × cos(longitude) is the
   cosine weighted area projection of sunspot area, and area = heliographic area of the sunspot group
   
   For reference: sunspot darkening (with empirical corrections for the additional darkness of larger sunspot than smaller sunspot = 
   mu * (3*mu + 2)/2.0 * area* (0.2231 + 0.0244 * alog10(area))

INPUTS

   area - heliographic area of the sunspot group
   lat  - heliographic latitude of sunspot group, adjusted for the Bo angle of the Sun’s axis to the ecliptic plane
   lon  - heliographic longitude of sunspot group

OUTPUTS

   ssb - the sunspot darkening  

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=compute_sunspot_blocking(area,lat,lon)

5. SOLAR_IRRADIANCE_FCDR/compute_tsi.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   compute_tsi.pro

PURPOSE

   The compute_tsi.pro procedure is a function called by the routine,process_irradiance,pro,
   to compute Total Solar Irradiance using multiple regression coefficients specific to the 
   NRLTSI2 model and given values for the sunspot darkening function and the facular brightening function.

DESCRIPTION

   The compute_tsi.pro function calculates the Total Solar Irradiance (TSI) for a specific day, given
   values for the sunspot darkening and the facular brightening function using a 2-component multiple regression formula.
 
   Variable Definitions:
   T(t) is the time-dependency (t) of TSI,
   delta_T_F(t) is the time dependency of the delta change to TSI from the facular brightening index, F(t)
   delta_T_S(t) is the time dependency of the delta change to TSI from the sunspot darkening index, S(t)
   T_Q is the TSI of the adopted Quiet Sun reference value.
   
   2-Component Regression formulas: 
   T(t) = T_Q + delta_T_F(t) + delta_T_S(t)
   Quantifying time-dependent TSI (T) Irradiance Variations from Faculae (F) and Sunspots (S):
   delta_T_F(t) = a_F + b_F * [F(t) - F_Q]
   delta_T_S(t) = a_S + b_S * [S(t) - S_Q] and a_S = 0
   F_Q and S_Q (=0) are the values of the facular brightening and sunspot darkening indices corresponding to T_Q 
   (i.e. for the quiet Sun, T_Q). 
   
   Quantifying time-dependent Uncertainties in TSI Irradiance Variation from faculae and sunspots:
   T_unc(t) = T_Q_unc + delta_T_F_unc(t) + delta_T_S_unc(t) where,
   delta_T_F_unc(t) = a_F_unc + (the uncertainty in b_F * [F(t) - F_Q]) 
   delta_T_S_unc(t) = (the uncertainty in b_S * [S(t) - S_Q]) 
   
   The uncertainty in b_F*[F(t) - F_Q]:
   [(uncertainty in b_F * [F(t) - F_Q]) / (b_F * [F(t) - F_Q])^2 = (b_F_unc / b_F)^2 + ((uncertainty in [F(t) - F_Q])/[F(t) - F_Q])^2,
   therefore, delta_T_F_unc(t) = a_F_unc + the square root of the above result multiplied by [b_F * [F(t) - F_Q]
   
   The uncertainty in b_S*[S(t) - S_Q]:
   [(uncertainty in b_S * [S(t) - S_Q]) / (b_S * [S(t) - S_Q])^2 = (b_S_unc / b_S)^2 + ((uncertainty in [S(t) - S_Q])/[S(t) - S_Q])^2,
   therefore, delta_T_S_unc(t) = the square root of the above result multiplied by [b_S * [S(t) - S_Q]
   
   Coefficients for faculae and sunspots:
   The a and b coefficients for faculae and sunspots are specified and supplied with the algorithm, as are their 
   1-sigma estimates (determined from the multiple linear regression analysis) . These coefficients best reproduce 
   the TSI irradiance variability  measured directly by SORCE TIM from 2003 to 2014. 
   Note, the a coefficient is nominally zero so that when F=F_Q and S=S_Q, then T=T_Q.
   
   Reference(s):
   Reference describing the solar irradiance variability due to linear combinations of sunspot darkening
   and facular brightening: 
      Fröhlich, C., and J. Lean, The Sun’s total irradiance: Cycles, trends
      and climate change uncertainties since 1976, Geophys. Res. Lett., 25, 4377‐4380, 1998.
   References describing the original NRLTSI and NRLSSI models are:
      Lean, J., Evolution of the Sun's Spectral Irradiance Since the Maunder Minimum, Geophys. Res. Lett., 27, 2425-2428, 2000.
      Lean, J., G. Rottman, J. Harder, and G. Kopp, SORCE Contributions to New Understanding of Global Change and Solar Variability,
      Solar. Phys., 230, 27-53, 2005.
      Lean, J. L., and T.N. Woods, Solar Total and Spectral Irradiance Measurements and Models: A Users Guide,
      in Evolving Solar Physics and the Climates of Earth and Space, Karel Schrijver and George Siscoe (Eds), Cambridge Univ. Press, 2010.
   Reference describing the extension of the model to include the extreme ultraviolet spectrum and the empirical capability to specify 
   entire solar spectral irradiance and its variability from 1 to 100,000 nm:
      Lean, J. L., T. N. Woods, F. G. Eparvier, R. R. Meier, D. J. Strickland, J. T. Correira, and J. S. Evans,
      Solar Extreme Ultraviolet Irradiance: Present, Past, and Future, J. Geophys. Res., 116, A001102, 
      doi:10.1029/2010JA015901, 2011.

INPUTS

   sb           - sunspot darkening indice
   mg           - facular brightening indice
   model_params - a structure containing model coefficients necessary to construct modeled TSI:
     tquiet     - the adopted total solar irradiance of the Quiet Sun
     acoef      - the 'a' multiple regression coefficient for facular brightening (equal to a_F, in above description)
     bfaccoef   - the 'b' multiple regression coefficient for facular brightening (equal to b_F, in above description)
     bspotcoef  - the 'b' multiple regression coefficient for sunspot darkening (equal to b_S, in above description)
     mgquiet    - the value of the facular brightening corresponding to quiet Sun (equal to F_Q, in above description)
     tsisigma   - the 1-sigma absolute uncertainty estimates for the coefficients returned in the multiple linear 
                  regression, so also accounts for autocorrelation in the time series. 
                  A 3-element array where first element contains the uncertainty in acoef (equal 
                  to a_F_unc in above description), the second element contains the uncertainty in bfaccoef (equal to 
                  b_F_unc in above description), and the third element contains the uncertainty in bspotcoef (equal to
                  b_S_unc in above description).
     mgu        - the relative uncertainty in change in facular brightening from its minimum value, mgquiet. Specified as 0.2 (20 %)
     sbu        - the relative uncertainty in change in sunspot darkening from its minimum value, '0'. Specified as 0.2 (20%)

OUTPUTS

   tsi   - a structure containing the following variables:
     totirrad    - modeled total solar irradiance
     totfac      - bolometric (spectrally integrated) contribution from facular brightening
     totspot     - bolometric (spectrally integrated) contribution from sunspot darkening
     totirradunc - uncertainty in the modeled total solar irradiance. Does not include the contribution 
                   from uncertainty in the absolute scale of the measured irradiance (+/- 0.5 Wm-2 or approx. 0.03%) 
     totfacunc   - uncertainty in the modeled total solar irradiance attributed to facular brightening contribution
     totspotunc  - uncertainty in the modeled total solar irradiance attributed to the sunspot darkening contribution     

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=compute_tsi(sb, mg, model_params)

6. SOLAR_IRRADIANCE_FCDR/create_filename.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   create_filename

PURPOSE

   The create_filename.pro function dynamically constructs a data product file name.

DESCRIPTION

   The create_filename.pro function dynamically constructs a data product file name.

INPUTS

   ymd1            - starting time range for the time range of the form 'yyyy-mm-dd'
   ymd2            - ending time range for the time range of the form 'yyyy-mm-dd'
   version         - version and revision number of the NRLTSI2 and NRLSSI2 models (e.g., v02r00)
   time_bin        - A value of 'year', 'month', or 'day' that defines the time-averaging performed for the given data records.
                     'day' is the default.
   tsi             - Keyword parameter designating file name is to be constructed for TSI data.
   ssi             - Keyword parameter designating file name is to be constructed for SSI data.

OUTPUTS

   filename        - The data product file name

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=create_filename(ymd1, ymd2, version, time_bin, tsi=tsi, ssi=ssi)

7. SOLAR_IRRADIANCE_FCDR/create_manifest.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   create_manifest

PURPOSE

   The create_manifest.pro function determines file sizes (in bytes) and the MD5 checksum value of 
   a file and passes the values to write_to_manifest.pro

DESCRIPTION

   The create_manifest.pro function determines file sizes (in bytes) and the MD5 checksum value of 
   a file and passes the values to write_to_manifest.pro

INPUTS

   output_dir - Path of directory to the input files 
   tsifile    - TSI file containing data for file size and MD5 checksum
   ssifile    - SSI file containing data for file size and MD5 checksum

OUTPUTS

   struct     - A structure containing:
     tsibytes    - File size (in bytes) of tsifile 
     ssibytes    - File size (in bytes) of ssifile 
     tsichecksum - MD5 checksum of tsifile
     ssichecksum - MD5 checksum of ssifile

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=create_manifest(output_dir=output_dir,tsifile,ssifile)

8. SOLAR_IRRADIANCE_FCDR/get_daily_time_bounds.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_daily_time_bounds

PURPOSE

   Defines the bounds for each time bin in the daily irradiance data

DESCRIPTION

   Defines the bounds for each time bin in the daily irradiance data

INPUTS

   mjd - array of Modified Julian Date for the data time bins

OUTPUTS

   bounds - The bounds (in modified Julian data) for the start of each day (inclusive), 
            and end of each day (exclusive).

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_daily_time_bounds(mjd)

9. SOLAR_IRRADIANCE_FCDR/get_mg_index.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_mg_index

PURPOSE

   The get_mg_index.pro is a function that parses a time-series of the facular brightening index for the desired starting and ending date. 

DESCRIPTION

   The get_mg_index.pro is a function that parses a time-series of the facular brightening index (actually, a proxy of the facular brightening index - Mg II) 
   for the desired starting and ending date, and passes the results to the routine, process_irradiance.pro. 
   Final data is parsed from LASP's time-series server, LaTiS, via an IDL net URL.

INPUTS

   ymd1       - starting time range respective to midnight GMT of the given day, in 'yyyy-mm-dd' format.
   ymd2       - ending time range respective to midnight GMT of the given day (i.e. in NOT inclusive), in 'yyyy-mm-dd' format.
   final      - delegate to the LaTiS server for final released data.

OUTPUTS

   data       - an IDL list containing the modified Julian date index and the Mg II index

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_mg_index(ymd1,ymd2,final=final)

10. SOLAR_IRRADIANCE_FCDR/get_model_params.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_model_params

PURPOSE

   The get_model_params.pro function is called from process_irradiance.pro.  It extracts coefficients for 
   faculae and sunspots that are pre-specified (determined using multiple linear regression) for the algorithm. The
   coefficients for reproducing TSI are spectrally integrated, while those for reproducing SSI are wavelength
   dependent. The purpose of the coefficients is to convert the facular brightening and sunspot darkening indices to their 
   equivalenet irradiance change, in energy units, depending on the wavelength-dependent strengths of the facular and sunspot influences
   at that time.

DESCRIPTION

   The get_model_params.pro function restores pre-specified coefficients from an IDL save file and passes them in a structure, 'params',
   to the main routine.

INPUTS

   file - an IDL save file containing the NRLTSI2 and NRLSSI2 model coefficients used to adjust the baseline, quiet Sun irradiance,
   either increasing or decreasing it depending on the wavelength-dependent strengths of the facular, F, and sunspot, S, 
   influences at that time.

OUTPUTS

   params - a structure containing the following variables:
     simver    = The data version of SORCE SIM used to derive model coefficients
     tquiet    = specified, invariant, quiet Sun reference value for total solar irradiance
     iquiet    = specified, invariant, quiet Sun reference value for solar spectral irradiance. Function of wavelength, k.
     lambda    = wavelength (k); consists of 1 nm bins centered at the bin midpoint from 115.5 nm to 99999.5 nm
     acoef     = the 'a' multiple regression coefficient for facular brightening 
     bfaccoef  = coefficient used to determine spectrally integrated facular brigthening adjustment to baseline, quiet Sun, tquiet. 
     bspotcoef = coefficient used to determine spectrally integrated sunspot darkening adjustment to baseline, quiet Sun, tquiet.
     ccoef     = coefficient for wavelength-dependent facular brightening 
     dfaccoef  = coefficient used to determine wavelength-dependent (k) facular brightening adjustment to baseline, quiet Sun, iquiet. 
     efaccoef  = small, but nonzero, adjustment factor that accounts for the imperfect nature of the facular brightening index. Used to ensure
                 the integral of the time and spectrally-dependent spectral irradiance variations from faculae equal the time-dependent total
                 irradiance variations from faculae.
     dspotcoef = coefficient used to determine wavelength-dependent (k) sunspot darkening adjustment to baseline, quiet Sun, iquiet.
     espotcoef = small, but nonzero, adjustment factor that accounts for the imperfect nature of the sunspot darkening index. Used to ensure
                 the integral of the time and spectrally-dependent spectral irradiance variations from sunspots equal the time-dependent total
                 irradiance variations from sunspots.
     mgquiet   = specified, invariant, reference value for the Mg II index for the quiet sun. Nonzero value. By contrast, the reference value 
                 for sunspot darkening at quiet sun conditions is zero.
     ccoefunc  = the absolute uncertainty in 'ccoef'
     mgu       = the relative uncertainty in change in facular brightening from its minimum value, mgquiet.
     sbu       = the relative uncertainty in change in sunspot darkening from its minimum value, '0'. 
     tsisigma  = the 1-sigma absolute uncertainty estimates for the coefficients returned in the multiple linear
                  regression, so also accounts for autocorrelation in the time series.
     faccfunc  = the relative uncertainty estimate for the coefficients of spectral facular brightening obtained from multiple linear
                  regression of the detrended spectral observations, and detrended indices.
     spotcfunc = the relative uncertainty estimate for the coefficients of spectral sunspot darkening obtained from multiple linear
                  regression of the detrended spectral observations, and detrended indices.
     coeff0spot = the regression coefficient that linearly relates the sunspot darkening index to the residual energy in the sunspot darkening
                  index
     qsigmaspot = the absolute uncertainty in the small, but nonzero 'coeff0spot' factor  
     coeff0fac = the regression coefficient that linearly relates the facular brightening index to the residual energy in the facular 
                  brightening index
     qsigmafac = the absolute uncertainty in the 'coeff0fac' factor
     selmg     = internal QA flag (not used to compute model irradiances)
     selfrac   = internal QA flag (not used to compute model irradiances)
     seltim    = internal QA flag (not used to compute model irradiances)

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_model_params(file=file)

11. SOLAR_IRRADIANCE_FCDR/get_monthly_time_bounds.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_monthly_time_bounds

PURPOSE

   Defines the bounds for each time bin in the monthly-averaged irradiance data

DESCRIPTION

   Defines the bounds for each time bin in the monthly-averaged irradiance data

INPUTS

   mjd - array of Modified Julian Date for the data time bins at the middle of the month (15th)

OUTPUTS

   bounds - The bounds (in modified Julian data) for the 1st of each month (inclusive),
            and end of each month (exclusive).

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_monthly_time_bounds(mjd)

12. SOLAR_IRRADIANCE_FCDR/get_solar_latitude.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_solar_latitude.pro

PURPOSE

   Obtains solar latitude from a generic file (betasun2.dat)

DESCRIPTION

   Obtains the ecliptic plane correction, B0, for the given day. The B0 factor is used to correct the
   heliocentric latitude of the sunspot grouping, 'lat' for an approximate +/- 7 degree annual 
   change in the ecliptic plane (the angle between the perpendicular of the line from the 
   earth center to the center of the Sun) and the angle of rotation of the Sun. The B0 correction is an 
   area projection (cosine weighting). 
   The corrected solar latitude = latitude - B0

INPUTS

   jd - Julian Date 

OUTPUTS

   lat - the ecliptic plane correction  

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_solar_latitude(jd)

13. SOLAR_IRRADIANCE_FCDR/get_spectral_bins.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_spectral_bins.pro

PURPOSE

   The get_spectral_bins.pro function is called from the routine, process_irradiance.pro.  It sets up wavelength bands for 
   the output solar spectral irradiance.  The wavelength grid is as follows:
   1 nm from 115 to 750
   5 nm from 750 to 5000
   10 nm from 5000 to 10000
   50 nm from 10000 to 100000
   The routine defines the bandcenters and bandwidths for the wavelength grid, and passes the variables back to the driver routine
   in a structure, 'bins'.

DESCRIPTION

   The get_spectral_bins.pro function passes wavelength grid information (number of bands, bandcenters, and bandwidths) to the 
   driver routine for later use in binning spectral irradiance data.

INPUTS

OUTPUTS

   bins - a structure containing the following variables:
     nband      = number of spectral bands, for a variable wavelength grid, that the NRLSSI2 model bins 1 nm solar spectral irradiance onto.
     bandcenter = the bandcenters (nm) of the variable wavelength grid.
     bandwidth  = the bandwidths (delta wavelength, nm)  of the variable wavelength grid, centered on bandcenter. 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_spectral_bins()

14. SOLAR_IRRADIANCE_FCDR/get_sunspot_blocking.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_sunspot_blocking.pro

PURPOSE

   The get_sunspot_blocking.pro is a utility function that iteratively invokes the function process_sunspot_blocking for a time period
   defined by a starting and ending date.

DESCRIPTION

   The get_sunspot_blocking function is a utility function that iteratively invokes a second function, process_sunspot_blocking, 
   which computes the sunspot darkening index for a time period defined by a starting and ending date. Keyword parameters define
   whether the sunspot darkening index is obtained from files identified as "final", or preliminary data ("dev") 

INPUTS

   ymd1                - starting time range respective to midnight GMT of the given day, in 'yyyy-mm-dd' format
   ymd2                - ending time range respective to midnight GMT of the given day (i.e. in NOT inclusive), in 'yyyy-mm-dd' format.
   final               - delegate to the LaTiS server for final released data.
   dev                 - delegate to processing routine for preliminary data.          

OUTPUTS

   data                - an IDL list containing modified Julian date and sunspot darkening index

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_sunspot_blocking(ymd1,ymd2,final=final,dev=dev)

15. SOLAR_IRRADIANCE_FCDR/get_yearly_time_bounds.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_yearly_time_bounds

PURPOSE

   Defines the bounds for each time bin in the yearly-averaged irradiance data

DESCRIPTION

   Defines the bounds for each time bin in the yearly-averaged irradiance data

INPUTS

   mjd - array of Modified Julian Date for the data time bins at the middle of the year (July 1)

OUTPUTS

   bounds - The bounds (in modified Julian data) for the 1st of each year (inclusive),
            and end of each year (exclusive).

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_yearly_time_bounds(mjd)

16. SOLAR_IRRADIANCE_FCDR/group_by_day.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   group_by_day.pro

PURPOSE

   Bins USAF white light sunspot data by day. 

DESCRIPTION

   This routine is called from process_sunspot_blocking.pro. Using a structure containing USAF white light sunspot region data 
   (from get_sunspot_data.pro), it returns a Hash where the key is the modified julian day number and the value is a list of sunspot records 
   for that modified julian day number

INPUTS

   structures - A structure containing (for each record in the USAF data):
     mjd - Modified Julian Date 
     lat - latitude of sunspot group
     lon - longitude of sunspot group
     group   - sunspot group number 
     area - recorded sunspot area
     station - station name 

OUTPUTS

   result - an IDL Hash (compound data type of key-value pair) where the key is the Julian Day Number 
            and the value is a List of records for that day.  

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=group_by_day(structures)

17. SOLAR_IRRADIANCE_FCDR/group_by_function.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   group_by_function

PURPOSE

   When given the name of a function that takes a structure as an argument, uses its return value as the key.

DESCRIPTION

   When given the name of a function that takes a structure as an argument, uses its return value as the key.

INPUTS

   structures - A structure or list of structures 
   hash_function - Name of the hash function

OUTPUTS

   result - an IDL Hash containing the key components of the structure 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=group_by_function(structures, hash_function)

18. SOLAR_IRRADIANCE_FCDR/group_by_tag.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   group_by_tag.pro

PURPOSE

   Given an array of structures and the name (a tag) in those structures,
   creates a Hash where each value of that tag becomes a key and the value
   for each key is an array of the structures that has that value of that tag.
   Does not modify the original structures.

DESCRIPTION

   Called by process_sunspot_blocking.pro
   Makes a Hash mapping for a tag that becomes a key and the value for each key is an array of structures
   that has the value of that tag.  For example, USAF station name can be used as a key and the value for that key is an array of 
   structures holding observations by that station. 

INPUTS

   structures - A structure containing, for each day of records in the USAF data:
     mjd - Modified Julian Date 
     lat - latitude of sunspot group
     lon - longitude of sunspot group
     group   - sunspot group number 
     area - recorded sunspot area
     station - station name 
   tag - an array of USAF station names  

OUTPUTS

   result - an IDL Hash (compound data type of key-value pair) where the key is the USAF station name and 
            the value is a List of sunspot records for that station (for a particular day).  

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=group_by_tag(structures, tag)

19. SOLAR_IRRADIANCE_FCDR/iso_date2mjdn.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   iso_date2mjdn

PURPOSE

   Converts time from ISO 8601 standard to Modified Julian Date 

DESCRIPTION

   Converts time from ISO 8601 standard to Modified Julian Date. 
   Uses the ITT/IDL library routine julday.pro, which calculates the julian day 
   number for a given month, day, and year. 

INPUTS

   ymd - a value for time in ISO format ('yyyy-mm-dd')

OUTPUTS

   mjd - Modified Julian Date 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=iso_date2mjdn(ymd)

20. SOLAR_IRRADIANCE_FCDR/jd2iso_date.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   jd2iso_date

PURPOSE

   Converts time from Julian Date (integer) to ISO 8601 standard, 'yyyy-mm-dd' 

DESCRIPTION

   Converts time from Julian Date (integer) to ISO 8601 standard, 'yyyy-mm-dd'. 
   Uses ITT IDL library routine caldat.pro, which return the calendar date given julian date.  

INPUTS

   jd - Julian Date

OUTPUTS

   a value for time in ISO format ('yyyy-mm-dd')

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=jd2iso_date(jd)

21. SOLAR_IRRADIANCE_FCDR/jd2mmdd.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   jd2mmdd

PURPOSE

   Converts time from Julian Date to a month and day string (mmdd). 

DESCRIPTION

   Converts time from Julian Date to a month and day string (mmdd). 

INPUTS

   jd - time value in Julian Date

OUTPUTS

   mmdd - a month and day string

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=jd2mmdd(jd)

22. SOLAR_IRRADIANCE_FCDR/mjd2iso_date.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   mjd2iso_date

PURPOSE

   Converts time from Modified Julian Date (integer) to ISO 8601 time standard, 'yyyy-mm-dd' 

DESCRIPTION

   Converts time from Modified Julian Date (integer) to ISO 8601 time standard, 'yyyy-mm-dd' 
   Uses the ITT/IDL library routine caldat.pro, which returns the calendar date given julian day 

INPUTS

   mjd - Modified Julian Date

OUTPUTS

   a value for time in ISO format ('yyyy-mm-dd')

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=mjd2iso_date(mjd)

23. SOLAR_IRRADIANCE_FCDR/mjd2iso_yyyy.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   mjd2iso_yyyy

PURPOSE

   Converts time from Modified Julian Date (integer) to a 4 digit year in ISO 8601 standard, 'yyyy' 

DESCRIPTION

   Converts time from Modified Julian Date (integer) to 4 digit year ISO 8601 standard, 'yyyy' 

INPUTS

   mjd - Modified Julian Date

OUTPUTS

   a value for year in ISO format ('yyyy')

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=mjd2iso_yyyy(mjd)

24. SOLAR_IRRADIANCE_FCDR/mjd2iso_yyyymm.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   mjd2iso_yyyymm

PURPOSE

   Converts time from Modified Julian Date (integer) to a 4 digit year and 2 digit month in ISO 8601 standard, 'yyyy-mm' 

DESCRIPTION

   Converts time from Modified Julian Date (integer) to a 4 digit year and 2 digit month in ISO 8601 standard, 'yyyy-mm-dd' 

INPUTS

   mjd - Modified Julian Date

OUTPUTS

   a value for year and month in ISO format ('yyyy-mm')

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   09/08/2014 Initial Version prepared for NCDC

USAGE

   result=mjd2iso_yyyymm(mjd)

25. SOLAR_IRRADIANCE_FCDR/nrl2_to_irradiance.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   nrl2_to_irradiance

PURPOSE

   The nrl2_to_irradiance.pro is the main driver procedure.  It calls subfunctions to compute Total Solar Irradiance (TSI) and 
   Solar Spectral Irradiance (SSI) to write the data output to NetCDF4 formatted files.

DESCRIPTION

   The nrl2_to_irradiance.pro is the main driver procedure.  It calls subfunctions to compute Total Solar Irradiance (TSI) and 
   Solar Spectral Irradiance (SSI) to write the data output to NetCDF4 formatted files.

INPUTS

   ymd1       - starting time range respective to midnight GMT of the given day, of the form 'yyyy-mm-dd'
   ymd2       - ending time range respective to midnight GMT of the given day (i.e. in NOT inclusive), of the form 'yyyy-mm-dd'.
   final      - Data processing is delegated to the LaTiS server for accessing final released values of model inputs.
   time_bin   - A value of 'year', 'month', or 'day' that defines the time-averaging performed for the given data records.
               'day' is the default.
   version    - version and revision number of the NRLTSI2 and NRLSSI2 models (e.g., v02r00)            
   output_dir - path to data output directory. 

OUTPUTS

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   nrl2_to_irradiance, ymd1, ymd2, final=final, time_bin=time_bin, version=version, output_dir=output_dir

26. SOLAR_IRRADIANCE_FCDR/process_irradiance.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   process_irradiance

PURPOSE

   The process_irradiance.pro procedure calls a series of functions to compute the Total Solar Irradiance (TSI) and 
   Solar Spectral Irradiance (SSI) using the NRLTSI2 and NRLSSI2 models.

DESCRIPTION

   The process_irradiance.pro procedure calls a series of functions to compute the Total Solar Irradiance (TSI) and 
   Solar Spectral Irradiance (SSI) using the NRLTSI2 and NRLSSI2 models.

INPUTS

   ymd1       - starting time range respective to midnight GMT of the given day, of the form 'yyyy-mm-dd'
   ymd2       - ending time range respective to midnight GMT of the given day (i.e. in NOT inclusive), of the form 'yyyy-mm-dd'.
   final      - Data processing is delegated to the LaTiS server for accessing final released values of model inputs.
   dev        - Data processing is delegated to processing routines for computing preliminary model input data. 
   time_bin   - A value of 'year', 'month', or 'day' that defines the time-averaging performed for the given data records.
               'day' is the default.

OUTPUTS

   data       - A structure containing the irradiance data and the spectral bins:
     mjd        - Modified Julian Date
     iso        - iso 8601 formatted time
     tsi        - Modeled Total Solar Irradiance
     ssi        - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot     - Integral of the Modeled Solar Spectral Irradiance
     nband      - number of spectral bands, for a variable wavelength grid, that the NRLSSI2 model bins 1 nm solar spectral irradiance onto.
     bandcenter - the bandcenters (nm) of the variable wavelength grid.
     bandwidth  - the bandwidths (delta wavelength, nm)  of the variable wavelength grid, centered on bandcenter.

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=process_irradiance(ymd1, ymd2, final=final, dev=dev, time_bin=time_bin)

27. SOLAR_IRRADIANCE_FCDR/process_sunspot_blocking.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   process_sunspot_blocking.pro

PURPOSE

   The process_sunspot_blocking.pro procedure computes the sunspot blocking function from U.S. Air Force
   White Light sunspot region data (obtained from a NOAA/NGDC web repository via ftp access- point of contact: Bill Denig).

DESCRIPTION

   This routine computes the sunspot darkening index, which is passed by structure, 'sunspot_blocking_data', to the calling 
   function, 'get_sunspot_blocking' for preliminary data. 
   This routine calls a series of subroutines with the names and purposes, summarized below:
   get_sunspot_data.pro - aquire USAF white light sunspot region data from NOAA/NGDC web repository and store
                          in a structure, 'sunspot_data', identified by index -> (jd, lat, lon, area, station)
                          An optional keyword, 'stations', is used to restrict data to a user-defined particular station(s).
                          By default, all stations are used in computing the sunspot darkening index.
   group_by_day.pro     - group the USAF white light data by Julian date: jdn -> (jd, lat, lon, area, station)
                          Stored in structure, 'daily_sunspot_data'
   get_solar_latitutude.pro - Obtains the ecliptic plane correction, B0, for the given day. The B0 factor is used to correct the
                              heliocentric latitude of the sunspot grouping, 'lat' for an approximate +/- 7 degree annual 
                              change in the ecliptic plane (the angle between the perpendicular of the line from the 
                              earth center to the center of the Sun) and the angle of rotation of the Sun. The B0 correction is an 
                              area projection (cosine weighting). The corrected solar latitude = latitude - B0
   compute_sunspot_blocking.pro -  The delta change (reduction) in irradiance computed from the latitude/longitude and
                                   sunspot area computed from the individual measurements of sunspot area for daily recorded
                                   sunspot grouping(s) of a particular station.
   group_and_sum.pro - The total delta change in irradiance due to sunspots is the sum of the sunspot blocking over each measuring station. 
                       If a station is missing data for a particular sunspot grouping, a quality flag to indicate missing data is set.                                                      
   write_sunspot_blocking_data.pro - If optional 'output_dir' keyword is defined, the sunspot darkening index, and its standard deviation 
                                     of the is output to intermediate ascii file 
                                     ('sunspot_blocking_YMD1_YMD2_VER.txt'), where time ranges specify start/end date of desired time range.
                                     'VER' is a hardcoded development version value to help keep track of data output. Intermediate file
                                     output used for QA analysis.
                                     
   Note**: Input time periods of YYYY-MM-DD format are internally converted to Modified Julian Date for these routines.

INPUTS

   ymd1       - starting time range respective to midnight GMT of the given day, in Modified Julian day (converted from 'yyyy-mm-dd' in main driver).
   ymd2       - ending time range respective to midnight GMT of the given day  
   stations = stations - Optional keyword to restrict sunspot darkening index to specified monitoring stations in the USAF white light network.
                         If omitted (default), these stations are used: 'LEAR','CULG','SVTO','RAMY','BOUL','HOLL','PALE','MANI','ATHN'. 
                         Used for QA analysis.
   output_dir=output_dir - Optional keyword to specify directory path to store sunspot darkening index in a text file. If omitted (default), output
                           is not written to intermediate file. Used for QA analysis.  

OUTPUTS

   sunspot_blocking_data - a structure containing the following variables:
     mjdn - the modified julian date 
     ssbt - the sunspot darkening index (a mean value of the reporting stations)
     dssbut - the standard deviation of the sunspot darkening index of the reporting stations
     quality flag - a value of 0 or 1 (1 = missing data or duplicate data); Used for QA analysis.

   if optional keyword 'output_dir' is defined, an intermediate text file of the naming convention, 'sunspot_blocking_YMD1_YMD2_VER.txt',
   contains the structure data listed above, where version is a defined developmental version - Used for QA monitoring. 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=process_sunspot_blocking(ymd1,ymd2,stations=stations,output_dir=output_dir)

28. SOLAR_IRRADIANCE_FCDR/read_latis_data.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   read_latis_data

PURPOSE

   The read_latis_data.pro is a function that gets data from the LASP Time Series Server as a list of structures

DESCRIPTION

   The read_latis_data.pro is a function that gets data from the LASP Time Series Server as a list of structures
   Data is parsed from LASP's time-series server, LaTiS, via an IDL net URL.

INPUTS

   dataset    - The name of the dataset
   start_time - starting time range to aquire the data, in 'yyyy-mm-dd' format.
   end_time   - ending time range to aquire the data, in 'yyyy-mm-dd' format.
   host       - name of the server host
   port       - the port on the server machine
   base_path  - Directory path on server to the dataset
   query      - query parameters used to convert time or rename parameters to match the structures in LaTiS.

OUTPUTS

   list       - an IDL list containing the dataset values

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=read_latis_data(dataset, start_time, end_time, host=host, port=port, base_path=base_path, query=query)

29. SOLAR_IRRADIANCE_FCDR/remove_duplicate_records.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   remove_duplicate_records.pro

PURPOSE

   Checks for duplicate sunspot station records in the USAF white light observations. Removes duplicate records if found.

DESCRIPTION

   Called by process_sunspot_blocking.pro
   If duplicate records are found, reports the number of duplicates

INPUTS

   ssdata_by_station - An IDL hash observations by that station:
     mjd - Modified Julian Date 
     lat - latitude of sunspot group
     lon - longitude of sunspot group
     group   - sunspot group number 
     area - recorded sunspot area
     station - station name 

OUTPUTS

   result - an IDL hash (an IDL Hash (compound data type of key-value pair) where the key is the Julian Day Number
            and the value is a List of records with duplicate records removed 
   ndup   - an integer value of the number of duplicate records found (default = 0)

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=remove_duplicate_records(ssdata_by_station, ndup)

30. SOLAR_IRRADIANCE_FCDR/remove_hyphens.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   remove_hypens

PURPOSE

   Removes hyphens from the ISO 8601 date standard 'YYYY-MM-DD' to create 'YYYYMMDD' format

DESCRIPTION

   Removes hyphens in the ISO 8601 time standard. 
   Used for formatting ISO 8601 time for dynamic filename creation. 

INPUTS

   string - a value for time in ISO format ('yyyy-mm-dd')

OUTPUTS

   result - ISO format without hyphens

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=remove_hyphens(string)

31. SOLAR_IRRADIANCE_FCDR/unix2mjd.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   unix2mjd

PURPOSE

   Converts time from UNIX standard (with epoch 1970-01-01T00:00:00Z) to Modified Julian Date

DESCRIPTION

   Converts time from UNIX standard (with epoch 1970-01-01T00:00:00Z) to Modified Julian Date

INPUTS

   unix_time - a value for time in UNIX format (with epoch 1970-01-01T00:00:00Z)

OUTPUTS

   mjd - Modified Julian Date

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=unix2mjd(unix_time)

32. SOLAR_IRRADIANCE_FCDR/write_irradiance_data.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_irradiance_data

PURPOSE

   The write_irradiance_data.pro function is the driver routine for writing irradiance output to netCDF4 output

DESCRIPTION

   The write_irradiance_data.pro function is the driver routine for writing irradiance output to netCDF4 output

INPUTS

   ymd1            - starting time range respective to midnight GMT of the given day, of the form 'yyyy-mm-dd'
   ymd2            - ending time range respective to midnight GMT of the given day (i.e. in NOT inclusive), of the form 'yyyy-mm-dd'.
   irradiance_data - a structure containing the following variables
     mjd        - Modified Julian Date  
     iso        - iso 8601 formatted time
     tsi        - Modeled Total Solar Irradiance
     ssi        - Modeled Solar Spectral Irradiance (in wavelength bins) 
     ssitot     - Integral of the Modeled Solar Spectral Irradiance 
     nband      - number of spectral bands, for a variable wavelength grid, that the NRLSSI2 model bins 1 nm solar spectral irradiance onto.
     bandcenter - the bandcenters (nm) of the variable wavelength grid.
     bandwidth  - the bandwidths (delta wavelength, nm)  of the variable wavelength grid, centered on bandcenter.
   version         - version and revision number of the NRLTSI2 and NRLSSI2 models (e.g., v02r00)
   time_bin        - A value of 'year', 'month', or 'day' that defines the time-averaging performed for the given data records.
                     'day' is the default.
   output_dir - Directory path for irradiance files

OUTPUTS

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_irradiance_data(ymd1,ymd2,irradiance_data, version, time_bin=time_bin, output_dir=output_dir)

33. SOLAR_IRRADIANCE_FCDR/write_monthly_average_ssi_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_monthly_average_ssi_to_netcdf2.pro

PURPOSE

   The write_monthly_average_ssi_to_netcdf2.pro function outputs monthly-averaged Solar Spectral Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_monthly_average_ssi_to_netcdf2.pro function outputs monthly-averaged Solar Spectral Irradiance
   to a netcdf4 file and (midpoint) date (YYYY-MM) to a netcdf4 formatted file. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   Missing values (NaN's or '0's) are defined as -99.0. 

INPUTS

   ymd1  - starting time  (yyyy-mm-dd)
   ymd2  - ending time  (yyyy-mm-dd)
   ymd3  - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLSSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     tsiunc - Uncertainty in total solar irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot - Integral of the Modeled Solar Spectral Irradiance
   spectral_bins - a structure containing the following variables
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid.
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro)

OUTPUTS

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_monthly_average_ssi_to_netcdf2(ymd1, ymd2, ymd3, version, irradiance_data, output_dir=output_dir, file)

34. SOLAR_IRRADIANCE_FCDR/write_monthly_average_tsi_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_monthly_average_tsi_to_netcdf2.pro

PURPOSE

   The write_monthly_average_tsi_to_netcdf2.pro function outputs monthly-averaged Total Solar Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_monthly_average_tsi_to_netcdf2.pro function outputs monthly-averaged Total Solar Irradiance
   to a netcdf4 file and (midpoint) date (YYYY-MM) to a netcdf4 formatted file. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   Missing values (NaN's or '0's) are defined as -99.0. 

INPUTS

   ymd1  - starting time  (yyyy-mm-dd)
   ymd2  - ending time  (yyyy-mm-dd)
   ymd3  - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLTSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     tsiunc - Uncertainty in total solar irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot - Integral of the Modeled Solar Spectral Irradiance
   spectral_bins - a structure containing the following variables
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid.
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro)

OUTPUTS

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_monthly_average_tsi_to_netcdf2(ymd1, ymd2, ymd3, version, irradiance_data, output_dir=output_dir, file)

35. SOLAR_IRRADIANCE_FCDR/write_ssi_model_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_ssi_model_to_netcdf2.pro

PURPOSE

   The write_ssi_model_to_netcdf2.pro function outputs daily Solar Spectral Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_ssi_model_to_netcdf2.pro function writes the daily Solar Spectral Irradiance and wavelength information 
   (midpoints and band width) to a netcdf4 formatted file. Also included is the value of total (spectrally)
   integrated Total Solar Irradiance for the particular date. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   CF-1.6 metadata conventions are used in defining global and variable name attributes. 
   Missing values are defined as -99.0. 

INPUTS

   ymd1  - starting time  (yyyy-mm-dd)
   ymd2  - ending time  (yyyy-mm-dd)
   ymd3  - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLSSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     tsiunc - Uncertainty in total solar irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot - Integral of the Modeled Solar Spectral Irradiance
   spectral_bins - a structure containing the following variables
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid.    
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro)

OUTPUTS

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_ssi_model_to_netcdf2(ymd1,ymd2,ymd3,version, irradiance_data,output_dir=output_dir, file)

36. SOLAR_IRRADIANCE_FCDR/write_sunspot_blocking.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_sunspot_blocking.pro

PURPOSE

   The write_sunspot_blocking.pro procedure outputs time (in iso yyyy-mm-dd format), sunspot darkening index, 
   the standard deviation of the sunspot darkening index, and a quality flag to an output text file.
   It is an optional routine utilized if the keyword paramater, output_dir, is defined in process_sunspot_blocking.pro

DESCRIPTION

   This routine is executed only if an optional keyword input, 'output_dir', is set in process_sunspot_blocking.pro.
   The write_sunspot_blocking.pro procedure outputs time, sunspot darkening index, the standard deviation of the sunspot darkening index,
   and a quality flag to an output text file.  This intermediate file is used in QA analysis.                                                    
   The file- naming convention of the output follows 'sunspot_blocking_YMD1_YMD2_VER.txt', where time ranges specify start/end date 
   of the time range over which the sunspot darkening is computed, and 'VER' is a hardcoded development version value to help keep track of 
   data output (i.e. 'VER' may differ from version of the NRL2 model).

INPUTS

   sunspot_blocking_data - a structure containing the following variables:
     mjdn - the modified julian date 
     ssbt - the sunspot darkening index (a mean value of the reporting stations)
     dssbut - the standard deviation of the sunspot darkening index of the reporting stations
     quality flag - a value of 0 or 1 (1 = missing data); Used for QA analysis.
   file - defined file name of the convention, 'sunspot_blocking_YMD1_YMD2_VER.txt', where 
   version is a defined developmental version - Used for QA monitoring. 

OUTPUTS

   file - a text file of the data in the sunspot_blocking_data structure, of the convention, 
   'sunspot_blocking_YMD1_YMD2_VER.txt', where version is a defined developmental version - Used for QA monitoring. 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_sunspot_blocking(sunspot_blocking_data,file)

37. SOLAR_IRRADIANCE_FCDR/write_to_manifest.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_to_manifest.pro

PURPOSE

   The write_to_manifest.pro function outputs filename, MD5 checksum, and 
   file size (in bytes) to a manifest (.mnf) file.

DESCRIPTION

   The write_to_manifest.pro function writes the filename, MD5 checksum, and 
   file size (in bytes) to a manifest (.mnf) file.

INPUTS

   output_dir - Directory path for manifest file
   filename   - name of data file, for which file size and checksum are reported
   filesize   - filesize (in bytes)
   checksum   - MD5 checksum for filename
   fileout    - output filename for the manifest file

OUTPUTS

   fileout    - Output manifest file, containing filename, file size, and checksum in a comma separated list

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_to_manifest(output_dir=output_dir, filename, filesize, checksum, fileout)

38. SOLAR_IRRADIANCE_FCDR/write_tsi_model_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_tsi_model_to_netcdf2.pro

PURPOSE

   The write_tsi_model_to_netcdf2.pro function outputs daily Total Solar Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_tsi_model_to_netcdf.pro function writes the daily Total Solar Irradiance to a netcdf4 formatted file. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   CF-1.6 metadata conventions are used in defining global and variable name attributes. 
   Missing values are defined as -99.0. 

INPUTS

   ymd1            - starting time  (yyyy-mm-dd)
   ymd2            - ending time  (yyyy-mm-dd)
   ymd3            - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLTSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date  
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins) 
     ssitot - Integral of the Modeled Solar Spectral Irradiance 
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro) 

OUTPUTS

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_tsi_model_to_netcdf2(ymd1, ymd2, ymd3, version, irradiance_data,output_dir=output_dir, file)

39. SOLAR_IRRADIANCE_FCDR/write_yearly_average_ssi_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_yearly_average_ssi_to_netcdf2.pro

PURPOSE

   The write_yearly_average_ssi_to_netcdf2.pro function outputs yearly-averaged Solar Spectral Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_yearly_average_ssi_to_netcdf2.pro function outputs yearly-averaged Solar Spectral Irradiance
   to a netcdf4 file and (midpoint) date (YYYY) to a netcdf4 formatted file. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   Missing values (NaN's or '0's) are defined as -99.0. 

INPUTS

   ymd1  - starting time  (yyyy-mm-dd)
   ymd2  - ending time  (yyyy-mm-dd)
   ymd3  - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLSSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     tsiunc - Uncertainty in total solar irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot - Integral of the Modeled Solar Spectral Irradiance
   spectral_bins - a structure containing the following variables
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid.
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro)

OUTPUTS

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=write_yearly_average_ssi_to_netcdf2(ymd1, ymd2, ymd3, version, irradiance_data, output_dir=output_dir, file)

40. SOLAR_IRRADIANCE_FCDR/write_yearly_average_tsi_to_netcdf2.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   write_yearly_average_tsi_to_netcdf2.pro

PURPOSE

   The write_yearly_average_tsi_to_netcdf2.pro function outputs yearly-averaged Total Solar Irradiance
   to a netcdf4 file. This function is called from the routine, write_irradiance_data.pro.

DESCRIPTION

   The write_yearly_average_tsi_to_netcdf2.pro function outputs yearly-averaged Total Solar Irradiance
   to a netcdf4 file and (midpoint) date (YYYY-MM) to a netcdf4 formatted file. 
   The time format variables is seconds since a 1610-01-01 00:00:00 epoch
   Missing values (NaN's or '0's) are defined as -99.0. 

INPUTS

   ymd1  - starting time  (yyyy-mm-dd)
   ymd2  - ending time  (yyyy-mm-dd)
   ymd3  - creation date (yyyy-mm-dd)
   version         - version and revision number of the NRLTSI2 model (e.g., v02r00)
   irradiance_data - a structure containing the following variables
     mjd    - Modified Julian Date
     iso    - iso 8601 formatted time
     tsi    - Modeled Total Solar Irradiance
     tsiunc - Uncertainty in total solar irradiance
     ssi    - Modeled Solar Spectral Irradiance (in wavelength bins)
     ssitot - Integral of the Modeled Solar Spectral Irradiance
   spectral_bins - a structure containing the following variables
     nband       - number of spectral bands, for a variable wavelength grid, that the NRL2 model bins 1 nm solar spectral irradiance onto.
     bandcenter  - the bandcenters (nm) of the variable wavelength grid.
     bandwidth   - the bandwidths (delta wavelength, nm)  of the variable wavelength grid.
   output_dir - Directory path for output file
   file       - filename (dynamically created from write_irradiance_data.pro)

OUTPUTS

AUTHOR

   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC
   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   11/10/2014 Initial Version prepared for NCDC

USAGE

   result=write_yearly_average_tsi_to_netcdf2(ymd1, ymd2, ymd3, version, irradiance_data, output_dir=output_dir, file)

41. SOLAR_IRRADIANCE_FCDR/yymmdd2mjd.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   yymmdd2mjd

PURPOSE

   Converts time from ISO 8601 standard to a Modified Julian Day (integer).

DESCRIPTION

   Converts time from ISO 8601 standard to a Modified Julian Day (integer).

INPUTS

   yymmdd - time value in ISO standard

OUTPUTS

   mjd - Modified Julian Date (integer)

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   yymmdd2mjd,yymmdd

42. TSI_FCDR/get_sunspot_data.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   get_sunspot_data.pro

PURPOSE

   Aquire U.S. Air Force white Light sunspot region data from a NOAA/NGDC web repository- point of contact: Bill Denig.
   http://www.ngdc.noaa.gov/stp/space-weather/solar-data/solar-features/sunspot-regions/usaf_mwl/

DESCRIPTION

   This routine is called from the function, process_sunspot_blocking.pro for the case of preliminary data.
   It accesses the above url and parses the given record into a data structure. Each record is for a sunspot group 
   measurement. The time (YYMMDD), solar latitude and longitude, sunspot area, and station ID are parsed from each record.

INPUTS

   ymd1       - starting time range respective to midnight GMT of the given day, in Modified Julian day (converted from 'yyyy-mm-dd' in main driver).
   ymd2       - ending time range respective to midnight GMT of the given day  
   stations = stations - Optional keyword to restrict sunspot darkening index to specified monitoring stations in the USAF white light network.
                         If omitted (default), these stations are used: 'LEAR','CULG','SVTO','RAMY','BOUL','HOLL','PALE','MANI','ATHN'. 
                         Used for QA analysis.

OUTPUTS

   'data' - a structure containing (for each record in the USAF data) is returned to process_sunspot_blocking
     mjd      - Modified Julian Date 
     lat     - latitude of sunspot group
     lon     - longitude of sunspot group
     group   - sunspot group number 
     area    - sunspot area
     station - station name 

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   result=get_sunspot_data(ymd1, ymd2, stations=stations)

43. TSI_FCDR/replace_nan_with_value.pro [ Programs ]

[ Top ] [ Programs ]

NAME

   replace_nan_with_value.pro

PURPOSE

   The replace_nan_with_value.pro function returns a float array containing the given data with 
   NaN replaced with user designated missing value.

DESCRIPTION

   The replace_nan_with_value.pro function returns a float array containing the given data with 
   NaN replaced with user designated missing value. 
   A copy of the input data as floats is made so the 'data' remains immutable.

INPUTS

   data - input data a copy of the data as floats:
   value - the value designated to replace NaN as "missing" values

OUTPUTS

   result - a copy of the input data, with NaNs replaced by missing values

AUTHOR

   Odele Coddington, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Doug Lindholm, Laboratory for Atmospheric and Space Physics, Boulder, CO
   Judith Lean, Space Science Division, Naval Research Laboratory, Washington, DC

COPYRIGHT

   THIS SOFTWARE AND ITS DOCUMENTATION ARE CONSIDERED TO BE IN THE PUBLIC
   DOMAIN AND THUS ARE AVAILABLE FOR UNRESTRICTED PUBLIC USE. THEY ARE
   FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS
   INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY,
   EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND
   DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR
   THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL
   SUPPORT TO USERS.

REVISION HISTORY

   06/04/2015 Initial Version prepared for NCDC

USAGE

   replace_nan_with_missing, data, value