API Reference

Reference for the main programmatic entry points exposed by SNID SAGE. This page focuses on the stable, commonly used interfaces rather than every internal helper.

Overview

SNID SAGE provides a Python API for: - Spectrum analysis and classification - Template management and matching - Data preprocessing and validation - Result processing and export - Workflow automation and customization

First Analysis

Basic Usage

from snid_sage.snid.snid import run_snid, preprocess_spectrum, run_snid_analysis
from snid_sage.snid.io import read_spectrum

# Method 1: Full pipeline
result, trace = run_snid(
    spectrum_path="spectrum.dat",
    templates_dir="templates/",
    output_dir="results/"
)

# Method 2: Step-by-step
# Preprocess spectrum
processed_spectrum, trace = preprocess_spectrum(
    spectrum_path="spectrum.dat",
    aband_remove=True,
    skyclip=True
)

# Run analysis
result, analysis_trace = run_snid_analysis(
    processed_spectrum,
    templates_dir="templates/",
    zmin=-0.01,
    zmax=1.0
)

# Access results
print(f"Type: {result.consensus_type}")
print(f"Redshift: {result.redshift}")
print(f"Confidence: {getattr(result, 'hsigma_lap_ccc', None)}")

Core Functions

run_snid()

Main function for complete SNID analysis pipeline.

def run_snid(
    spectrum_path: str,
    templates_dir: str,
    *,
    # Preprocessing options
    preprocessed_spectrum: Optional[Tuple[np.ndarray, np.ndarray]] = None,
    skip_preprocessing_steps: Optional[List[str]] = None,
    savgol_window: int = 0,
    savgol_fwhm: float = 0.0,
    savgol_order: int = 3,
    aband_remove: bool = False,
    skyclip: bool = False,
    emclip_z: float = -1.0,
    emwidth: float = 40.0,
    wavelength_masks: Optional[List[Tuple[float, float]]] = None,
    apodize_percent: float = 10.0,
    # Analysis parameters
    zmin: float = -0.01,
    zmax: float = 1.0,
    age_range: Optional[Tuple[float, float]] = None,
    type_filter: Optional[List[str]] = None,
    template_filter: Optional[List[str]] = None,
    exclude_templates: Optional[List[str]] = None,
    forced_redshift: Optional[float] = None,
    lapmin: float = 0.3,
    hsigma_lap_ccc_threshold: float = 1.5,
    # Output options
    output_dir: Optional[str] = None,
    output_main: bool = False,
    output_fluxed: bool = False,
    output_flattened: bool = False,
    output_correlation: bool = False,
    output_plots: bool = False,
    plot_types: Optional[List[str]] = None,
    max_output_templates: int = 5,
    max_plot_templates: int = 20,
    plot_figsize: Tuple[int, int] = (10, 8),
    plot_dpi: int = 150,
    verbose: bool = False,
    # Plotting options
    show_plots: bool = True,
    save_plots: bool = False,
    plot_dir: Optional[str] = None,
    # Profile selection
    profile_id: Optional[str] = None
) -> Tuple[SNIDResult, Dict[str, Any]]

Parameters:

Name Type Default Description
spectrum_path str — Path to input spectrum file
templates_dir str — Path to template library directory
preprocessed_spectrum tuple or None None Pre-processed (wave, flux) arrays to skip preprocessing
skip_preprocessing_steps list or None None Specific preprocessing steps to skip
savgol_window int 0 Savitzky–Golay filter window size (0 = no filtering)
savgol_fwhm float 0.0 Savitzky–Golay FWHM in Å (alternative to window size)
savgol_order int 3 Savitzky–Golay polynomial order
aband_remove bool False Remove telluric A-band
skyclip bool False Clip sky emission lines
emclip_z float -1.0 Redshift for emission line clipping (-1 to disable)
emwidth float 40.0 Width for emission line clipping (Å)
wavelength_masks list or None None Wavelength ranges to mask
apodize_percent float 10.0 Percentage of spectrum ends to apodize
zmin float -0.01 Minimum redshift to search
zmax float 1.0 Maximum redshift to search
age_range tuple or None None Age range filter for templates
type_filter list or None None Supernova types to include
template_filter list or None None Specific templates to use
exclude_templates list or None None Templates to exclude
forced_redshift float or None None Force analysis at specific redshift
lapmin float 0.3 Minimum overlap fraction
hsigma_lap_ccc_threshold float 1.5 Threshold for clustering quality (HσLAP-CCC: (height × lap × CCC) / sqrt(sigma_z))
output_dir str or None None Directory for output files
output_main bool False Generate main output file
output_fluxed bool False Generate fluxed spectrum file
output_flattened bool False Generate flattened spectrum file
output_correlation bool False Generate correlation files
output_plots bool False Generate plots
plot_types list or None None Types of plots to generate
max_output_templates int 5 Maximum templates in output
max_plot_templates int 20 Maximum templates to plot
plot_figsize tuple (10, 8) Figure size for plots
plot_dpi int 150 DPI for saved plots
verbose bool False Print detailed information
show_plots bool True Display plots
save_plots bool False Save plots to files
plot_dir str or None None Directory for saved plots
profile_id str or None None Analysis profile selection (optical or onir)

Returns: - SNIDResult: Analysis results object - trace (dict): Processing trace for debugging

preprocess_spectrum()

Preprocess a spectrum for SNID analysis.

def preprocess_spectrum(
    spectrum_path: Optional[str] = None,
    input_spectrum: Optional[Tuple[np.ndarray, np.ndarray]] = None,
    *,
    # Preprocessing options
    spike_masking: bool = True,
    spike_floor_z: float = 50.0,
    spike_baseline_window: int = 501,
    spike_baseline_width: float | None = None,
    spike_rel_edge_ratio: float = 2.0,
    spike_min_separation: int = 2,
    spike_max_removals: Optional[int] = None,
    spike_min_abs_resid: Optional[float] = None,
    savgol_window: int = 0,
    savgol_fwhm: float = 0.0,
    savgol_order: int = 3,
    aband_remove: bool = False,
    skyclip: bool = False,
    emclip_z: float = -1.0,
    emwidth: float = 40.0,
    wavelength_masks: Optional[List[Tuple[float, float]]] = None,
    apodize_percent: float = 10.0,
    skip_steps: Optional[List[str]] = None,
    verbose: bool = False,
    # Grid handling
    clip_to_grid: bool = True,
    grid_min_wave: Optional[float] = None,
    grid_max_wave: Optional[float] = None,
    min_overlap_angstrom: float = 2000.0,
    profile_id: Optional[str] = None,
) -> Tuple[Dict[str, np.ndarray], Dict[str, Any]]

Parameters:

Name Type Default Description
spectrum_path str or None None Path to spectrum file
input_spectrum tuple or None None (wavelength, flux) arrays
spike_masking bool True Enable early spike masking
spike_floor_z float 50.0 Floor-relative robust z for outlier detection
spike_baseline_window int 501 Running median window (pixels)
spike_baseline_width float or None None Baseline width in wavelength units
spike_rel_edge_ratio float 2.0 Center residual vs neighbors ratio
spike_min_separation int 2 Minimum pixel separation between spikes
spike_max_removals int or None None Cap on number of removed spikes
spike_min_abs_resid float or None None Minimum absolute residual amplitude
savgol_window int 0 Savitzky–Golay window (0 disables)
savgol_fwhm float 0.0 Savitzky–Golay FWHM in Å
savgol_order int 3 Savitzky–Golay polynomial order
aband_remove bool False Remove telluric A-band
skyclip bool False Clip sky emission lines
emclip_z float -1.0 Redshift for emission line clipping (-1 disables)
emwidth float 40.0 Emission clipping width (Å)
wavelength_masks list or None None Wavelength ranges to mask
apodize_percent float 10.0 Percentage to apodize
skip_steps list or None None Preprocessing steps to skip
verbose bool False Print detailed information
clip_to_grid bool True Clip to standard analysis grid
grid_min_wave float or None None Minimum wavelength for grid clipping
grid_max_wave float or None None Maximum wavelength for grid clipping
min_overlap_angstrom float 2000.0 Minimum wavelength overlap required (Å)
profile_id str or None None Active analysis profile (optical or onir)

Returns: - processed_spectrum (dict): Processed spectrum data - 'input_spectrum': Original input - 'log_wave': Log-rebinned wavelength - 'log_flux': Log-rebinned flux - 'flat_flux': Flattened flux - 'tapered_flux': Apodized flux - 'continuum': Fitted continuum - 'nonzero_mask': Valid data region - 'left_edge': Left edge index - 'right_edge': Right edge index - 'grid_params': Grid parameters - trace (dict): Processing trace

run_snid_analysis()

Run SNID analysis on preprocessed spectrum.

def run_snid_analysis(
    processed_spectrum: Dict[str, np.ndarray],
    templates_dir: str,
    *,
    zmin: float = -0.01,
    zmax: float = 1.0,
    age_range: Optional[Tuple[float, float]] = None,
    type_filter: Optional[List[str]] = None,
    template_filter: Optional[List[str]] = None,
    exclude_templates: Optional[List[str]] = None,
    preloaded_templates: Optional[List[Dict[str, Any]]] = None,
    peak_window_size: int = 10,
    phase1_peak_min_height: float = 0.3,
    phase1_peak_min_distance: int = 3,
    lapmin: float = 0.3,
    hsigma_lap_ccc_threshold: float = 1.5,
    forced_redshift: Optional[float] = None,
    max_output_templates: int = 5,
    verbose: bool = False,
    show_plots: bool = True,
    save_plots: bool = False,
    plot_dir: Optional[str | Path] = None,
    progress_callback: Optional[Callable[[str, float], None]] = None,
    gmm_model_selection: Optional[str] = None,
    profile_id: Optional[str] = None,
) -> Tuple[SNIDResult, Dict[str, Any]]

Parameters:

Name Type Default Description
processed_spectrum dict — Preprocessed spectrum from preprocess_spectrum()
templates_dir str — Path to template library
zmin float -0.01 Minimum redshift
zmax float 1.0 Maximum redshift
age_range tuple or None None Age range filter
type_filter list or None None Type filter
template_filter list or None None Template name filter
exclude_templates list or None None Templates to exclude
preloaded_templates list or None None Optional preloaded templates for reuse/performance
peak_window_size int 10 Peak-refinement search radius
phase1_peak_min_height float 0.3 Minimum normalized phase-1 peak height
phase1_peak_min_distance int 3 Minimum distance between phase-1 peaks in bins
forced_redshift float or None None Force specific redshift
lapmin float 0.3 Minimum overlap
hsigma_lap_ccc_threshold float 1.5 Threshold for clustering quality (HσLAP-CCC: (height × lap × CCC) / sqrt(sigma_z))
max_output_templates int 5 Maximum output templates
verbose bool False Verbose output
show_plots bool True Show plots
save_plots bool False Save plots
plot_dir str or None None Plot directory
progress_callback callable or None None Progress callback
gmm_model_selection str or None None Optional GMM model-selection override
profile_id str or None None Active analysis profile (optical or onir)

Returns: - SNIDResult: Analysis results - trace (dict): Analysis trace

Result Classes

SNIDResult

Class containing SNID analysis results.

Canonical definition / import

SNIDResult is defined in the SNID pipeline and re-exported for stable imports:

from snid_sage.snid import SNIDResult

Note: SNIDResult is not provided by snid_sage.shared.types.

Properties

  • success (bool): Whether analysis succeeded
  • spectrum_name (str): Input spectrum name
  • template_name (str): Best matching template
  • template_type (str): Best template type
  • template_subtype (str): Best template subtype
  • consensus_type (str): Consensus classification
  • best_subtype (str): Best subtype
  • redshift (float): Determined redshift
  • redshift_error (float): Redshift uncertainty
  • age (float): Age from maximum light
  • age_error (float): Age uncertainty
  • hsigma_lap_ccc (float): Best HσLAP-CCC value (when available)
  • lap (float): Best overlap fraction
  • runtime_sec (float): Analysis runtime
  • best_matches (list): List of best template matches
  • filtered_matches (list): Filtered matches above threshold
  • all_correlations (list): All correlation results
  • type_fractions (dict): Fraction of each type
  • subtype_fractions (dict): Fraction of each subtype
  • clustering_results (dict): GMM clustering results
  • processed_spectrum (dict): Processed spectrum data

Notes

  • SNIDResult is a dataclass-style result container defined in snid_sage.snid.snidtype.
  • It provides a human-readable __str__() representation, but it does not currently expose documented get_summary() or to_dict() methods.

I/O Functions

read_spectrum()

Read spectrum from file.

def read_spectrum(filename: str, apodize: bool = False) -> Tuple[np.ndarray, np.ndarray]

Parameters:

Name Type Default Description
filename str — Path to spectrum file
apodize bool False Whether to apodize the spectrum

Returns: - wavelength (np.ndarray): Wavelength array - flux (np.ndarray): Flux array

Supported formats: - ASCII text files (.dat, .txt, .ascii, .asci, .csv, .flm) - FITS files (.fits, .fit)

load_templates()

Load template library.

def load_templates(
    template_dir: str,
    flatten: bool = True
) -> Tuple[List[Dict[str, Any]], Dict[str, int]]

Parameters:

Name Type Default Description
template_dir str — Template directory
flatten bool True Whether to flatten templates

Returns: - templates (list): List of template dictionaries - type_counts (dict): Counts of templates by type

write_result()

Write analysis results to file.

def write_result(
    result: SNIDResult,
    filename: str
) -> None

Parameters:

Name Type Default Description
result SNIDResult — Analysis results
filename str — Output filename

Plotting Functions

plot_correlation_function()

Plot correlation function.

def plot_correlation_function(
    result: Any,
    figsize: Tuple[int, int] = (8, 6),
    save_path: Optional[str] = None,
    fig: Optional[plt.Figure] = None,
    theme_manager=None,
) -> plt.Figure

Parameters: - result (SNIDResult-like object): Result object containing best-match correlation data - figsize (tuple): Figure size (width, height) - save_path (str, optional): Path to save the figure - fig (matplotlib Figure, optional): Existing figure to draw into - theme_manager (optional): Theme manager used by the GUI plotting layer

Returns: - matplotlib.figure.Figure: The rendered figure

Preprocessing Functions

log_rebin()

Rebin spectrum to logarithmic wavelength grid.

def log_rebin(
    wave: np.ndarray,
    flux: np.ndarray,
) -> Tuple[np.ndarray, np.ndarray]

Parameters:

Name Type Default Description
wave np.ndarray — Input wavelength
flux np.ndarray — Input flux

Returns: - log_wave (np.ndarray): Log-rebinned wavelength - log_flux (np.ndarray): Log-rebinned flux

fit_continuum()

Fit and remove continuum.

def fit_continuum(
    flux: np.ndarray,
    *,
    method: str = "spline",
    knotnum: int = 13,
    izoff: int = 0,
) -> Tuple[np.ndarray, np.ndarray]

Parameters:

Name Type Default Description
flux np.ndarray — Input flux
method str "spline" Fitting method
knotnum int 13 Number of spline knots
izoff int 0 Index offset parameter

Returns: - flat_flux (np.ndarray): Flattened flux - continuum (np.ndarray): Fitted continuum

apodize()

Apply apodization to spectrum ends.

def apodize(
    flux: np.ndarray,
    left_edge: int,
    right_edge: int,
    percent: float = 10.0
) -> np.ndarray

Parameters: - flux (np.ndarray): Input flux - left_edge (int): Left edge index - right_edge (int): Right edge index - percent (float): Percentage to apodize

Returns: - tapered_flux (np.ndarray): Apodized flux

Template Management

Template Structure

Templates are stored as HDF5 files with the following structure:

template = {
    'name': str,           # Template name
    'type': str,           # Supernova type
    'subtype': str,        # Subtype
    'age': float,          # Days from maximum
    'redshift': float,     # Template redshift
    'quality': float,      # Quality score
    'wave': np.ndarray,    # Wavelength array
    'flux': np.ndarray,    # Flux array
    'metadata': dict       # Additional metadata
}

Template Functions

add_template()

Add template to library.

def add_template(
    library_path: str,
    spectrum_file: str,
    template_info: Dict,
    force_rebin: bool = False
) -> str

Parameters: - library_path (str): Template library path - spectrum_file (str): Spectrum file to add - template_info (dict): Template metadata - force_rebin (bool): Force rebinning

Returns: - template_file (str): Added template path

get_template_info()

Get template library information.

def get_template_info(library_path: str) -> Dict

Parameters: - library_path (str): Library path

Returns: - info (dict): Library information

Merged index and user overrides (HDF5)

get_template_info() reads the unified storage index from template_index.json and, if present, merges it with the user index <User Templates Folder>/template_index.user.json. If a per-type user HDF5 file exists (e.g., <User Templates Folder>/templates_Ia.user.hdf5), templates for that type are taken exclusively from the user file and base entries for that type are ignored. This ensures that any user edits (add/rename/delete) for a type immediately take precedence across CLI and GUI without duplications.

Usage Examples

Basic Analysis

from snid_sage.snid.snid import run_snid

# Simple analysis
result, trace = run_snid(
    "spectrum.dat",
    "templates/",
    output_dir="results/"
)

print(f"Classification: {result.consensus_type}")
print(f"Redshift: {result.redshift:.4f}")
print(f"Best template: {result.template_name}")

Advanced Analysis

from snid_sage.snid.snid import preprocess_spectrum, run_snid_analysis

# Custom preprocessing
processed, _ = preprocess_spectrum(
    "spectrum.dat",
    savgol_window=11,
    aband_remove=True,
    skyclip=True,
    wavelength_masks=[(6550, 6600), (7600, 7700)]
)

# Filtered analysis
result, _ = run_snid_analysis(
    processed,
    "templates/",
    type_filter=["Ia", "Ib", "Ic"],
    age_range=(-5, 20),
    zmin=0.0,
    zmax=0.1
)

Batch Processing

from snid_sage.snid.snid import run_snid
import glob

# Process multiple spectra
spectra = glob.glob("data/*.dat")
results = []

for spectrum in spectra:
    result, _ = run_snid(
        spectrum,
        "templates/",
        output_dir=f"results/{Path(spectrum).stem}/"
    )
    results.append(result)

# Summary statistics
types = [r.consensus_type for r in results if r.success]
print(f"Processed {len(results)} spectra")
print(f"Type distribution: {Counter(types)}")

Forced Redshift Analysis

# Known redshift from host galaxy
result, _ = run_snid(
    "spectrum.dat",
    "templates/",
    forced_redshift=0.0234,
    output_dir="results/"
)

Error Handling

Common Exceptions

  • FileNotFoundError: Spectrum or template file not found
  • ValueError: Invalid parameter values
  • RuntimeError: Analysis failed
  • MemoryError: Insufficient memory for templates

Error Handling Example

try:
    result, trace = run_snid("spectrum.dat", "templates/")
except FileNotFoundError as e:
    print(f"File not found: {e}")
except ValueError as e:
    print(f"Invalid parameters: {e}")
except Exception as e:
    print(f"Analysis failed: {e}")

Note: This API reference reflects the actual implementation of SNID SAGE v1.1.0. For the latest updates, check the GitHub repository.