Source code for obstools.rimas_dither_pattern

# -*- coding: utf-8 -*-
#
#  This file is part of LDTObserverTools.
#
#   This Source Code Form is subject to the terms of the Mozilla Public
#   License, v. 2.0. If a copy of the MPL was not distributed with this
#   file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
#  Created on 19-Aug-2026
#
#  @author: tbowers

"""Create ECSV sidecars that correct RIMAS dither metadata

LDTObserverTools contains python ports of various LDT Observer Tools

Lowell Discovery Telescope (Lowell Observatory: Flagstaff, AZ)
https://lowell.edu

The generated tables identify the dither pattern, position, and sequence for
all commanded RIMAS frames, including exposures that were not written to disk.
"""

# Built-In Libraries
import argparse
from collections.abc import Iterable, Sequence
import dataclasses
import pathlib

# 3rd-Party Libraries
import astropy.table

# Local Libraries
from obstools import utils

# Module-level Constants
PATTERNS = {"ABBA": ("A", "B", "B", "A"), "ONOFF": ("On", "Off")}


[docs] @dataclasses.dataclass(frozen=True) class DitherSequence: """Represent the recorded frames in one commanded dither sequence. Parameters ---------- frames : tuple of int Commanded frame numbers in strictly increasing order, including frames that were not written to disk. sequence_id : int Positive identifier for the commanded sequence. Attributes ---------- frames : tuple of int Recorded frame numbers in the sequence. sequence_id : int Identifier for the sequence. """ frames: tuple[int, ...] sequence_id: int
[docs] def normalize_pattern(sequence_type: str) -> str: """Return the canonical name of a supported dither pattern. Parameters ---------- sequence_type : str Pattern name. Matching ignores case and surrounding whitespace. Returns ------- str Uppercase canonical pattern name. Raises ------ ValueError If ``sequence_type`` is not supported. """ pattern = sequence_type.strip().upper() if pattern not in PATTERNS: raise ValueError( f"Unsupported sequence type {sequence_type!r}; choose {', '.join(PATTERNS)}." ) return pattern
[docs] def parse_frame_list(value: str | Iterable[str]) -> tuple[int, ...]: """Parse frame numbers from one or more strings. Parameters ---------- value : str or iterable of str Frame numbers supplied as individual strings, comma-separated strings, or a mixture of both. Whitespace and empty fields are ignored. Returns ------- tuple of int Parsed frame numbers in input order. Raises ------ ValueError If a nonempty field is not an integer or no frames are given. """ values = (value,) if isinstance(value, str) else value try: frames = tuple( int(item.strip()) for entry in values for item in entry.split(",") if item.strip() ) except ValueError as exc: raise ValueError( f"Invalid frame list {value!r}; use space- or comma-separated integers." ) from exc if not frames: raise ValueError("A dither sequence must contain at least one frame.") return frames
[docs] def validate_sequence(sequence: DitherSequence, sequence_type: str) -> None: """Validate one sequence against a dither pattern. Parameters ---------- sequence : DitherSequence Sequence to validate. sequence_type : str Supported dither pattern name. Raises ------ ValueError If the pattern or sequence is invalid. """ pattern, frames = normalize_pattern(sequence_type), sequence.frames if not frames: raise ValueError("A dither sequence must contain at least one frame.") if sequence.sequence_id < 1: raise ValueError("Sequence IDs must be positive.") if any(frame < 0 for frame in frames): raise ValueError("Frame numbers must be non-negative.") if any(b <= a for a, b in zip(frames, frames[1:])): raise ValueError( f"Frames in sequence {sequence.sequence_id} must increase strictly." ) if frames[-1] - frames[0] >= len(PATTERNS[pattern]): raise ValueError( f"Frames in sequence {sequence.sequence_id} span more than one {pattern} pattern." )
[docs] def build_correction_table( sequence_type: str, sequences: Sequence[DitherSequence], date: str, arms: Iterable[str] = ("YJ", "HK"), source: str = "observing log", ) -> astropy.table.Table: """Build a RIMAS dither metadata correction table. Parameters ---------- sequence_type : str Supported dither pattern name. sequences : sequence of DitherSequence Recorded frames grouped by commanded sequence. date : str Observing date in ``YYYYMMDD`` format. arms : iterable of str, optional Detector arms to include; supported values are ``"YJ"`` and ``"HK"``. source : str, optional Description of the correction metadata source. Returns ------- astropy.table.Table Correction rows for every recorded frame and selected arm. Raises ------ ValueError If inputs are invalid, identifiers or frames are duplicated, or no rows can be produced. """ pattern = normalize_pattern(sequence_type) if len(date) != 8 or not date.isdigit(): raise ValueError("Date must have YYYYMMDD format.") use_arms = tuple(str(arm).strip().upper() for arm in arms) if not use_arms or any(arm not in ("YJ", "HK") for arm in use_arms): raise ValueError("Arms must contain one or both of YJ and HK.") if len(set(use_arms)) != len(use_arms): raise ValueError("Arms must not contain duplicates.") rows, seen_frames, seen_ids = [], set(), set() for sequence in sequences: validate_sequence(sequence, pattern) if sequence.sequence_id in seen_ids: raise ValueError(f"Duplicate sequence ID {sequence.sequence_id}.") seen_ids.add(sequence.sequence_id) first = sequence.frames[0] for frame in sequence.frames: if frame in seen_frames: raise ValueError(f"Frame {frame} occurs in more than one sequence.") seen_frames.add(frame) dithnum = frame - first + 1 for arm in use_arms: rows.append( ( f"{date}.rimas.{frame:04d}.{arm}.fits", pattern, dithnum, PATTERNS[pattern][dithnum - 1], sequence.sequence_id, source, ) ) if not rows: raise ValueError("At least one dither sequence is required.") table = astropy.table.Table( rows=rows, names=("filename", "dithpat", "dithnum", "dithpos", "dithseq", "source"), ) table.meta["description"] = "RIMAS dither metadata corrections" return table
[docs] def write_correction_table( table: astropy.table.Table, output: str | pathlib.Path, overwrite: bool = False ) -> pathlib.Path: """Write a correction table in ECSV format. Parameters ---------- table : astropy.table.Table Correction table to write. output : str or pathlib.Path Destination path. Missing parent directories are created. overwrite : bool, optional Whether to replace an existing file. Returns ------- pathlib.Path Absolute path of the written file. """ output_path = pathlib.Path(output).expanduser().resolve() output_path.parent.mkdir(parents=True, exist_ok=True) table.write(output_path, format="ascii.ecsv", overwrite=overwrite) return output_path
[docs] class RimasDitherPattern(utils.ScriptBase): """Provide the CLI for creating RIMAS dither sidecars. Notes ----- One ``--sequence`` option is accepted per commanded sequence. Sequence identifiers follow the order of those options. """
[docs] @classmethod def get_parser( cls, description: str | None = None, width: int | None = None, formatter: type[ argparse.HelpFormatter ] = argparse.ArgumentDefaultsHelpFormatter, ) -> argparse.ArgumentParser: """Construct the command-line argument parser. Parameters ---------- description : str or None, optional Parser description. Retained for base-class compatibility. width : int or None, optional Maximum width of formatted help output. formatter : type of argparse.HelpFormatter, optional Help formatter class. Returns ------- argparse.ArgumentParser Configured command-line parser. """ parser = super().get_parser( description="Create an ECSV sidecar correcting RIMAS dither metadata.", width=width, formatter=formatter, ) parser.add_argument("sequence_type", choices=tuple(PATTERNS)) parser.add_argument( "-s", "--sequence", action="append", nargs="+", required=True, metavar="FRAME", help=( "Full frame list for one commanded sequence, including frames not " "written to disk. Repeat for each sequence; Bash brace expansion " "such as -s {86..89} is supported." ), ) parser.add_argument("--date", required=True, help="Observing date (YYYYMMDD)") parser.add_argument( "--arms", nargs="+", default=("YJ", "HK"), choices=("YJ", "HK") ) parser.add_argument("-o", "--output", default="rimas_dither_corrections.ecsv") parser.add_argument("--source", default="observing log") parser.add_argument("--overwrite", action="store_true") return parser
[docs] @staticmethod def main(args: argparse.Namespace) -> None: """Create and write a correction table from parsed arguments. Parameters ---------- args : argparse.Namespace Parsed command-line arguments produced by :meth:`get_parser`. """ sequences = [ DitherSequence(parse_frame_list(value), index) for index, value in enumerate(args.sequence, start=1) ] table = build_correction_table( args.sequence_type, sequences, args.date, args.arms, args.source ) output = write_correction_table(table, args.output, args.overwrite) print(f"Wrote {len(table)} corrections to {output}")