IMAP-Science-Operations-Center · tech3371 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 10, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -43,4 +43,4 @@ repos:
     hooks:
       - id: mypy
         exclude: .*(tests|docs).*
-        additional_dependencies: [ numpy==1.26.4 ]
+        additional_dependencies: [ numpy==2.3.5 ]
diff --git a/docs/source/code-documentation/cdf.rst → ...urce/algorithm-code-documentation/cdf.rst b/docs/source/code-documentation/cdf.rst → ...urce/algorithm-code-documentation/cdf.rst
diff --git a/docs/source/code-documentation/codice.rst → ...e/algorithm-code-documentation/codice.rst b/docs/source/code-documentation/codice.rst → ...e/algorithm-code-documentation/codice.rst
diff --git a/docs/source/code-documentation/glows.rst → ...ce/algorithm-code-documentation/glows.rst b/docs/source/code-documentation/glows.rst → ...ce/algorithm-code-documentation/glows.rst
diff --git a/docs/source/code-documentation/hi.rst → ...ource/algorithm-code-documentation/hi.rst b/docs/source/code-documentation/hi.rst → ...ource/algorithm-code-documentation/hi.rst
diff --git a/docs/source/code-documentation/hit.rst → ...urce/algorithm-code-documentation/hit.rst b/docs/source/code-documentation/hit.rst → ...urce/algorithm-code-documentation/hit.rst
diff --git a/docs/source/code-documentation/idex.rst → ...rce/algorithm-code-documentation/idex.rst b/docs/source/code-documentation/idex.rst → ...rce/algorithm-code-documentation/idex.rst
diff --git a/docs/source/code-documentation/index.rst → ...ce/algorithm-code-documentation/index.rst b/docs/source/code-documentation/index.rst → ...ce/algorithm-code-documentation/index.rst
@@ -1,7 +1,7 @@
-.. _code-documentation:
+.. _algorithm-code-documentation:
 
-Code Documentation
-==================
+Algorithm Code Documentation
+============================
 
 .. currentmodule:: imap_processing
 
@@ -15,7 +15,6 @@ Instruments
 .. toctree::
    :maxdepth: 1
 
-   cli
    codice
    glows
    hi
@@ -26,6 +25,7 @@ Instruments
    swapi
    swe
    ultra
+   quicklooks
 
 Utilities
 ---------
@@ -62,12 +62,4 @@ variable ``IMAP_DATA_DIR``. For example to use a temporary directory
 
       imap_cli --instrument codice --level 1 --data-dir /tmp/imap-data
       # or equivalently with an environment variable
-      IMAP_DATA_DIR=/tmp/imap-data imap_cli --instrument codice --level 1
-
-Tools
------
-
-.. toctree::
-   :maxdepth: 2
-
-   tools/index
+      IMAP_DATA_DIR=/tmp/imap-data imap_cli --instrument codice --level 1
diff --git a/docs/source/code-documentation/lo.rst → ...ource/algorithm-code-documentation/lo.rst b/docs/source/code-documentation/lo.rst → ...ource/algorithm-code-documentation/lo.rst
diff --git a/docs/source/code-documentation/mag.rst → ...urce/algorithm-code-documentation/mag.rst b/docs/source/code-documentation/mag.rst → ...urce/algorithm-code-documentation/mag.rst
diff --git a/docs/source/algorithm-code-documentation/quicklooks.rst b/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.
diff --git a/docs/source/code-documentation/spice.rst → ...ce/algorithm-code-documentation/spice.rst b/docs/source/code-documentation/spice.rst → ...ce/algorithm-code-documentation/spice.rst
diff --git a/docs/source/code-documentation/swapi.rst → ...ce/algorithm-code-documentation/swapi.rst b/docs/source/code-documentation/swapi.rst → ...ce/algorithm-code-documentation/swapi.rst
diff --git a/docs/source/code-documentation/swe.rst → ...urce/algorithm-code-documentation/swe.rst b/docs/source/code-documentation/swe.rst → ...urce/algorithm-code-documentation/swe.rst
diff --git a/docs/source/code-documentation/ultra.rst → ...ce/algorithm-code-documentation/ultra.rst b/docs/source/code-documentation/ultra.rst → ...ce/algorithm-code-documentation/ultra.rst
diff --git a/...e/external-tools/cdf/cdf_introduction.rst → .../source/cdf-metadata/cdf_introduction.rst b/...e/external-tools/cdf/cdf_introduction.rst → .../source/cdf-metadata/cdf_introduction.rst
@@ -32,7 +32,7 @@ The internal format of CDF files are described in the `cdf specification <https:
 Variables
 ---------
 
-.. image:: ../../_static/cdf_variables.png
+.. image:: ../_static/cdf_variables.png
 
 
 Variables are the data stored within a file.  They have a few key characteristics -

diff --git a/...e/external-tools/cdf/cdf_requirements.rst → .../source/cdf-metadata/cdf_requirements.rst b/...e/external-tools/cdf/cdf_requirements.rst → .../source/cdf-metadata/cdf_requirements.rst
diff --git a/...e/external-tools/cdf/cdf_verification.rst → .../source/cdf-metadata/cdf_verification.rst b/...e/external-tools/cdf/cdf_verification.rst → .../source/cdf-metadata/cdf_verification.rst
diff --git a/docs/source/external-tools/cdf/index.rst → docs/source/cdf-metadata/index.rst b/docs/source/external-tools/cdf/index.rst → docs/source/cdf-metadata/index.rst
@@ -1,5 +1,5 @@
-CDFs
-====
+CDF Metadata
+============
 
 These pages describe CDF files, tools for using CDF files, and SPDF requirements for archiving.
 

diff --git a/docs/source/code-documentation/cli.rst b/docs/source/code-documentation/cli.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -81,7 +81,7 @@
 
 intersphinx_mapping = {
     "numpy": ("https://numpy.org/doc/stable/", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
     "pytest": ("https://pytest.org/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
@@ -106,6 +106,7 @@
     (r"py:.*", r".*space_packet_parser.*"),
     (r"py:.*", r".*CoDICECompression.*"),
     (r"py:.*", r".*SegmentedPacketOrder.*"),
+    (r"py:.*", r".*codice.utils.*"),
     (r"py:.*", r".*RectangularSkyMap.*"),
     (r"py:.*", r".*AbstractSkyMap.*"),
     (r"py:.*", r".*MapDescriptor.*"),
@@ -122,6 +123,8 @@
     (r"py:.*", r".*np.ndarray.*"),
     (r"py:.*", r".*numpy._typing._array_like._ScalarType_co.*"),
     (r"py:.*", r".*idex.l1a.TRIGGER_DESCRIPTION.*"),
+    (r"py:.*", r".*idex.l1b.TriggerOrigin.*"),
+    (r"py:.*", r".*idex.l1b.EventMessage.*"),
     (r"py:.*", r".*idex.l2a.BaselineNoiseTime.*"),
     (r"py:.*", r".*PacketProperties"),
     (r"py:.*", r".*.spice.geometry.SpiceBody.*"),