hifast.radec Coordinate Calculation#

Overview#

The hifast.radec module calculates the celestial coordinates (Right Ascension and Declination) for each spectrum in your data. It matches the timestamp of the spectral data with the telescope’s feed cabin trajectory log (KY files) to compute coordinates for all 19 beams simultaneously.

Processing Workflow#

  1. Input Data (Two Modes) The module accepts two types of input files, determining the processing mode:

    • HDF5 File (Spectral Data): Pass an HDF5 file (e.g., data/*_specs_T.hdf5) using the fname argument.

      • Usage: The module only reads the time information (S/mjd) from this file. It does not rely on any existing coordinate columns.

      • Output: It generates a new file containing RA/DEC for all 19 beams, derived from the feed cabin position and the fixed geometry of the receiver.

    • Excel File (Feed Cabin Log): Pass a KY file (.xlsx) directly.

      • Usage: Calculates the RA/DEC trajectory of the feed cabin itself.

      • Output: Useful for inspecting the telescope’s tracking path independent of spectral data.

  2. Locating Feed Cabin Data (KY Files) To calculate coordinates, the program needs the telescope’s position log, known as “KY files” (Excel format).

    • Automatic Search: By default, it searches for matching KY files in standard directories, checking ``~/KY`` first, followed by others like /data/hw1/FAST/KY and /data31/KY. You can customize the search directory with --ky_dir.

    • Manual Specification: If your KY files are in a non-standard location, you can explicitly list one or more of them using --ky_files.

  3. Coordinate Calculation The module interpolates the feed cabin position to the exact time of each spectrum.

    • Backend: You can choose between astropy (default) and erfa for the coordinate transformation using --backend.

      • Astropy (Recommended): Automatically downloads and applies Earth orientation parameters (including dUT1 and polar motion). If you use this backend, the manual --dUT1 argument is ignored.

        Note

        If your computer does not have internet access, Astropy will fail to download IERS data, leading to errors like:

        • IERSStaleWarning: leap-second file is expired.

        • astropy.utils.iers.iers.IERSRangeError: (some) times are outside of range covered by IERS table.

        • urllib.error.URLError: <urlopen error [Errno -2] Name or service not known>

        To resolve this, please use the IERS Offline Cache Updater tool to manually update the offline cache.

      • Erfa: Requires manual specification of --dUT1 if special requirement is needed.

    • Extrapolation: Ideally, the feed cabin data (KY file) should fully cover the time range of your spectral data. However, small timing offsets can occur.

      • --tol (default: 1 second) defines the maximum allowed time gap for extrapolation.

      • If the spectral data starts slightly before or ends slightly after the KY data records (within this tolerance), the coordinates are extrapolated linearly.

      • is_extrapo: The output file will contain a boolean dataset named is_extrapo marking these extrapolated points.

      • Handling in Downstream Analysis: When processing with hifast.multi, you can use the parameter --mask_extrapo True to automatically mask these extrapolated data points as NaN.

      • If the gap exceeds this tolerance, the program will raise an error (unable to find a matching KY file).

    • Environmental Corrections: Parameters like --temperature, --phpa (pressure), and --humidity are used for refraction corrections.

  4. Output The result is a new HDF5 file (suffix -radec.hdf5) containing the calculated RA and DEC columns.

    • Plotting: Use --plot to generate a PDF showing the telescope’s trajectory during the observation.

Examples#

# Basic usage (auto-search for KY files)
python -m hifast.radec data/observation.hdf5

# Manually specifying a KY file and enabling plotting
python -m hifast.radec data/observation.hdf5 --ky_files data/feed_log.xlsx --plot

# Using a custom tolerance for data with gaps
python -m hifast.radec data/observation.hdf5 --tol 5.0

# Processing a KY file directly (to inspect the feed trajectory)
python -m hifast.radec data/feed_log.xlsx --plot

Full Parameter Reference#

Tip

You can also view the full list of parameters and their descriptions directly in your terminal by running:

python -m hifast.radec --help

Calculate RA/DEC coordinates from feed cabin data.

usage: python -m hifast.radec [-h] [--outdir DIR] [-f] [--plot]
                              [--ky_files [FILE ...]] [--ky_dir DIR]
                              [--backend {erfa,astropy}] [--tol SEC]
                              [--ky_fixed] [--phpa HPA] [--temperature DEG_C]
                              [--humidity 0-1] [--dUT1 SEC] [-n INT]
                              [--no_cache]
                              FILE

Input/Output#

FILE

Input file path. Can be an HDF5 spectral data file (must contain “S/mjd”) or a KY feed cabin log file (.xlsx).

--outdir

Output directory. Defaults to the input file directory (for HDF5) or current directory (for XLSX).

-f

Force overwrite of the output file if it already exists.

Default: False

--plot

Create a PDF plot showing the calculated RA/DEC trajectory.

Default: False

Configuration#

--ky_files, --ky-files

Explicitly specify one or more KY (feed cabin log) file paths. Separate multiple files with spaces. If omitted, searches in –ky_dir based on observation time.

--ky_dir, --ky-dir

Base directory to search for KY files. Defaults to standard locations, with ~/KY checked first, followed by others like /data31/KY.

--backend

Possible choices: erfa, astropy

Coordinate calculation backend. “astropy” (default) is recommended (auto-handles Earth orientation). “erfa” is a lower-level alternative.

Default: “astropy”

--tol

Maximum allowed extrapolation time [seconds]. Coordinates are extrapolated for gaps smaller than this; larger gaps raise an error.

Default: 1

--ky_fixed, --ky-fixed

Assume fixed feed position. Useful for early drift scans with incomplete trajectory logs.

Default: False

Environment#

--phpa

Atmospheric pressure [hPa]. Used for refraction correction.

Default: 925.0

--temperature

Ground-level temperature [Celsius]. Used for refraction correction.

Default: 15.0

--humidity

Relative humidity [0.0 - 1.0]. Used for refraction correction.

Default: 0.8

--dUT1

UT1-UTC time difference [seconds]. Only used for “erfa” backend (ignored for “astropy” as it handles it automatically).

Performance#

-n, --nproc

Number of parallel processes for multi-beam calculation.

Default: 1

--no_cache, --no-cache

Disable using cached intermediate results (forces fresh KY file processing).

Default: False