Difference between revisions of "Software utilities"

From Planck PLA 2015 Wiki
Jump to: navigation, search
(LFI_fastcc formatting/additions)
(Blanked the page)
Line 1: Line 1:
==Unpack and Display==
 
  
There is no "unpack and display" software for PLA1.
 
 
==Unit Conversion and Colour Correction==
 
The unit conversion and colour correction software (UC_CC) consists of a set of IDL procedures and functions that read the band transmission from the DPC RIMOs and perform the requested conversions.  The package is delivered as a tarfile and contains a detailed instruction manual.  The data and software file requirements are provided below along with basic use instructions and some simple examples.  The full list of its contents is:
 
 
UC_CC_v102/get_hfibolo_list.pro
 
UC_CC_v102/hfi_co_correction.pro
 
UC_CC_v102/hfi_colour_correction.pro
 
UC_CC_v102/hfi_lfi_test_script.pro
 
UC_CC_v102/hfi_lfi_test_script_PLA_RIMO.pro
 
UC_CC_v102/hfi_read_avg_bandpass.pro
 
UC_CC_v102/hfi_read_bandpass.pro
 
UC_CC_v102/hfi_unit_conversion.pro
 
UC_CC_v102/lfi_read_avg_bandpass.pro
 
UC_CC_v102/lfi_read_bandpass.pro
 
UC_CC_v102/LFI_fastcc.pro
 
UC_CC_v102/LFI_fastcc_test.pro
 
UC_CC_v102/README.txt
 
UC_CC_v102/Instructions.pdf
 
 
The package is currently available on [[http://externaltools.planck.fr]]
 
 
=== Relevant Documentation ===
 
 
Please refer to the Spectral Response sections of the Explanatory Supplement (i.e. 2.2.1.2, 4.4.5, and 4.6), as well as the Spectral Response Paper <cite>#planck2013-p03d</cite> for details of the derivation of the detector spectra and band-average spectra included in the RIMO files, as well as additional details on the unit conversion and colour correction methodology, philosophy, and implementation.  This section concentrates on the use of the provided UC_CC software itself, leaving the other sections to provide the basis for it. 
 
 
=== Tarfile Distribution Package ===
 
 
This section provides a brief explanation of each file included in the UC_CC distribution.
 
 
# <tt>get_hfibolo_list.pro</tt>: used to provide basic detector information (i.e. names) within subsequent routines.
 
# <tt>hfi_read_bandpass.pro</tt>: a routine to get the desired detector level spectral transmission data (HFI) and output in a structure format used by the other routines.
 
# <tt>hfi_read_avg_bandpass.pro</tt>: a routine to get the desired HFI band-average spectral transmission data and output in a structure format used by the other routines.
 
# <tt>hfi_unit_conversion.pro</tt>: a routine that accepts spectral response information and outputs unit conversion coefficients.
 
# <tt>hfi_colour_correction.pro</tt>: a routine that accepts spectral response information and outputs colour correction coefficients.
 
# <tt>hfi_co_correction.pro</tt>: a routine that accepts spectral response information and outputs CO conversion coefficients.
 
# <tt>lfi_read_bandpass.pro</tt>: a routine to get the desired detector level spectral transmission data (LFI) and output in a structure format used by the other routines.
 
# <tt>lfi_read_avg_bandpass.pro</tt>: a routine to get the desired LFI band-average spectral transmission data and output in a structure format used by the other routines.
 
# <tt>hfi_lfi_test_script.pro</tt>: a sample script providing examples of calling the various routines.
 
# <tt>hfi_lfi_test_script_PLA_RIMO.pro</tt>: a sample script providing examples of calling the various routines using the PLA RIMO file (without detector-level spectra).
 
# <tt>LFI_fastcc.pro</tt>: a routine to calculate LFI colour corrections using quadratic approximations (faster than integrating each time).
 
# <tt>LFI_fastcc_test.pro</tt>: a sample script providing examples of calling the LFI_fastcc routine.
 
# <tt>README.txt</tt>: a text file providing basic instructions and expected output for the hfi_lfi_test_script.pro file (basic introduction and precursor to this document).
 
 
=== Required Input Data ===
 
<div id="sec:input"></div>
 
The UC_CC routines require access to the Planck spectral response data. This is nominally provided in the RIMO files included in the same location as this package. The ingestion routines are written in such a way as to accept updated RIMO files (provided the <tt>.fits</tt> header structure uses the same naming conventions as currently / previously implemented). For users with access to the HFI databases on magique3 (i.e. members of the HFI Core-team), the software is also able to access the spectral response data directly from the HFI IMO (see examples below for details).  The software is written to allow use of the PLA RIMO file which includes only band-average spectra, as well as the full RIMO (with detector level spectra) which will be made available through the PLA in a future release.
 
 
A user may provide a unique model spectrum about which to generate colour correction coefficients specific to the model input (see §[[#sec:CC|2.6.5]]), however this is not required for standard colour correction coefficients based on power-law spectral indices and/or modified blackbody spectra.
 
 
=== Required Software Packages ===
 
<div id="sec:soft"></div>
 
This software has been tested on IDL versions 6.4, 7.1, 8.0, 8.1, and 8.2. It requires use of the <tt>mrdfits.pro</tt> file, and related sub-routines, from ''the IDL Astronomy User’s Library'' to read the RIMO <tt>.fits</tt> files. This library should be included with most IDL Healpix distributions, and is otherwise freely available online (http://idlastro.gsfc.nasa.gov/). The UC_CC routines will not work with the RIMO <tt>.fits</tt> files without routines from this library! The routines provided will work with either the full (internal) RIMO files containing detector level spectra, or the PLA (external) RIMO files with only frequency-band level spectra. To date the software has not been tested on the PLA RIMO files (this should change soon, and needs to prior to the data release).
 
 
=== Software Initialization ===
 
<div id="sec:init"></div>
 
No installation is required. It is recommended to add the UC_CC scripts to a directory within your IDL path, or add the UC_CC directory to your IDL path. As some of the UC_CC files contain multiple functions/procedures, it is also recommended to compile each of the UC_CC <tt>.pro</tt> files prior to running scripts using the respective routines; <tt>get_hfibolo_list.pro</tt> should be compiled before any of the other routines.
 
 
=== Software Use ===
 
<div id="sec:use"></div>
 
The following section outlines basic use of the UC_CC IDL scripts and provides examples.
 
 
==== Spectral Input ====
 
<div id="sec:getSpec"></div>
 
The UC_CC routines accept individual detector and band-average spectra structures as input. The<br />
 
<tt>hfi_read_bandpass.pro</tt> and <tt>hfi_read_avg_bandpass.pro</tt> routines are used to obtain this data for HFI, and the <tt>lfi_read_bandpass.pro</tt> and <tt>lfi_read_avg_bandpass.pro</tt> routines are used to obtain this data for LFI. The spectra can be restored from either a RIMO file, or an IMO database (if access to such is available). The routines return the transmission spectra by default, but are also configured to return the spectral uncertainty and interpolation flag as additional output parameters. Here are some example IDL commands using these routines:
 
 
<tt>hfi_bp = hfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg, ER_INFO=er, /FLAG)</tt>
 
<tt>hfi_bp_withCO = hfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/file', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_withCO, $</tt><br />
 
     <tt>    ER_INFO=er_withCO, FLAG = 0)</tt>
 
<tt>hfi_avg = hfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_avg, ER_INFO=er_avg, /FLAG)</tt>
 
<tt>hfi_avg_withCO = hfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/file', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_avg_withCO, $</tt><br />
 
     <tt>    ER_INFO=er_avg_withCO, FLAG = 0)</tt>
 
<tt>lfi_bp = lfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_LFI_RIMO_file.fits', ER_INFO=er)</tt>
 
<tt>lfi_avg = lfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $</tt><br />
 
     <tt>    NAME_RIMO='Name_of_LFI_RIMO_file.fits', ER_INFO=er_avg)</tt>
 
 
In the above examples, <tt>hfi_bp</tt>, <tt>hfi_bp_withCO</tt>, and <tt>lfi_bp</tt> represent IDL structures containing individual detector spectra. The variables <tt>er</tt> and <tt>er_avg</tt> containt the spectral uncertainty within a structure similar to that of the spectra. The <tt>flg</tt> and <tt>flg_avg</tt> structures contain the CO interpolation flag indiciating if a spectral data point is uniquely measured from the calibration data (i.e. <tt>flg[i] = 0</tt>), or interpolated (i.e. <tt>flg[i] = 1</tt>, see Ex. Supp. for more details). No such flag exists for LFI. If the <tt>FLAG</tt> keyword is set, flagged data points are removed from the spectral structures prior to being output; i.e. <tt>FLAG=0</tt> outputs all data and <tt>FLAG=1</tt> outputs only un-flagged data points, the default setting if FLAG is not input is the <tt>FLAG=1</tt> setting. With the <tt>RIMO</tt> keyword set, there must be a <tt>RIMO.fits</tt> file in the <tt>PATH_RIMO</tt> directory of the <tt>NAME_RIMO</tt> keyword value. The routines may also get the spectra from an IMO database (this requires the user to have access to an IMO data base with details available within the Planck collaboration).
 
 
The output of the ...read_bandpass.pro routines is an array of IDL structures. The other UC_CC routines are written in such a way as to accept these structures as input. The software has been modularized such that the subroutines within the scripts can accept input spectra in other formats. This level of use of the UC_CC routines is beyond this introduction, however. Those interested are directed to look through the original source code of the subroutines, paying particular attention to the subroutines without the hfi_ prefix within each script; these routines may be called externally. Further queries may be directed towards the authors (esp. Spencer).
 
 
The LFI RIMO files follow a different convention than that of HFI, so the ingestion routine also accounts for this. The LFI RIMO file frequency bins represent the bin start frequency rather than the bin centre frequency, and the convention is such that the transmission data need to be scaled by <math>\lambda^2</math> to be consistent with the HFI spectra. Both of these modifications are performed within the <tt>lfi_read_bandpass</tt> and <tt>lfi_read_avg bandpass</tt> routines, so their output structures are in the format expected by the remaining UC_CC routines.
 
 
The UC_CC routines follow HFI unit conversion and colour correction conventions, and have been developed primarily for use with HFI data processing. Functionality has also been included for the LFI spectra. The UC_CC routines LFI output has been verified against internal LFI coefficients for the combined case of K<math>_{\mbox{CMB}}</math> to T<math>_{\mbox{b}}</math> unit conversion and colour correction for spectral indices ranging from <math>-2</math> to <math>+4</math>. This validation confirmed that the UC_CC code treats the LFI spectra in the same way as in other LFI data processing, and thus all of the UC_CC LFI output is expected to conform with official LFI data processing.
 
 
==== UC_CC Output ====
 
<div id="sec:output"></div>
 
The UC_CC routines output conversion coefficients as arrays of IDL structures. This ensures that the detector name and coefficient are paired, and any additional information may also be provided, e.g. the CO rotational transition line in the case of a CO coefficient. It is important to note that the output for the 143-8 and 545-3 detector coefficients is intentionally set to <math>-10^{9}</math> in all cases. These two detectors have been excluded from HFI data processing due to their noise characteristics, and thus do not contribute to the band-average spectra or band-average coefficients. Ground measurements for these detectors do exist, and it is possible to determine these coefficients if needed, but they have been intentionally hidden from standard use.
 
 
==== Coefficient Uncertainty Estimate ====
 
An optional function of this software is to output an uncertainty for every unit conversion and colour correction coefficient
 
determined. This requires spectral uncertainty as input (HFI only at present), and has uncertainty of other parameters
 
as optional depending on the colour correction (e.g. CO radial velocity, dust temperature or emissivity, spectral
 
index uncertainty, user-supplied spectral profile uncertainty (see §6.5), etc.). The GETERR keyword instructs the
 
routines to calculate the coefficient uncertainty via NITER (another keyword) iterations of a Monte-Carlo uncertainty
 
simulation. This requires the BP_ERR keyword to be set to the detector uncertainty (output from the hfi_read_bandpass
 
routine), and/or the band-average spectral uncertainty to be set via the EABP (Error in Average Band-Pass) keyword
 
(output from the hfi_read_avg_bandpass routine). Please refer to the test scripts for details on how these routine calls
 
are performed. In principle it is possible to determine uncertainties for the LFI colour corrections, based on errors in
 
the spectral index, dust temperature, etc. without spectral uncertainty; this is beyond the scope of this introduction and
 
is left as an exercise (contact the authors for assistance if needed).
 
The colour correction routine accepts various error keywords for use in the GETERR uncertainty estimate. These
 
include ER_ALPHA, ER_TBD, ER_BETABD, ER_INU, associated with the ALPHA, TBD, BETABD, and INU input
 
keywords. The default setting is zero to allow the uncertainty estimate to be strictly based on the spectral uncertainty. If
 
any of the additional error keywords are set, then this additional uncertainty is combined with the spectral uncertainty
 
in the simulation run.
 
The defualt number of itereations is 2. Obviously this will not provide an accurate estimate, but not task processing
 
time if accidentally set. The example routines use 100 iterations. Published uncertainty results typically use 10000
 
iterations (but this obviously takes longer to compute).
 
 
==== Unit Conversion ====
 
<div id="sec:Uc"></div>
 
The hfi_unit_conversion.pro routine will yield a structure of unit conversion coefficients for the provided spectral input, on a frequency channel and individual detector level for both LFI and HFI. It accepts an IDL structure containing individual detector spectra as input. It also accepts a band-average structure array as an additional keyword input, and outputs coefficients derived from the provided detector average spectrum. If this ABP optional keyword input is not provided, then the optional AVG_UC keyword output is not returned, and the main output returned by the function is set to zero (the individual bolometer coefficients are still returned via the keyword outputs).
 
 
<tt>hfi_100_uc = hfi_unit_conversion(BP_INFO=hfi_bp, '100',hfibolo_100_uc, $</tt><br />
 
     <tt>    ABP=hfi_avg, AVG_UC=AVG_100_UC, CH_UC=ch_100_uc)</tt><br />
 
     <tt>help, hfibolo_100_uc, /STRUCT    ;  Displays details of the structure contents.</tt><br />
 
     <tt>uc_KCMB2MJy_100_1a = hfibolo_100_uc[0].KCMB2MJYSR</tt><br />
 
     <tt>uc_KCMB2YSZ_100_2b = hfibolo_100_uc[3].KCMB2YSZ</tt><br />
 
     <tt>uc_MJY2TB_100_avg = avg_100_uc.MJY2TB</tt><br />
 
     <tt>lfi_44_uc = hfi_unit_conversion(BP_INFO=lfi_bp, '44', lfibolo_44_uc, $</tt><br />
 
     <tt>    /lfi, ABP=lfi_avg, AVG_UC=AVG_44_UC)</tt>
 
 
In the above expressions, both the <tt>hfi_100_uc</tt> and <tt>avg_100_uc</tt> variables contain the coefficients determined using the band-average spectrum, and the <tt>ch_100_uc</tt> variable contains the average of the individual detector coefficients; these two variable sets may be similar but are not expected to be identical. The hfibolo_100_uc variable contains the individual detector values. The UC_CC unit conversion script accepts both LFI and HFI spectra in the format output by the corresponding read_..._bandpass routine. Details of the unit conversion equations are available in <cite>planck2013-p03d</cite>.
 
 
==== Colour Correction ====
 
<div id="sec:CC"></div>
 
The colour correction routine works in much the same way as the unit conversion. It requires individual detector spectra as input, and band-average spectral input is optional, with the same caveats as above (§[[#sec:Uc|2.8]]). The colour correction routine has three distinct modes of operation. The first mode is a powerlaw spectral index where the output is a multiplicative coefficient for conversion ''from'' a spectral index of <math>-1</math> ''to'' a user-supplied spectral index, <math>\alpha</math>. The second is a modified blackbody where the conversion is ''from'' a <math>-1</math> spectral index ''to'' a Planck function of temperature, <math>T</math>, and emissivity <math>\propto\nu^\beta</math> (normalized by a <math>\nu_c^\beta B_\nu(\nu_c,T)</math> factor). The third is ''from'' a <math>-1</math> spectral index ''to'' a user supplied spectral profile. One example of this use is in the provision of colour correction coefficients for Mars, Jupiter, Saturn, Uranus, and Neptune where planet model spectra is provided as the user-specified spectral profile. Details of the colour correction equations are available in the Ex. Supp. An additional set of keywords have been added to the colour correction routines to provide the relevant effective frequency for a given spectral index, modified blackbody profile, or user-specified spectral profile. Examples of this use are included in the hfi_lfi_test_script.pro file. It is stressed that the use of effective frequencies is not within the official data processing philosophy of Planck; these outputs are provided strictly to allow comparison with other experiments that have adopted the effective frequency approach.
 
 
<tt>    ;    Determine a powerlaw colour correction for 100 GHz detectors.</tt><br />
 
<tt>hfi_100_cc = hfi_color_correction(BP_INFO=hfi_bp, '100', hfibolo_100_cc, $</tt><br />
 
<tt>    /POWERLAW, ALPHA=2.0, ABP=hfi_avg, AVG_CC=AVG_100_cc)</tt><br />
 
<tt>help, hfibolo_100_cc, /struct    ;    Print info about the detector output.</tt><br />
 
<tt>    ;    Determine a modified blackbody colour correction for Beta = 1.8 and T = 18 K.</tt><br />
 
<tt>hfi_545_cc = hfi_color_correction(BP_INFO=hfi_bp, '545', hfibolo_545_cc, /MODBLACKBODY, $</tt><br />
 
<tt>    TBD = 18d, BETABD = 1.8d, ABP=hfi_avg, CH_CC=CH_545_CC, AVG_CC=AVG_545_CC)</tt><br />
 
<tt>    print, hfibolo_545_cc.BOLONAME</tt><br />
 
<tt>    print, hfibolo_545_cc.CC</tt>
 
* Note that 545-3 is set to <math>-10^9</math> as this detector is not included in flight data products due to excessive noise.
 
<tt>    ;    Try to use a user-input spectrum</tt><br />
 
<tt>nu = (hfi_avg[5].freq)    ;    in Hz</tt><br />
 
<tt>Inu = COS((hfi_avg[5].trans)) ;    some arb. profile</tt><br />
 
<tt>hfi_857_cc = hfi_color_correction(BP_INFO=hfi_bp, '857', nu, Inu, hfibolo_857_cc, $</tt><br />
 
<tt>    ABP=hfi_avg, CH_CC=CH_857_CC, AVG_CC=AVG_857_CC)</tt><br />
 
<tt>print, hfibolo_857_cc.BOLONAME</tt><br />
 
<tt>    print, hfibolo_857_cc.CC</tt>
 
 
<tt>    ;    Try to use another user-input spectrum</tt><br />
 
<tt>nu = (hfi_avg[5].freq)    ;    in Hz</tt><br />
 
<tt>Inu = LOG((hfi_avg[5].trans)) ;    some arb. profile</tt><br />
 
<tt>hfi_857_cc = hfi_color_correction(BP_INFO=hfi_bp, '857', nu, Inu, hfibolo_857_cc, $</tt><br />
 
<tt>    ABP=hfi_avg, CH_CC=CH_857_CC, AVG_CC=AVG_857_CC)</tt><br />
 
<tt>print, hfibolo_857_cc.BOLONAME</tt><br />
 
<tt>    print, hfibolo_857_cc.CC</tt>
 
 
 
 
 
The variable CH_CC represents the average of the individual detector coefficients. The AVG_CC keyword and the function return value are both the output variable for the colour correction based on the band-average spectrum (i.e. the spectra are averaged and single coefficients are determined, not the averaging of multiple coefficients). The hfibolo_... variable is the output for the individual detector coefficients. For the user specified spectral profile, i.e. nu and Inu provided by the user, the frequency sampling of nu and Inu must match that of the corresponding transmission spectra. This was demonstrated above by setting nu = (hfi_avg[5].freq) from the transmission structure array.
 
 
==== CO Correction ====
 
<div id="sec:CO"></div>
 
 
The CO correction routine provides conversion for CO emission from units of K<math>_{\mbox{CMB}}</math> to units of K km/s. The input and output formats are similar to the other UC_CC routines as described above. It is advised to use the <tt>FLAG=0</tt> setting in obtaining the detector and band-average spectra for the CO coefficients whereas it is recommended to use the <tt>FLAG=1</tt> or <tt>/FLAG</tt> setting for generation of any of the other coefficients (§[[#sec:getSpec|2.6.1]]).
 
 
<nowiki>
 
 
  ; Determine CO coefficients for 100 GHz detectors, COJ1-0 transition.
 
vrad = 0d ; radial velocity of 0 km/s.
 
    hfi_100_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, ’100’, hfibolo_100_co, $
 
    hfibolo_100_13co, vrad=vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_100_CO, $
 
    AVG_13CO=AVG_100_13CO, CH_CO=CH_100_CO, CH_13CO=CH_100_13CO, $
 
    BP_FLG=flg_withCO, FABP=flg_avg_withCO)
 
 
print, hfibolo_100_co.BOLONAME ; print the detector names
 
print, hfibolo_100_co.COLINE ; print the lower J value of the CO transition
 
print, hfibolo_100_co.CC ; print the CO coefficients
 
print, hfibolo_100_13co.CC ; print the 13CO coefficients
 
 
; Repeat the above while also getting an uncertainty estimate.
 
hfi_100_co_wEr = hfi_co_correction( BP_INFO=hfi_bp_withCO, ’100’, hfibolo_100_co_wEr, $
 
    hfibolo_100_13co_wEr, vrad=vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_100_CO_wEr, $
 
    AVG_13CO=AVG_100_13CO_wEr, CH_CO=CH_100_CO_wEr, CH_13CO=CH_100_13CO_wEr, $
 
    BP_FLG=flg_withCO, FABP=flg_avg_withCO, BP_ERR=hfi_er_withCO, EABP=hfi_er_avg_withCO, $
 
    /GETERR, NITER=100)
 
 
print, hfibolo_100_co.BOLONAME ; print the detector names
 
print, hfibolo_100_co.COLINE ; print the lower J value of the CO transition
 
print, hfibolo_100_co.CC ; print the CO coefficients
 
print, hfibolo_100_co.ER ; print the CO coefficient uncertainties
 
print, hfibolo_100_13co.CC ; print the 13CO coefficients
 
print, hfibolo_100_13co.ER ; print the 13CO coefficient uncertainties
 
 
; Use a different vrad and get the coefficients for the 143 GHz detectors.
 
; You do not have to set the BP_FLG and FABP keywords, but the result is more accurate if you do.
 
 
vrad = -30d ; radial velocity of -30 km/s (towards viewer).
 
hfi_143_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, ’143’, hfibolo_143_co, $
 
    hfibolo_143_13co, vrad=vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_143_CO, $
 
    AVG_13CO=AVG_143_13CO, CH_CO=CH_143_CO, CH_13CO=CH_143_13CO)
 
 
print, hfibolo_143_co.BOLONAME ; print the detector names
 
print, hfibolo_143_co.COLINE ; There are two 143 GHz lines inc. (both coeffs. very small)
 
print, hfibolo_143_co.CC ; print the CO coefficients
 
 
; Use another vrad and get the coefficients for the 857 GHz detectors.
 
vrad = 60d ; radial velocity of 60 km/s (away from viewer).
 
hfi_857_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, ’857’, hfibolo_857_co, $
 
    hfibolo_857_13co, vrad=vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_857_CO, $
 
    AVG_13CO=AVG_857_13CO, CH_CO=CH_857_CO, CH_13CO=CH_857_13CO)
 
 
print, hfibolo_857_co.BOLONAME ; print the detector names
 
print, hfibolo_857_co.COLINE ; There are four 857 GHz lines
 
print, hfibolo_857_co.CC ; print the CO coefficients
 
</nowiki>
 
 
Although it is possible to determine CO coefficients for all 9 of the lowest rotational transitions for each HFI channel, the UC_CC routine only outputs those within, or nearly within the relevant spectral band. The two out-of-band 143 GHz coefficients are included as a confirmation of the CO rejection within this band.
 
 
==== Nested Correction ====
 
<div id="sec:nest"></div>
 
Combinations of the above coefficients may be used to obtain additional correction factors. A few illustrative examples are included below.
 
 
===== Colour correction from <math>\alpha = -2</math> to <math>\alpha = 4 </math> =====
 
 
The colour correction from a spectral index of <math>-2</math> to <math>4</math> is done by first computing the conversion from both indices to <math>-1</math>, and then producing the correct ratio of the two.
 
 
<tt>    ;    Determine the -2 to -1 correction, and the 4 to -1 correction</tt><br />
 
<tt>alpha1 = -2d ;  the first  CC spectral index</tt><br />
 
<tt>alpha2 =  4d ;  the second CC spectral index</tt><br />
 
<tt>hfi_100_a1_cc = hfi_colour_correction(BP_INFO=hfi_bp, '100', hfibolo_100_a1_cc, $</tt><br />
 
<tt>    /POWERLAW, ALPHA=alpha1, ABP=hfi_avg, AVG_CC=AVG_100_a1_cc)</tt><br />
 
<tt>    ;    The above converts from -1 to alpha1</tt><br />
 
<tt>hfi_100_a2_cc = hfi_colour_correction(BP_INFO=hfi_bp, '100', hfibolo_100_a2_cc, $</tt><br />
 
<tt>    /POWERLAW, ALPHA=alpha2, ABP=hfi_avg, AVG_CC=AVG_100_a2_cc)</tt><br />
 
<tt>    ;    The above converts from -1 to alpha2</tt><br />
 
<tt>hfibolo_100_m2_to_4_cc = hfibolo_100_a1_cc    ;  Use this as a placeholder.</tt><br />
 
<tt>cc_m1_to_m2 = hfibolo_100_a1_cc.CC    ;  Coeffs. for -1 to -2</tt><br />
 
<tt>cc_m1_to_4  = hfibolo_100_a2_cc.CC    ;  Coeffs. for -1 to  4</tt><br />
 
<tt>cc_m2_to_4  = cc_m1_to_4/cc_m1_to_m2  ;  ratio the coeffs.</tt><br />
 
<tt>hfibolo_100_m2_to_4_cc.CC = cc_m2_to_4    ;  Set the structure values to the coeff. ratios.</tt><br />
 
<tt>print, cc_m1_to_m2    ;  the -1 -&gt; -2 coeffs.</tt><br />
 
<tt>print, cc_m1_to_4    ;  the -1 -&gt;  4 coeffs.</tt><br />
 
<tt>print, cc_m2_to_4    ;  the -2 -&gt;  4 coeffs.</tt>
 
 
It is important to get the correct numerator and denominator when determining nested/combined unit conversion and colour correction ratios. Colour correction coefficients are from spectral index <math>-1</math> ''to'' spectral index <math>\alpha</math> by definition. The units of the unit conversion coefficients should be clear. The IRAS convention implies a spectral index of <math>-1</math>, so the unit conversion coefficients yielding results in units of MJy/sr are expected to have an associated spectral index of <math>-1</math>.
 
 
===== Unit conversion / colour correction from K<math>_{\mbox{CMB}}</math> to <math>\alpha = 2</math> =====
 
 
In order to convert between units of K<math>_{\mbox{CMB}}</math> to MJy/sr with an effective spectral index of <math>\alpha = 2</math> requires both a unit conversion and a colour correction.
 
 
<tt>    ;    Determine the K_CMB to MJy/sr conversion (alpha=-1)</tt><br />
 
<tt>hfi_100_uc = hfi_unit_conversion(BP_INFO=hfi_bp, '100',hfibolo_100_uc, $</tt><br />
 
<tt>    ABP=hfi_avg, AVG_UC=AVG_100_UC)</tt><br />
 
<tt>uc_100_KCMB2MJy = hfibolo_100_uc.KCMB2MJYSR    ;    The UC Coeffs.</tt><br />
 
<tt>    ;    Determine the -1 to 2 colour correction.</tt><br />
 
<tt>hfi_100_cc = hfi_color_correction(BP_INFO=hfi_bp, '100', hfibolo_100_cc, $</tt><br />
 
<tt>    /POWERLAW, ALPHA=2.0, ABP=hfi_avg, AVG_CC=AVG_100_cc)</tt><br />
 
<tt>cc_100_m1_to_2 = hfibolo_100_cc.CC    ;    The CC coeffs.</tt><br />
 
<tt>uccc_100_Kcmb_to_2 = uc_100_KCMB2MJy*cc_100_m1_to_2    ;    Units are still MJy/sr/Kcmb</tt><br />
 
<tt>print, uccc_100_Kcmb_to_2    ;    Print the UC/CC Coeffs.</tt>
 
 
The above examples should demonstrate the basic idea. Users are welcome to experiment with various combinations of data conversion.
 
 
=== LFI quadratic (fast) Colour Correction ===
 
 
The IDL routine 'LFI_fastcc' provides a quick and easy method of calculating the colour corrections that should be applied to Planck LFI data depending on the source spectra. It uses quadratic fits of the form $cc=A + B\times\alpha + C\times\alpha^2$ to the tabulated values in section 2 of P02b Planck/LFI Calibration<cite>#planck2013-p02b</cite>. It does not have any external dependencies.
 
 
The routine can be called for the band averaged maps as
 
LFI_fastcc(freq,spectra)
 
where ''freq'' is one of 28.4, 44.1 or 70.4; or for individual RCA as
 
LFI_fastcc(70.4,spectra,detector=18)
 
(for the 70GHz RCA number 18).
 
 
Also included is the LFI_fastcc_test.pro script. This reproduces the tabulated values using the quadratic fits, and demonstrates that the values from the quadratic fit agree with those in the table to an accuracy of ~0.1%.
 
 
The conventions for the spectra and corrections are the same as in the paper, i.e. the measured values should be ''multiplied'' by the colour corrections to obtain the colour-corrected value.
 
 
=== Conclusions ===
 
<div id="sec:concl"></div>
 
 
The basic function and structure of the UC_CC routines has been described with command-line examples provided. Further details on the derivation of the equations used within the routines is found in the references cited above, i.e. <cite>#planck2013-p03d</cite>.
 
 
 
=== References ===
 
<biblio force=false>
 
#[[References]]
 
</biblio>
 
 
==Print and Plot==
 
 
There is no "print and plot" software for PLA1.
 
 
==Analysis==
 
 
There is no "analysis" software for PLA1.
 
 
 
==Format Conversion==
 
 
There is no "format conversion" software for PLA1.
 
 
 
[[Category:PLA contents]]
 

Revision as of 15:35, 14 March 2013