Quicklooks doc

docs/source/algorithm-code-documentation/index.rst

@@ -25,6 +25,7 @@ Instruments
    swapi
    swe
    ultra
+   quicklooks
 
 Utilities
 ---------

docs/source/algorithm-code-documentation/quicklooks.rst

@@ -0,0 +1,154 @@
+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.