CRUSH: SOFIA/HIRMES

Author: Attila Kovacs <attila[AT]sigmyne.com>

Last updated: 27 Sep 2018


Table of Contents

  1. Introduction

  2. Quickstart guide
    • 2.1. HIRMES specific options
  3. Technical details for expert users
    • 3.1. HIRMES specific pixel divisions
    • 3.2. Glossary of HIRMES specific options
    • 3.3. HIRMES specific log quantities

1. Introduction

This document contains information specific to using CRUSH-2 with SOFIA/HIRMES. It should be used in conjuction with the more generic README for SOFIA instruments (README.sofia), and with the master README for using CRUSH in general.

It is recommended that you also familiarize yourself with both the SOFIA specific README (README.sofia) and the main CRUSH-2 README (especially Section 1. Getting Started), which covers installation and basic usage.

2. Quickstart guide

You may specify reduction options as command-line arguments to CRUSH. Each option in the line begins with a dash -, and should not contain white spaces, unless these are enclosed in quotes. E.g. below is a valid option line, with three options, one of which contains a white-space characters:

crush hirmes -faint -name=“My HIRMES image.fits” -projection=TAN …

Spectral cubes can be quite large, and mostly empty, especially in mid-resolution mode. As such, you may want to produce compressed output. CRUSH has an option for that:

gzip               Compress outputs (e.g. FITS) with gzip, if possible.
                   (The .gz extension will be added to the output name as
                   necessary.)

The ‘gzip’ option is enabled, by default, for spectral cubes. To disable, use ‘-blacklist=gzip’ command-line option.

The SOFIA README offers is a brief guide to a few useful options for using CRUSH with any SOFIA instrument. Here only the options specific to HIRMES are discussed.

2.1 HIRMES specific options

-spectral.unit=<spec>  Set the spectral unit to use, e.g. to `GHz` or `um`.
                    All spectral inputs and outputs will be referred to in
                    the specified unit. (The default is `Hz`).
                    @See: `spectral.grid`

-spectral.grid=X    Explcitly define the spectral bin (grid) size to X in
                    the specified `spectral.unit` (default is `Hz`).
                    @See: `spectral.unit`, `spectral.resolution`

-spectral.R=X       Specify a spectral resolving power X (f/df) at the
                    center frequency of observation. This option is used
                    only if the spectral bin (grid) size is not explicitly
                    defined via `spectral.gid`.
                    @See: `spectral.grid`

3. Technical details for expert users

From this point on, the documentation is of more technical nature, intended for expert users only.

3.1. HIRMES specific pixel divisions

For a general overview of channel divisions, please consult Section 3. (Correlated Signals) in the main README document.

bias        Grouping of pixels by TES bias line. Each subarray has 20
            bias lines, each applied to two consecutive detectors rows.

cols        Grouping of detector pixels by physical (geomtric) detector
            columns.

mux         A grouping of pixels based on their SQUID multiplexing scheme,
            allowing to decorrelate pixels that share the same readout MUX.

pins        A grouping of pixels among different MUXes that share the
            same MUX address (i.e. pin).

rows        Grouping of detector pixels by physical (geometric) detector
            rows.

series      The grouping of pixels based on the series array through which
            they are read out.

subarrays   Grouping of pixels by subarray.

3.2. Glossary of HIRMES specific options

blinds              @Expert
                    Use information from blind detectors (ones that are
                    not illuminated) when decorrelating groups of channels
                    The inclusion of blind detectors can be useful for
                    removing correlated thermal and/or electronic noise.

cols                @Alias: 'correlated.cols'
                    @Expert
                    Decorrelate on physical (geometric) detector columns. 
                    All correlated modality suboptions apply.
                    @See: 'correlated.<?>'

darkcorrect         @Expert
                    Include the dark SQUIDs when decorrelating over SQUID
                    MUXes (`mux` option).

gyrocorrect         @Since: 2.41
                    @Advanced
                    Correct for gyro drifts based on guide-star relock
                    data stored in the scan headers. This isn't normally
                    needed when the gyros funtion properly. But,
                    occasionally, they drift a fair bit, and this option
                    can activate the correction scheme on demand.

imaging.aperture=X[,Y]    @Expert
                    Specifies the imaging aperture size, either as a square
                    of X arcseconds size, or a rectangle of X by Y arcsec.  

los                 @Alias: 'correlated.los'
                    @Since: 2.41
                    @Expert
                    Remove correlations with the second-derivative to the
                    telescope line-of-sight (LOS) angle. It's a good proxy
                    for removing pitch-type acceleration response from the
                    detector timestreams.
                    @See: 'correlated.<?>'

mux                 @Alias: 'correlated.mux'
                    @Expert
                    Decorrelate on SQUID muxes. All correlated modality
                    suboptions apply.
                    @See: 'correlated.<?>'

offset.blue=dx,dy
offset.red=dx,dy
offset.hires=dx,dy  @Expert
                    Specify the subarray offset (as dx,dy pixels in
                    the focal plane) from their nominal positions, for
                    the two lowres subarrays or the hires array. 

pins                @Alias: 'correlated.pins'
                    @Expert
                    Decorrelate on pixels that share MUX addresses (pins)
                    over different MUXes. All correlated modality
                    suboptions apply.
                    @See: 'correlated.<?>'

pixelsize=X[,Y] @Expert
                    Specify the size of the pixels for calculating pixel 
                    positions based on a regular grid. 
                    The argument can be either X lateral size (in arcsec) 
                    for square pixels, or two comma separated sizes for 
                    rectangular pixels.
                    @See: 'platescale', 'rotation', 'pcenter'

platescale=X        @Expert
                    Override the plate scale recorded in the FITS, and
                    set it manually to X arcsec/mm.
                    @See: 'pixelsize'

roll                @Alias: 'correlated.roll'
                    @Since: 2.41
                    @Expert
                    Remove correlations with the second-derivative of the
                    aircraft roll angle (roll-type accelerations).
                    @See: 'correlated.<?>'

rotation=<deg>      @Expert
                    Specify the focal-plane rotation (in degrees).
                    @See: 'pixelsize'

rotation.red=<deg>     
rotation.blue=<deg>
rotation.hires=<deg>   @Expert
                    Specify the relative rotation of each subarray in 
                    the focal plane.

rows                @Alias: 'correlated.rows'
                    @Expert
                    Decorrelate along the 'row' direction of the arrays,
                    the same as SQUID address lines. All correlated 
                    modality sub-options apply.
                    @See: 'correlated.<?>'

rtoc                @Expert
                    @Since: 2.33
                    Instruct crush to reference maps to Real-Time Object 
                    Coordinates (RTOC) for sidereal and non-sidereal
                    sources alike. Otherwise, sidereal object coordinates
                    are determined via the header keywords OBSRA/OBSDEC or
                    OBJRA/OBJDEC.

series              @Alias: 'correlated.series'
                    @Expert
                    Decorrelate on the series arrays. It seems that the
                    series array (at 4K) is sensitive to some level of
                    thermal fluctuation, and enabling decorrelation on
                    these can improve imaging quality.

spectral.grid=X     Specify the bin spacing in the spectral dimension to
                    X, in the units set by 'spectral.unit'. When present
                    this option supercedes the 'spectral.R', which
                    is an elternative way to set the spectral bin size.
                    @See: 'spectral.unit' 

spectral.obs        Output spectra in the observing frame rather than the
                    default rest frame.

spectral.R=X        Specify a spectral resolving power X at the
                    center frequency of observation. This option is used
                    only if the spectral bin (grid) size is not explicitly
                    defined via `spectral.grid`.
                    @See: `spectral.grid`

spectral.unit=<spec>        Specify the unit of the spectral axis in the 
                    output data. It can be a wavelength unit, such as 'um' 
                    (micron) or a frequency unit, such as 'GHz'. 

write.fieldspec     Write the aggregate 1D field spectrum as and ASCII
                    table also. This data can also be readiliy plotted
                    using gnuplot if the '.eps' and/or '.png' sub-options
                    are set (see below). The plot can be customized via
                    a set of sub-options '.lt', '.lw', '.pt', '.ps' and
                    '.style' in accordance with gnuplot's capabilities.
                    @See: 'gnuplot'

write.fieldspec.eps    Create an EPS plot from the aggregate 1D field 
                    spectrum using gnuplot.
                    @See: 'gnuplot'
            
write.fieldspec.lt=N   Set the plot line type to gnuplot's built-in type N. 

write.fieldspec.lw=X   Set the plot line with to X points wide, e.g. 2.5.

write.fieldspec.nodata=<string>  Set how NaN (no data) values are reported
                    The specified string will be used verbetum where no
                    valid data is available. 

write.fieldspec.png    Create a PNG plot from the aggregate 1D field 
                    spectrum using gnuplot. A set of sub-options can be 
                    used to customize the appearance
                            
write.fieldspec.png.bg=<color>   Set the PNG background color to the
                    specified color (e.g. 'white' or '#FFFFFF', or 
                    'transparent').

write.fieldspec.png.size=NxM     Set the PNG output size to N by M pixels. 

write.fieldspec.ps=X   Set the plot point size scale factor to X, e.g. 1.5.

write.fieldspec.pt=N   Set the plot point tyle to gnuplot built-in type N.

write.fieldspec.show   Display the plot on screen right away.

write.fieldspec.style=<plotstyle>   Set the gnuplot plotting style for 1D
                    data. E.g. 'histep', or 'points' or 'lines' or 
                    'linespoints'.

write.flattened     Write a flattened 2D (monochrome) FITS image also.

write.flattened.gzip   Compress the flattened image with gzip.

3.3. HIRMES specific log quantities

Here you will find only the log quantities specific to HIRMES. See also README.sofia for all SOFIA specific log quantities, and the main CRUSH README for an even more generic list of available log quantities.

gratingAngle        (deg) Grating angle

gyro.max            (arcsec) Maximum gyro drift during scan.
gyro.rms            (arcsec) RMS gyro drift during scan.

FPIk                (1/radian) FPI dispersion constant

mode                HIRMES configuration mode.

ref.x               (mm) Focal plane reference X position.
ref.y               (mm) Focal plane reference Y position.

strip               [0-7] Integer index of hires strip in used, if 
                    applicable

Copyright (C)2018 – Attila Kovacs <attila[AT]sigmyne.com>