.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_tutorials/03_quick_start.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_tutorials_03_quick_start.py: 03. Quick Start =============== This quick start gives the smallest runnable example of CaliBrain's central object: a pre-calibration empirical coverage curve. It stays intentionally simple. The goal is to show the core idea in a few lines, then point to the later tutorials that explain each workflow stage in full. .. GENERATED FROM PYTHON SOURCE LINES 16-30 What this quick start shows --------------------------- CaliBrain asks whether posterior uncertainty is empirically calibrated. In the full workflow, that question is answered after: 1. simulating sources and sensors, 2. estimating a posterior mean and covariance, 3. converting that posterior summary into an uncertainty representation, 4. comparing nominal and empirical coverage. This quick start jumps directly to step 4 using a lightweight synthetic fixed- orientation example. .. GENERATED FROM PYTHON SOURCE LINES 30-40 .. code-block:: Python import matplotlib.pyplot as plt import numpy as np from calibrain import UncertaintyEstimator RANDOM_SEED = 7 rng = np.random.default_rng(RANDOM_SEED) .. GENERATED FROM PYTHON SOURCE LINES 41-47 Step 1: define a minimal fixed-orientation source example --------------------------------------------------------- The source matrix has shape ``(n_sources, n_times)``. Most sources are zero; a small subset contains ERP-like activity. The full simulation setup is explained in :doc:`Source Simulation `. .. GENERATED FROM PYTHON SOURCE LINES 47-57 .. code-block:: Python n_sources = 48 n_times = 80 time = np.linspace(-0.2, 0.5, n_times) x_true = np.zeros((n_sources, n_times)) active_sources = rng.choice(n_sources, size=5, replace=False) erp_waveform = np.exp(-0.5 * ((time - 0.12) / 0.045) ** 2) x_true[active_sources] = rng.normal(1.0, 0.2, size=(5, 1)) * erp_waveform .. GENERATED FROM PYTHON SOURCE LINES 58-70 Step 2: define a simple posterior summary ----------------------------------------- In real workflows, inverse solvers such as ``gamma_map_sflex`` or ``BMN`` produce posterior means and covariance estimates. Those steps are covered in :doc:`Source Estimation `. Here we use a simple synthetic posterior summary: - ``x_hat`` is the posterior mean; - ``posterior_var`` is the fixed-orientation marginal variance used by the uncertainty stage. .. GENERATED FROM PYTHON SOURCE LINES 70-78 .. code-block:: Python posterior_var = np.full(n_sources, 0.06**2) x_hat = x_true + rng.normal( loc=0.0, scale=np.sqrt(posterior_var)[:, None], size=x_true.shape, ) .. GENERATED FROM PYTHON SOURCE LINES 79-89 Step 3: compute the pre-calibration coverage curve -------------------------------------------------- ``UncertaintyEstimator`` builds the uncertainty representation that is used in the fixed-orientation workflow: aggregated marginal intervals. The aggregated method averages source time courses over time before checking whether the true source quantity lies inside the interval. The later tutorial :doc:`Uncertainty Estimation ` explains this in detail. .. GENERATED FROM PYTHON SOURCE LINES 89-101 .. code-block:: Python nominal_coverages = np.linspace(0.0, 1.0, 11) uncertainty = UncertaintyEstimator(nominal_coverages=nominal_coverages) curve = uncertainty.calibration_curve_intervals_aggregated( x_true=x_true, x_hat=x_hat, posterior_var=posterior_var, ) print("empirical coverages:", np.round(curve["empirical_coverages"], 3)) print("interval type:", curve["interval_type"]) .. rst-class:: sphx-glr-script-out .. code-block:: none empirical coverages: [0. 0.125 0.229 0.354 0.458 0.542 0.542 0.646 0.771 0.854 1. ] interval type: marginal .. GENERATED FROM PYTHON SOURCE LINES 102-107 Step 4: visualize the source example and its calibration curve -------------------------------------------------------------- The left panel shows one active source and the posterior mean. The right panel shows the resulting pre-calibration curve. .. GENERATED FROM PYTHON SOURCE LINES 107-148 .. code-block:: Python example_source = int(active_sources[0]) fig, axes = plt.subplots(1, 2, figsize=(10.0, 4.2)) axes[0].plot(time, x_true[example_source], label="x_true", linewidth=2) axes[0].plot(time, x_hat[example_source], label="x_hat", alpha=0.85) axes[0].fill_between( time, x_hat[example_source] - 1.96 * np.sqrt(posterior_var[example_source]), x_hat[example_source] + 1.96 * np.sqrt(posterior_var[example_source]), alpha=0.25, label="pointwise 95% band", ) axes[0].set( xlabel="Time", ylabel="Source amplitude", title=f"Example source {example_source}", ) axes[0].legend(loc="best") axes[0].grid(True, linestyle="--", alpha=0.35) axes[1].plot([0, 1], [0, 1], "--", color="0.5", label="perfect calibration") axes[1].plot( curve["nominal_coverages"], curve["empirical_coverages"], "o-", label="pre-calibration curve", ) axes[1].set( xlabel="Nominal coverage", ylabel="Empirical coverage", xlim=(0, 1), ylim=(0, 1), title="Aggregated marginal intervals", ) axes[1].set_aspect("equal", adjustable="box") axes[1].grid(True, linestyle="--", alpha=0.4) axes[1].legend(loc="best") fig.tight_layout() .. image-sg:: /auto_tutorials/images/sphx_glr_03_quick_start_001.png :alt: Example source 28, Aggregated marginal intervals :srcset: /auto_tutorials/images/sphx_glr_03_quick_start_001.png :class: sphx-glr-single-img .. GENERATED FROM PYTHON SOURCE LINES 149-160 What to read next ----------------- This quick start shows only the smallest runnable coverage example. The later tutorials unpack each stage of the actual workflow: - :doc:`Source Simulation ` - :doc:`Source Estimation ` - :doc:`Uncertainty Estimation ` - :doc:`Calibration Methods ` - :doc:`End-to-End Workflow ` .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.230 seconds) .. _sphx_glr_download_auto_tutorials_03_quick_start.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: 03_quick_start.ipynb <03_quick_start.ipynb>` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: 03_quick_start.py <03_quick_start.py>` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: 03_quick_start.zip <03_quick_start.zip>`