Quickstart

This guide covers the basic workflow of analyzing an exoplanetary transmission spectrum using Bionium-X.

1. Loading a Spectrum

The core data structure is the TransmissionSpectrum. It automatically handles masking, error propagation, and physical metadata.

import numpy as np
from bioniumx.spectra import TransmissionSpectrum

# Simulated observational data (e.g., from JWST)
wl_obs = np.linspace(1.0, 5.0, 500)
depth_obs = 0.015 + 1e-4 * np.random.randn(500)
err_obs = 1e-5 * np.ones(500)

spec = TransmissionSpectrum(
    wavelength=wl_obs,
    transit_depth=depth_obs,
    err=err_obs,
    target_name="K2-18 b"
)

2. Preprocessing

Observational data is often noisy. You can apply rigorous smoothing algorithms from the bioniumx.preprocessing module.

from bioniumx.preprocessing import savitzky_golay

# Smooth the observational noise
spec_smoothed = savitzky_golay(spec, window=11, polyorder=3)

3. Cross-Correlation Detection

To detect specific molecules, we cross-correlate the smoothed observational spectrum with theoretical templates generated by our catalog.

from bioniumx.detection import cross_correlate_template
from bioniumx.molecules import get_template

# Fetch theoretical templates
wl_h2o, depth_h2o = get_template("H2O", resolving_power=100)
wl_ch4, depth_ch4 = get_template("CH4", resolving_power=100)

# Run detection
result_h2o = cross_correlate_template(spec_smoothed, wl_h2o, depth_h2o)

print(f"H2O Detection Significance: {result_h2o['significance']:.1f} sigma")

4. Assessing Habitability

A chemical detection must be placed into physical context. Bionium-X calculates heuristic habitability scores based on planetary radius and equilibrium temperature.

from bioniumx.physics import habitability_score

# Check planetary physics limits (e.g., T_eq = 265 K, R = 2.6 R_earth)
score = habitability_score(T_eq=265.0, radius_Rearth=2.6)

if score < 0.3:
    print("Warning: Planet is likely a non-rocky world.")

5. AI Inference (Optional)

If you installed the library with [ml], you can instantly infer the presence of multiple molecules using the pre-trained 1D CNN.

from bioniumx.models.cnn1d import BiosignatureCNN
from bioniumx.models.fetch import fetch_model

# Automatically download/cache model weights
weights_path = fetch_model("cnn_model.pth")

cnn = BiosignatureCNN(in_channels=1, num_classes=5)
cnn.load_weights(weights_path)

# Assuming preprocessed_flux is an array of length 256
probabilities = cnn.predict(preprocessed_flux)
print(probabilities)