Skip to content

quicklooks.rst

Latest commit

 

History

History
154 lines (105 loc) · 4.86 KB

quicklooks.rst

File metadata and controls

154 lines (105 loc) · 4.86 KB

Quicklook Generation

This document provides a high-level overview of the workflow and usage of the QuicklookGenerator system. It is intended to help developers understand how quicklook plots are produced from IMAP instrument data files.

Overview

Each instrument implements its own plotting logic while sharing a common initialization, data-loading, and dispatch workflow.

The system is built around four major components:

  1. Dataset loading – converting a CDF file into an xarray.Dataset.
  2. Instrument detection – determining the correct quicklook generator class.
  3. Abstract quicklook interface – common API for all instruments.
  4. Instrument-specific subclasses – actual plotting implementations.

Workflow

  1. User supplies a CDF file path:

    quicklook = get_instrument_quicklook("path/to/file.cdf")

  2. The filename is parsed using ScienceFilePath.extract_filename_components to extract the instrument field.

  3. The correct Quicklook subclass is selected via the QuicklookGeneratorType enum. For example:

    MAG  → MagQuicklookGenerator

    The pattern continues for each individual instrument.

  4. The chosen class is instantiated, and the constructor:

    • Loads the dataset using dataset_into_xarray.
    • Stores instrument metadata (such as the instrument name).
    • Initializes plotting-related attributes.

  5. The user calls two_dimensional_plot(variable="..."). This method is implemented by each subclass and acts as a routing mechanism that decides which quicklook plot to generate.

    Example for MAG:

    mag_ql = MagQuicklookGenerator("imap_mag_20250101_v01.cdf")
mag_ql.two_dimensional_plot(variable="mag sensor co-ord")

  6. The requested plot function runs, accessing data from the internal xarray.Dataset and generating figures using Matplotlib.

  7. Plots are displayed, and the workflow ends. No data is returned— the quicklook system produces visualizations only.

Core Components

Abstract Base Class: QuicklookGenerator

The QuicklookGenerator abstract base class provides:

  • Unified dataset loading via dataset_into_xarray.
  • Common metadata attributes (instrument, title, axis labels, etc.).
  • Basic validation to ensure that a dataset is present.
  • An abstract method two_dimensional_plot, which each instrument subclass must implement as a dispatch mechanism.

Time & Coordinate Handling

Instrument data often stores time in J2000 nanoseconds. These values are converted to UTC timestamps using:

convert_j2000_to_utc(time_array)

This conversion internally uses:

  • A fixed epoch: 2000-01-01 11:58:55.816
  • NumPy timedelta64 arithmetic
  • Output as datetime64[ns] UTC timestamps

This routine is used across all instruments providing an epoch field.

Instrument Dispatch Logic

Users should begin quicklook generation by calling:

quicklook = get_instrument_quicklook(filename)

This function:

  1. Extracts the instrument identifier from the filename.
  2. Uses QuicklookGeneratorType to map the instrument to a class.
  3. Returns an instantiated quicklook object.

Example:

>>> ql = get_instrument_quicklook("imap_swapi_20250101_v02.cdf")
>>> ql.two_dimensional_plot("count rates")

Adding Support for New Instruments

To extend the quicklook system:

  1. Create a new subclass:

    class NewInstQuicklookGenerator(QuicklookGenerator):
    ...

  2. Implement two_dimensional_plot as a dispatch method.

  3. Add plot functions as needed.

  4. Register the class in the QuicklookGeneratorType enum.

  5. Ensure that ScienceFilePath.extract_filename_components correctly identifies the instrument.

Instrument Team Support

To implement a new instrument-specific quicklook, instrument teams must provide a minimal set of information that defines what plots are required and how the underlying data should be interpreted.

Required Information

  1. List of quicklook plots - A high-level description of each plot to be generated. - Whether each plot is 1-D (line), 2-D (spectrogram), or multi-panel.
  2. Variables required for each plot - CDF variable names. - Which CDF files contain the required variables.
  3. Time-axis requirements (if applicable) - Desired time range (full file, event-based selection, rolling window).
  4. Plot formatting preferences - Preferred units or scaling (linear, log). - Desired titles, axis labels, and annotations.
  5. Special processing rules - Required calibrations or unit conversions. - Masking rules for invalid ranges or quality flags. - Any filtering or smoothing applied before plotting.