Difference between revisions of "Software utilities"

From Planck Legacy Archive Wiki
Jump to: navigation, search
(Spectral Input)
 
(38 intermediate revisions by 6 users not shown)
Line 1: Line 1:
==Unpack and Display==
+
This chapter contains information about the auxiliary software product used by the two DPCs and available for download from the PLA.
  
There is no "unpack and display" software for PLA1.
+
<!---* [[Planck Sky Model | Planck Sky Model simulation tool]] --->
 
+
<!---* [[Mapmaking | Mapmaking from timelines and ring tools]] --->
==Unit Conversion and Colour Correction==
+
<!---* [[Febecop tools | FEBeCoP effective beam extraction and convolution tools]] --->
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:
+
* [[Unit conversion and Color correction | Unit conversion and colour correction]]  
 
+
* [[SMICA weights propagation code | SMICA weights propagation code ]]
UC_CC_v101/get_hfibolo_list.pro
 
UC_CC_v101/hfi_co_correction.pro
 
UC_CC_v101/hfi_colour_correction.pro
 
UC_CC_v101/hfi_lfi_test_script.pro
 
UC_CC_v101/hfi_read_avg_bandpass.pro
 
UC_CC_v101/hfi_read_bandpass.pro
 
UC_CC_v101/hfi_unit_conversion.pro
 
UC_CC_v101/lfi_read_avg_bandpass.pro
 
UC_CC_v101/lfi_read_bandpass.pro
 
UC_CC_v101/README.txt
 
UC_CC_v101/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>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).
 
 
 
A user may provide a unique model spectrum about which to generate colour correction coefficients specific to the model input (see §[sec:CC]), 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). An example is provided here:
 
 
 
 
 
<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>
 
 
 
<tt>bp = hfi_read_bandpass(/IMO, LBL_IMO='3_20_detilt_t2_ptcor6', $</tt><br />
 
    <tt>    PATH_IMO='/data/dmc/MISS03/METADATA')</tt>
 
 
 
<tt>bp = hfi_read_bandpass(/IMO, LBL_IMO='3_20_detilt_t2_ptcor6', $</tt><br />
 
 
 
 
 
 
 
<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>
 
 
 
 
 
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.
 
 
 
=== 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]). 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>
 
 
 
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]]).
 
 
 
<tt>    ;    Determine CO coefficients for 100 GHz detectors, COJ1-0 transition.</tt><br />
 
     <tt>vrad = 0d    ;    radial velocity of 0 km/s.</tt><br />
 
     <tt>hfi_100_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, '100', hfibolo_100_co, $</tt><br />
 
     <tt>    hfibolo_100_13co, vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_100_CO, $</tt><br />
 
     <tt>    AVG_13CO=AVG_100_13CO, CC_CO=CC_100_CO, CC_13CO=CC_100_13CO)</tt><br />
 
     <tt>print, hfibolo_100_co.BOLONAME ;    print the detector names</tt><br />
 
     <tt>print, hfibolo_100_co.COLINE  ;    print the lower J value of the CO transition</tt><br />
 
     <tt>print, hfibolo_100_co.CC      ;    print the CO coefficients</tt><br />
 
     <tt>print, hfibolo_100_13co.CC    ;    print the 13CO coefficients</tt><br />
 
     <tt>    ;    Use a different vrad and get the coefficients for the 143 GHz detectors.</tt><br />
 
     <tt>vrad = -30d    ;    radial velocity of -30 km/s (towards viewer).</tt><br />
 
     <tt>hfi_143_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, '143', hfibolo_143_co, $</tt><br />
 
     <tt>    hfibolo_143_13co, vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_143_CO, $</tt><br />
 
     <tt>    AVG_13CO=AVG_143_13CO, CC_CO=CC_143_CO, CC_13CO=CC_143_13CO)</tt><br />
 
     <tt>print, hfibolo_143_co.BOLONAME ;    print the detector names</tt><br />
 
     <tt>print, hfibolo_143_co.COLINE  ;    There are two 143 GHz lines inc. (both coeffs. very small)</tt><br />
 
     <tt>print, hfibolo_143_co.CC      ;    print the CO coefficients</tt><br />
 
     <tt>    ;    Use another vrad and get the coefficients for the 857 GHz detectors.</tt><br />
 
     <tt>vrad = 60d    ;    radial velocity of 60 km/s (away from viewer).</tt><br />
 
     <tt>hfi_857_co = hfi_co_correction( BP_INFO=hfi_bp_withCO, '857', hfibolo_857_co, $</tt><br />
 
     <tt>    hfibolo_857_13co, vrad, ABP=hfi_avg_withCO, AVG_CO=AVG_857_CO, $</tt><br />
 
     <tt>    AVG_13CO=AVG_857_13CO, CC_CO=CC_857_CO, CC_13CO=CC_857_13CO)</tt><br />
 
     <tt>print, hfibolo_857_co.BOLONAME ;    print the detector names</tt><br />
 
     <tt>print, hfibolo_857_co.COLINE  ;    There are four 857 GHz lines</tt><br />
 
     <tt>print, hfibolo_857_co.CC      ;    print the CO coefficients</tt>
 
 
 
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.
 
 
 
=== 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]]
 

Latest revision as of 09:49, 10 July 2018

This chapter contains information about the auxiliary software product used by the two DPCs and available for download from the PLA.

Planck Legacy Archive