fused_chaos_index.tier1

Tier-1 helper utilities for catalog processing and scoring.

Overview

Tier-1 commands provide essential preprocessing and evaluation tools:

• extract_radec - Extract RA/Dec coordinates from FITS catalogs
• add_quantum_mass - Compute quantum mass from k-NN graph eigenvectors
• score_single - Score individual predictions against ground truth
• score_frontier - Evaluate frontier evidence suite predictions

Use Cases

Extract Coordinates from FITS

from fused_chaos_index.tier1.extract_radec import extract_radec_to_npz

# Extract RA/Dec from a FITS catalog
result = extract_radec_to_npz(
    catalog="catalog.fits",
    out_npz="catalog_radec.npz",
    ra_col="RA",
    dec_col="DEC",
)

Add Quantum Mass

Quantum mass is derived from eigenvector localization properties of the k-NN graph:

from fused_chaos_index.tier1.add_quantum_mass import add_quantum_mass_to_catalog_npz

# Compute quantum mass from positions
result = add_quantum_mass_to_catalog_npz(
    catalog_npz="catalog.npz",
    out_npz="catalog_with_qm.npz",
    k=10,
    n_modes=10,
    threshold=5e-7,
)

Scoring

Evaluate predictions against artifacts:

from fused_chaos_index.tier1.score_single import score_single_artifact
from pathlib import Path

# Score a single prediction
score_result = score_single_artifact(
    prediction_card_json=Path("prediction.json"),
    artifact_json=Path("artifact.json"),
)

print(f"Status: {score_result['status']}")

API Reference

fused_chaos_index.tier1

add_quantum_mass_to_catalog_npz(*, catalog_npz, out_npz, k=10, n_modes=10, threshold=5e-07, force=False)

Add quantum_mass (and eigenvalues) to a local NPZ catalog.

Offline-first: - No network access - Inputs are local .npz artifacts

Inputs: - Either positions (N×D) must exist, OR both ra and dec (degrees).

Outputs: - Writes an output NPZ containing all original keys plus: - quantum_mass (N,) - eigenvalues (n_modes,) - dark_percent (computed from threshold for convenience) - Writes a JSON manifest alongside the output NPZ.

extract_radec_to_npz(*, catalog_path, out_npz, ra_col=None, dec_col=None, max_rows=0)

Extract RA/Dec columns from an Astropy-readable catalog into a compressed NPZ.

Requires optional dependency: astropy.