mib-extractor 0.2.0

CLI tool to archive Mission Information Bases (MIB), inspect SPIDs, and build serializable SPID parameter maps.

MIB Extractor

mib-extractor is a CLI tool to archive Mission Information Bases (MIB), inspect SPIDs, and generate serializable SPID parameter maps (pickle or parquet).

Quick Start

# 1) Add a MIB folder to the local archive
mib-extractor add /path/to/mib_folder --code mission-2-5

# 2) Inspect available SPIDs
mib-extractor spids mission-2-5

# 3) Build a serializable SPID map
mib-extractor build-spid-map mission-2-5 \
  --spid 1001,1002 \
  --output ./out/spid_map.pkl \
  --format pickle \
  --date-zero 2025-01-01T00:00:00Z

Installation

1. Clone and enter the project

git clone <your-repo-url>
cd mib-extractor

2. Install dependencies

Using Poetry:

poetry install

Or using the local virtual environment:

python -m venv venv
source venv/bin/activate
pip install -e .

Optional dependency: spicepy

spicepy is optional. If installed, SCET conversion uses SPICE. If not installed, the tool falls back to CLI-provided --date-zero.

With Poetry (optional extra):

poetry add "spicepy>=1.0.5,<2.0.0" --optional

Or pip:

pip install "spicepy>=1.0.5,<2.0.0"

CLI Overview

Check available commands:

mib-extractor --help

Main commands:

• add <mib_path> [--code CODE]
• list
• remove <code>
• rename <code> <new_code>
• spids <code> [--filter WORD]...
• spid <code> <spid_number>
• build-spid-map <code> --spid ... --output <file> --format parquet|pickle --date-zero <ISO-UTC>
• build-command-map <code> --apid <tc_apid> --output <file> --format parquet|pickle

Examples

Add a MIB folder:

mib-extractor add /path/to/mib_folder

List archived MIBs:

mib-extractor list

List SPIDs (with filter):

mib-extractor spids mission-2-5 --filter science --filter housekeeping

Build SPID map as pickle:

mib-extractor build-spid-map mission-2-5 \
  --spid 1001 --spid 1002 \
  --output ./out/spid_map.pkl \
  --format pickle \
  --date-zero 2025-01-01T00:00:00Z

Build command map (CCF + CDF) as pickle:

mib-extractor build-command-map mission-2-5 \
  --apid 42 \
  --output ./out/command_map.pkl \
  --format pickle

Build SPID map as parquet:

mib-extractor build-spid-map mission-2-5 \
  --spid 1001,1002,1003 \
  --output ./out/spid_map.parquet \
  --format parquet \
  --date-zero 2025-01-01T00:00:00Z

Output File Structure (pickle / parquet)

Both formats store the same tabular structure (pandas.DataFrame):

Core columns:

• SPID
• DESCR
• NAME
• OFFBY
• OFFBI
• WIDTH
• UNIT
• CATEG
• CURTX
• NATUR
• PTC
• PFC

SCET metadata columns (only for SCET-like rows, PTC=9, PFC=17):

• SCET_MODE (spicepy or date_zero_fallback)
• SCET_ZERO_UTC

For command maps (build-command-map), output rows come from CCF + CDF join and include command-level fields (CNAME, APID, TYPE, STYPE, ...), plus command-parameter fields (ELTYPE, ELLEN, BIT, PNAME, INTER, ...).

Loading pickle/parquet and Building ParamDef Objects

Use mib_extractor.paramdef_loader.dataframe_to_paramdefs to convert a DataFrame into a list[ParamDef].

Example: from pickle

import pandas as pd
from mib_extractor.paramdef_loader import dataframe_to_paramdefs

# Load full table
spid_table = pd.read_pickle("./out/spid_map.pkl")

# Select one SPID and convert to ParamDef list
spid_1002_df = spid_table.query("SPID == 1002")
params = dataframe_to_paramdefs(spid_1002_df)

print(type(params), len(params))
print(params[0])

Example: from parquet

import pandas as pd
from mib_extractor.paramdef_loader import dataframe_to_paramdefs

spid_table = pd.read_parquet("./out/spid_map.parquet")
spid_1001_df = spid_table[spid_table["SPID"] == 1001]
params = dataframe_to_paramdefs(spid_1001_df)

for p in params[:3]:
    print(p.mnemonic, p.byte_location, p.bit_location, p.build_unpack_format())

Using ParamDef list at runtime

# Example snippet
for param in params:
    fmt = param.build_unpack_format()
    # value = param.extract(bitstream, fmt)  # requires a BitStream-like object
    # param.calibrate()

Telecommand Object Model

The package now includes typed telecommand classes:

• Telecommand (src/mib_extractor/telecommand_definition.py)
• TelecommandParameter (src/mib_extractor/telecommand_definition.py)

Both classes expose runtime fields:

• value
• calibrated

and runtime methods equivalent to ParamDef:

• calibrate()
• reset_runtime()

Build object graphs from command-map DataFrames:

import pandas as pd
from mib_extractor.telecommand_loader import dataframe_to_telecommands

command_table = pd.read_pickle("./out/command_map.pkl")
commands = dataframe_to_telecommands(command_table)

cmd = commands[0]
print(cmd.command_name, cmd.apid, len(cmd.parameters))
print(cmd.parameters[0].parameter_name)

Or build objects directly from a MIB folder/APID:

from pathlib import Path
from mib_extractor.build_command_map import build_telecommands_from_mib

commands = build_telecommands_from_mib(
  mib_folder=Path("/path/to/mib"),
  apid=42,
)

Notes

• Code arguments in CLI commands support unique prefixes.
• If a code prefix is ambiguous, CLI returns an error with possible matches.
• Archive data is stored under .mib_archive/ in the current working directory.

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See the LICENSE file for details.

How to Cite

If you use this software in scientific work, please cite:

• MIB Extractor (v0.2.0), DOI: https://doi.org/10.5281/zenodo.18798971

Citation metadata is available in CITATION.cff.