
# 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>


