Add spice instructions (#299)

laspsandoval · web-flow · commit 387de0caf231 · 2026-03-26T09:56:22.000-06:00
diff --git a/README.md b/README.md
@@ -47,6 +47,27 @@ $ imap-data-access query --start-date 20240101 --end-date 20241231 --output-form
 [{'file_path': 'imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_v001.pkts', 'instrument': 'swe', 'data_level': 'l0', 'descriptor': 'sci', 'start_date': '20240105', 'version': 'v001', 'extension': 'pkts'}, {'file_path': 'imap/swe/l0/2024/01/imap_swe_l0_sci_20240105_v001.pkts', 'instrument': 'swe', 'data_level': 'l0', 'descriptor': 'sci', 'start_date': '20240105', 'version': 'v001', 'extension': 'pkts'}]
 ```
 
+Find all latest predicted ephemeris kernels
+
+```bash
+$ imap-data-access query --table spice --ingestion-start-date 20260301 --type ephemeris_predicted --version latest
+```
+
+An equivalent curl command is shown.
+```bash
+$ curl "https://api.imap-mission.com/spice-query?start_ingest_date=20260301&type=ephemeris_predicted&latest=true"
+```
+
+Download a predicted ephemeris kernel
+```bash
+$ imap-data-access download spk/imap_pred_od025_20260303_20260414_v01.bsp
+```
+
+An equivalent curl command is shown.
+```bash
+$ curl "https://api.imap-mission.com/download/imap/spice/spk/imap_pred_od025_20260303_20260414_v01.bsp" --output imap_pred_od025_20260303_20260414_v01.bsp
+```
+
 ### Download a file
 
 Download a level 0 SWE file on 2024/01/05
diff --git a/imap_data_access/__init__.py b/imap_data_access/__init__.py
@@ -18,7 +18,7 @@
     ScienceFilePath,
     SPICEFilePath,
 )
-from imap_data_access.io import download, query, reprocess, upload
+from imap_data_access.io import download, query, reprocess, spice_query, upload
 from imap_data_access.processing_input import (
     AncillaryInput,
     ProcessingInputCollection,
@@ -47,6 +47,7 @@
     "download",
     "query",
     "reprocess",
+    "spice_query",
     "upload",
 ]
 
diff --git a/imap_data_access/cli.py b/imap_data_access/cli.py
@@ -29,7 +29,7 @@
     ScienceFilePath,
     generate_imap_file_path,
 )
-from imap_data_access.io import query
+from imap_data_access.io import query, spice_query
 from imap_data_access.webpoda import download_daily_data
 
 
@@ -45,7 +45,7 @@ def _download_parser(args: argparse.Namespace):
     print(f"Successfully downloaded the file to: {output_path}")
 
 
-# ruff: noqa: PLR0912
+# ruff: noqa: PLR0912, PLR0915
 def _print_query_results_table(query_results: list[dict]):
     """Print the query results in a table.
 
@@ -62,7 +62,9 @@ def _print_query_results_table(query_results: list[dict]):
 
     # Get the database table
     query_table = ""
-    if "end_date" in query_results[0]:
+    if "kernel_type" in query_results[0]:
+        query_table = "spice"
+    elif "end_date" in query_results[0]:
         query_table = "ancillary"
     elif "repointing" in query_results[0]:
         query_table = "science"
@@ -86,6 +88,14 @@ def _print_query_results_table(query_results: list[dict]):
         "Version",
         "Filename",
     ]
+    spice_header_keys = {
+        "Kernel Type": "kernel_type",
+        "Min Date": "min_date_datetime",
+        "Max Date": "max_date_datetime",
+        "Ingestion Date": "ingestion_date",
+        "Version": "version",
+    }
+    headers_spice = [*spice_header_keys.keys(), "Filename"]
     # Boolean to check if CR is present in any science files
     cr_flag = query_table == "science" and any(
         item.get("cr") not in (None, "", []) for item in query_results
@@ -104,16 +114,22 @@ def _print_query_results_table(query_results: list[dict]):
     # Set appropriate headers for desired table
     if query_table == "science":
         headers = headers_science
+    elif query_table == "spice":
+        headers = headers_spice
     else:
         headers = headers_ancillary
 
     # Calculate the maximum width for each column based on the header and the data
     # have to adjust Ingestion Date, Filename, and CR to properly align
     column_widths = {}
     for header in headers[:-1]:
+        if query_table == "spice":
+            data_key = spice_header_keys[header]
+        else:
+            data_key = header.lower()
         column_widths[header] = max(
             len(header),
-            *(len(str(item.get(header.lower(), ""))) for item in query_results),
+            *(len(str(item.get(data_key, ""))) for item in query_results),
         )
 
         column_widths["Ingestion Date"] = max(
@@ -128,12 +144,10 @@ def _print_query_results_table(query_results: list[dict]):
                 len("CR"), *(len(str(item.get("cr", ""))) for item in query_results)
             )
 
+        file_key = "file_name" if query_table == "spice" else "file_path"
         column_widths["Filename"] = max(
             len("Filename"),
-            *(
-                len(os.path.basename(item.get("file_path", "")))
-                for item in query_results
-            ),
+            *(len(os.path.basename(item.get(file_key, ""))) for item in query_results),
         )
 
     # Create the format string dynamically based on the number of columns
@@ -153,7 +167,11 @@ def _print_query_results_table(query_results: list[dict]):
 
     # Print data
     for item in query_results:
-        if query_table == "ancillary":
+        if query_table == "spice":
+            values = [
+                str(item.get(spice_header_keys[header], "")) for header in headers[:-1]
+            ] + [str(item.get("file_name", ""))]
+        elif query_table == "ancillary":
             values = [
                 str(item.get("instrument", "")),
                 str(item.get("descriptor", "")),
@@ -210,6 +228,7 @@ def _query_parser(args: argparse.Namespace):
         "version",
         "extension",
         "filename",
+        "type",
     ]
 
     # Filter to get the arguments of interest from the namespace
@@ -262,9 +281,21 @@ def _query_parser(args: argparse.Namespace):
 
     # SPICE query table
     elif args.table == "spice":
-        raise NotImplementedError("SPICE query not implemented yet.")
+        spice_valid_args = [
+            "start_date",
+            "end_date",
+            "ingestion_start_date",
+            "ingestion_end_date",
+            "type",
+            "version",
+        ]
+        query_params = {
+            key: value for key, value in query_params.items() if key in spice_valid_args
+        }
+        query_results = spice_query(**query_params)
 
-    query_results = query(**query_params)
+    else:
+        query_results = query(**query_params)
 
     if args.output_format == "table":
         _print_query_results_table(query_results)
@@ -401,6 +432,18 @@ def add_query_args(subparser: ArgumentParser) -> None:
         "processing.readthedocs.io/en/latest/development-guide/style-guide/naming-conventions"
         ".html#data-product-file-naming-conventions",
     )
+    subparser.add_argument(
+        "--type",
+        type=str,
+        required=False,
+        help="SPICE kernel type. Only used with --table spice. "
+        "Valid types: attitude_history, attitude_predict, spin, repoint, "
+        "ephemeris_reconstructed, ephemeris_nominal, ephemeris_predicted, "
+        "ephemeris_90days, ephemeris_long, ephemeris_launch, planetary_ephemeris, "
+        "planetary_constants, leapseconds, pointing_attitude, spacecraft_clock, "
+        "imap_frames, science_frames, metakernel, thruster, lagrange_point, "
+        "earth_attitude.",
+    )
     subparser.set_defaults(func=_query_parser)
 
 
@@ -430,7 +473,7 @@ def _reprocess_parser(args: argparse.Namespace):
 
 
 # PLR0915: too many statements
-def main():  # noqa: PLR0915
+def main():
     """Parse the command line arguments.
 
     Run the command line interface to the IMAP Data Access API.
diff --git a/imap_data_access/io.py b/imap_data_access/io.py
@@ -219,6 +219,74 @@ def _validate_query_parameters(**kwargs) -> None:
             )
 
 
+def spice_query(
+    *,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    ingestion_start_date: Optional[str] = None,
+    ingestion_end_date: Optional[str] = None,
+    type: Optional[str] = None,
+    version: Optional[str] = None,
+) -> list[dict[str, str]]:
+    """Query the SPICE data archive via the /spice-query endpoint.
+
+    Parameters
+    ----------
+    start_date : str, optional
+        Start date in YYYYMMDD format.
+    end_date : str, optional
+        End date in YYYYMMDD format.
+    ingestion_start_date : str, optional
+        Ingestion start date in YYYYMMDD format.
+    ingestion_end_date : str, optional
+        Ingestion end date in YYYYMMDD format.
+    type : str, optional
+        SPICE kernel type (e.g. ``ephemeris_predicted``).
+    version : str, optional
+        Version in the format ``vXXX`` or ``latest``.
+
+    Returns
+    -------
+    list
+        List of SPICE files matching the query
+    """
+    # locals() gives us the keyword arguments passed to the function
+    # and allows us to filter out the None values
+    query_params = {key: value for key, value in locals().items() if value is not None}
+    logger.debug("Input query parameters: %s", query_params)
+
+    # removing version from query if it is 'latest',
+    # ensuring other parameters are passed
+    if version == "latest":
+        del query_params["version"]
+        if not query_params:
+            raise ValueError("One other parameter must be run with 'version'")
+        query_params["latest"] = "true"
+
+    if "type" not in query_params:
+        raise ValueError(
+            "The 'type' parameter is required for SPICE queries. "
+            "Run 'query -h' for more information."
+        )
+
+    # Remap ingestion date params to /spice-query naming convention
+    if "ingestion_start_date" in query_params:
+        query_params["start_ingest_date"] = query_params.pop("ingestion_start_date")
+    if "ingestion_end_date" in query_params:
+        query_params["end_ingest_date"] = query_params.pop("ingestion_end_date")
+
+    url = f"{_get_base_url()}/spice-query"
+    request = requests.Request(method="GET", url=url, params=query_params).prepare()
+
+    logger.info("Querying data archive for %s with url %s", query_params, request.url)
+    with _make_request(request) as response:
+        # Decode the JSON response as a list of items
+        items = response.json()
+        logger.debug("Received JSON: %s", items)
+
+    return items
+
+
 def query(
     *,
     table: Optional[str] = "science",
diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -16,6 +16,29 @@ def test_cli_works():
             cli.main()
 
 
+def test_cli_spice_query(capsys):
+    """Test the CLI SPICE query command."""
+    with mock.patch.object(
+        sys,
+        "argv",
+        [
+            "imap-data-access",
+            "query",
+            "--table",
+            "spice",
+            "--type",
+            "ephemeris_predicted",
+        ],
+    ):
+        with mock.patch(
+            "imap_data_access.cli.spice_query", return_value=[]
+        ) as mock_spice_query:
+            cli.main()
+    captured = capsys.readouterr()
+    assert "Found [0] matching files" in captured.out
+    mock_spice_query.assert_called_once_with(type="ephemeris_predicted")
+
+
 def test_cli_error_message(capsys):
     """Test the CLI error message when no arguments are passed."""
     with mock.patch.object(
diff --git a/tests/test_io.py b/tests/test_io.py
