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 :class:`~bioniumx.spectra.transmission.TransmissionSpectrum`. It automatically handles masking, error propagation, and physical metadata.

.. code-block:: python

    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.

.. code-block:: python

    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.

.. code-block:: python

    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.

.. code-block:: python

    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.

.. code-block:: python

    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)