Software utilities

Unpack and Display[edit]

There is no "unpack and display" software for PLA1.

Unit Conversion and Colour Correction[edit]

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 [[1]]

Relevant Documentation[edit]

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 #planck2013-p03d 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[edit]

This section provides a brief explanation of each file included in the UC_CC distribution.

get_hfibolo_list.pro: used to provide basic detector information (i.e. names) within subsequent routines.
hfi_read_bandpass.pro: a routine to get the desired detector level spectral transmission data (HFI) and output in a structure format used by the other routines.
hfi_read_avg_bandpass.pro: a routine to get the desired HFI band-average spectral transmission data and output in a structure format used by the other routines.
hfi_unit_conversion.pro: a routine that accepts spectral response information and outputs unit conversion coefficients.
hfi_colour_correction.pro: a routine that accepts spectral response information and outputs colour correction coefficients.
hfi_co_correction.pro: a routine that accepts spectral response information and outputs CO conversion coefficients.
lfi_read_bandpass.pro: a routine to get the desired detector level spectral transmission data (LFI) and output in a structure format used by the other routines.
lfi_read_avg_bandpass.pro: a routine to get the desired LFI band-average spectral transmission data and output in a structure format used by the other routines.
hfi_lfi_test_script.pro: a sample script providing examples of calling the various routines.
hfi_lfi_test_script_PLA_RIMO.pro: a sample script providing examples of calling the various routines using the PLA RIMO file (without detector-level spectra).
LFI_fastcc.pro: a routine to calculate LFI colour corrections using quadratic approximations (faster than integrating each time).
LFI_fastcc_test.pro: a sample script providing examples of calling the LFI_fastcc routine.
README.txt: 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[edit]

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 .fits 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[edit]

This software has been tested on IDL versions 6.4, 7.1, 8.0, 8.1, and 8.2. It requires use of the mrdfits.pro file, and related sub-routines, from the IDL Astronomy User’s Library to read the RIMO .fits 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 .fits 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[edit]

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 .pro files prior to running scripts using the respective routines; get_hfibolo_list.pro should be compiled before any of the other routines.

Software Use[edit]

The following section outlines basic use of the UC_CC IDL scripts and provides examples.

Spectral Input[edit]

The UC_CC routines accept individual detector and band-average spectra structures as input. The
hfi_read_bandpass.pro and hfi_read_avg_bandpass.pro routines are used to obtain this data for HFI, and the lfi_read_bandpass.pro and lfi_read_avg_bandpass.pro 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:

hfi_bp = hfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $

         NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg, ER_INFO=er, /FLAG)
hfi_bp_withCO = hfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/file', $

         NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_withCO, $

         ER_INFO=er_withCO, FLAG = 0)
hfi_avg = hfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $

         NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_avg, ER_INFO=er_avg, /FLAG)
hfi_avg_withCO = hfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/file', $

         NAME_RIMO='Name_of_RIMO_file.fits', FLG_INFO=flg_avg_withCO, $

         ER_INFO=er_avg_withCO, FLAG = 0)
lfi_bp = lfi_read_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $

         NAME_RIMO='Name_of_LFI_RIMO_file.fits', ER_INFO=er)
lfi_avg = lfi_read_avg_bandpass(/RIMO, PATH_RIMO='/path/to/RIMO/file/', $

         NAME_RIMO='Name_of_LFI_RIMO_file.fits', ER_INFO=er_avg)

In the above examples, hfi_bp, hfi_bp_withCO, and lfi_bp represent IDL structures containing individual detector spectra. The variables er and er_avg containt the spectral uncertainty within a structure similar to that of the spectra. The flg and flg_avg structures contain the CO interpolation flag indiciating if a spectral data point is uniquely measured from the calibration data (i.e. flg[i] = 0), or interpolated (i.e. flg[i] = 1, see Ex. Supp. for more details). No such flag exists for LFI. If the FLAG keyword is set, flagged data points are removed from the spectral structures prior to being output; i.e. FLAG=0 outputs all data and FLAG=1 outputs only un-flagged data points, the default setting if FLAG is not input is the FLAG=1 setting. With the RIMO keyword set, there must be a RIMO.fits file in the PATH_RIMO directory of the NAME_RIMO 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 lfi_read_bandpass and lfi_read_avg bandpass 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[edit]

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[edit]

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).

hfi_100_uc = hfi_unit_conversion(BP_INFO=hfi_bp, '100',hfibolo_100_uc, $

         ABP=hfi_avg, AVG_UC=AVG_100_UC, CH_UC=ch_100_uc)

     help, hfibolo_100_uc, /STRUCT ; Displays details of the structure contents.
     uc_KCMB2MJy_100_1a = hfibolo_100_uc[0].KCMB2MJYSR
     uc_KCMB2YSZ_100_2b = hfibolo_100_uc[3].KCMB2YSZ
     uc_MJY2TB_100_avg = avg_100_uc.MJY2TB
     lfi_44_uc = hfi_unit_conversion(BP_INFO=lfi_bp, '44', lfibolo_44_uc, $

         /lfi, ABP=lfi_avg, AVG_UC=AVG_44_UC)

In the above expressions, both the hfi_100_uc and avg_100_uc variables contain the coefficients determined using the band-average spectrum, and the ch_100_uc 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 planck2013-p03d.

Colour Correction[edit]

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 (§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.

    ;    Determine a powerlaw colour correction for 100 GHz detectors.
hfi_100_cc = hfi_color_correction(BP_INFO=hfi_bp, '100', hfibolo_100_cc, $
    /POWERLAW, ALPHA=2.0, ABP=hfi_avg, AVG_CC=AVG_100_cc)
help, hfibolo_100_cc, /struct    ;    Print info about the detector output.
    ;    Determine a modified blackbody colour correction for Beta = 1.8 and T = 18 K.
hfi_545_cc = hfi_color_correction(BP_INFO=hfi_bp, '545', hfibolo_545_cc, /MODBLACKBODY, $
    TBD = 18d, BETABD = 1.8d, ABP=hfi_avg, CH_CC=CH_545_CC, AVG_CC=AVG_545_CC)
    print, hfibolo_545_cc.BOLONAME
    print, hfibolo_545_cc.CC

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.

    ;    Try to use a user-input spectrum
nu = (hfi_avg[5].freq)    ;    in Hz
Inu = COS((hfi_avg[5].trans)) ;    some arb. profile
hfi_857_cc = hfi_color_correction(BP_INFO=hfi_bp, '857', nu, Inu, hfibolo_857_cc, $
    ABP=hfi_avg, CH_CC=CH_857_CC, AVG_CC=AVG_857_CC)
print, hfibolo_857_cc.BOLONAME
    print, hfibolo_857_cc.CC

    ;    Try to use another user-input spectrum
nu = (hfi_avg[5].freq)    ;    in Hz
Inu = LOG((hfi_avg[5].trans)) ;    some arb. profile
hfi_857_cc = hfi_color_correction(BP_INFO=hfi_bp, '857', nu, Inu, hfibolo_857_cc, $
    ABP=hfi_avg, CH_CC=CH_857_CC, AVG_CC=AVG_857_CC)
print, hfibolo_857_cc.BOLONAME
    print, hfibolo_857_cc.CC

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[edit]

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 FLAG=0 setting in obtaining the detector and band-average spectra for the CO coefficients whereas it is recommended to use the FLAG=1 or /FLAG setting for generation of any of the other coefficients (§2.6.1).

    ;    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, ABP=hfi_avg_withCO, AVG_CO=AVG_100_CO, $
    AVG_13CO=AVG_100_13CO, CC_CO=CC_100_CO, CC_13CO=CC_100_13CO)
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
    ;    Use a different vrad and get the coefficients for the 143 GHz detectors.
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, ABP=hfi_avg_withCO, AVG_CO=AVG_143_CO, $
    AVG_13CO=AVG_143_13CO, CC_CO=CC_143_CO, CC_13CO=CC_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, ABP=hfi_avg_withCO, AVG_CO=AVG_857_CO, $
    AVG_13CO=AVG_857_13CO, CC_CO=CC_857_CO, CC_13CO=CC_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

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[edit]

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][edit]

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.

    ;    Determine the -2 to -1 correction, and the 4 to -1 correction
alpha1 = -2d ;   the first  CC spectral index
alpha2 =  4d ;   the second CC spectral index
hfi_100_a1_cc = hfi_colour_correction(BP_INFO=hfi_bp, '100', hfibolo_100_a1_cc, $
    /POWERLAW, ALPHA=alpha1, ABP=hfi_avg, AVG_CC=AVG_100_a1_cc)
    ;    The above converts from -1 to alpha1
hfi_100_a2_cc = hfi_colour_correction(BP_INFO=hfi_bp, '100', hfibolo_100_a2_cc, $
    /POWERLAW, ALPHA=alpha2, ABP=hfi_avg, AVG_CC=AVG_100_a2_cc)
    ;    The above converts from -1 to alpha2
hfibolo_100_m2_to_4_cc = hfibolo_100_a1_cc    ;   Use this as a placeholder.
cc_m1_to_m2 = hfibolo_100_a1_cc.CC    ;  Coeffs. for -1 to -2
cc_m1_to_4  = hfibolo_100_a2_cc.CC    ;  Coeffs. for -1 to  4
cc_m2_to_4  = cc_m1_to_4/cc_m1_to_m2  ;  ratio the coeffs.
hfibolo_100_m2_to_4_cc.CC = cc_m2_to_4    ;  Set the structure values to the coeff. ratios.
print, cc_m1_to_m2    ;  the -1 -> -2 coeffs.
print, cc_m1_to_4     ;  the -1 ->  4 coeffs.
print, cc_m2_to_4     ;  the -2 ->  4 coeffs.

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][edit]

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.

    ;    Determine the K_CMB to MJy/sr conversion (alpha=-1)
hfi_100_uc = hfi_unit_conversion(BP_INFO=hfi_bp, '100',hfibolo_100_uc, $
    ABP=hfi_avg, AVG_UC=AVG_100_UC)
uc_100_KCMB2MJy = hfibolo_100_uc.KCMB2MJYSR    ;    The UC Coeffs.
    ;    Determine the -1 to 2 colour correction.
hfi_100_cc = hfi_color_correction(BP_INFO=hfi_bp, '100', hfibolo_100_cc, $
    /POWERLAW, ALPHA=2.0, ABP=hfi_avg, AVG_CC=AVG_100_cc)
cc_100_m1_to_2 = hfibolo_100_cc.CC    ;    The CC coeffs.
uccc_100_Kcmb_to_2 = uc_100_KCMB2MJy*cc_100_m1_to_2    ;    Units are still MJy/sr/Kcmb
print, uccc_100_Kcmb_to_2    ;    Print the UC/CC Coeffs.

The above examples should demonstrate the basic idea. Users are welcome to experiment with various combinations of data conversion.

LFI quadratic (fast) Colour Correction[edit]

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 Planck Collaboration, P02b Planck/LFI Calibration. It 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 {\it multiplied} by the colour corrections to obtain the colour-corrected value.

Conclusions[edit]

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. #planck2013-p03d.

References[edit]

References

</biblio>

Print and Plot[edit]

There is no "print and plot" software for PLA1.

Analysis[edit]

There is no "analysis" software for PLA1.

Format Conversion[edit]

There is no "format conversion" software for PLA1.