calab 0.1.0__tar.gz

calab-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+*.pyc

calab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Aharoni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calab-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: calab
+Version: 0.1.0
+Summary: CaLab: calcium imaging analysis tools — deconvolution and data preparation
+Project-URL: Homepage, https://github.com/miniscope/CaLab
+Project-URL: Repository, https://github.com/miniscope/CaLab
+Project-URL: Issues, https://github.com/miniscope/CaLab/issues
+Author: Daniel Aharoni
+License-Expression: MIT
+License-File: LICENSE
+Keywords: FISTA,calcium-imaging,deconvolution,neuroscience,spike-inference
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CaLab Python
+
+Calcium imaging analysis tools — deconvolution and data preparation. Python companion package for the [CaLab](https://github.com/miniscope/CaLab) tools.
+
+## Installation
+
+```bash
+pip install calab
+```
+
+## Quick Start
+
+```python
+import calab
+
+# Build a calcium kernel
+kernel = calab.build_kernel(tau_rise=0.02, tau_decay=0.4, fs=30.0)
+
+# Get AR(2) coefficients
+g1, g2, d, r = calab.tau_to_ar2(tau_rise=0.02, tau_decay=0.4, fs=30.0)
+
+# Compute Lipschitz constant for FISTA step size
+L = calab.compute_lipschitz(kernel)
+```
+
+## Deconvolution
+
+Run FISTA deconvolution matching the CaTune web app's Rust solver exactly
+(baseline estimation + lambda scaling by kernel DC gain):
+
+```python
+import numpy as np
+import calab
+
+# Load your calcium traces (n_cells x n_timepoints)
+traces = np.load("my_traces.npy")
+
+# Basic: returns non-negative activity array
+activity = calab.run_deconvolution(traces, fs=30.0, tau_r=0.02, tau_d=0.4, lam=0.01)
+
+# Full: returns activity, baseline, reconvolution, iterations, converged
+result = calab.run_deconvolution_full(traces, fs=30.0, tau_r=0.02, tau_d=0.4, lam=0.01)
+print(f"Baseline: {result.baseline}, Converged: {result.converged}")
+```
+
+> **Note:** The deconvolved output represents scaled neural activity, not discrete
+> spikes or firing rates. The signal is scaled by an unknown constant (indicator
+> expression level, optical path, etc.), so absolute values should not be
+> interpreted as spike counts.
+
+## Bandpass Filter
+
+Apply the same FFT bandpass filter used in the CaTune web app:
+
+```python
+filtered = calab.bandpass_filter(trace, tau_rise=0.02, tau_decay=0.4, fs=100.0)
+```
+
+## Using CaTune Export JSON
+
+Load parameters from a CaTune export JSON and run deconvolution:
+
+```python
+import calab
+
+# Load export params
+params = calab.load_export_params("catune-params-2025-01-15.json")
+# -> {'tau_rise': 0.02, 'tau_decay': 0.4, 'lambda_': 0.01, 'fs': 30.0, 'filter_enabled': False}
+
+# One-step pipeline: loads params, optionally filters, and deconvolves
+activity = calab.deconvolve_from_export(traces, "catune-params-2025-01-15.json")
+```
+
+## Saving Data for CaTune
+
+```python
+import calab
+
+calab.save_for_tuning(traces, fs=30.0, path="my_recording")
+# Creates my_recording.npy + my_recording_metadata.json
+# Load into CaTune browser tool via the .npy file
+```
+
+## Converting from CaImAn / Minian
+
+CaLab works with raw calcium traces extracted by any pipeline. Use
+`save_for_tuning()` to convert extracted traces into CaTune-compatible
+format. No additional dependencies are required -- users extract arrays
+with their existing pipeline tools.
+
+### CaImAn
+
+```python
+import h5py
+import calab
+
+with h5py.File("caiman_results.hdf5", "r") as f:
+    traces = f["estimates/C"][:]       # shape: (n_cells, n_timepoints)
+    fs = float(f["params/data/fr"][()])
+
+calab.save_for_tuning(traces, fs, "my_recording")
+# -> my_recording.npy + my_recording_metadata.json, ready for CaTune
+```
+
+### Minian
+
+```python
+import zarr
+import calab
+
+store = zarr.open("minian_output", mode="r")
+traces = store["C"][:]  # shape: (n_cells, n_frames)
+fs = 30.0  # user must know their frame rate
+
+calab.save_for_tuning(traces, fs, "my_recording")
+```
+
+### Then deconvolve
+
+After tuning parameters in CaTune's browser interface, export your settings
+and apply them in Python:
+
+```python
+import numpy as np
+import calab
+
+traces = np.load("my_recording.npy")
+activity = calab.deconvolve_from_export(traces, "catune-params.json")
+# activity is non-negative deconvolved neural activity (scaled by unknown constant)
+```
+
+## API Reference
+
+| Function                                                | Description                               |
+| ------------------------------------------------------- | ----------------------------------------- |
+| `build_kernel(tau_rise, tau_decay, fs)`                 | Build double-exponential calcium kernel   |
+| `tau_to_ar2(tau_rise, tau_decay, fs)`                   | Derive AR(2) coefficients from tau values |
+| `compute_lipschitz(kernel)`                             | Lipschitz constant for FISTA step size    |
+| `run_deconvolution(traces, fs, tau_r, tau_d, lam)`      | FISTA deconvolution, returns activity     |
+| `run_deconvolution_full(traces, fs, tau_r, tau_d, lam)` | Full result with baseline, reconvolution  |
+| `bandpass_filter(trace, tau_rise, tau_decay, fs)`       | FFT bandpass filter from kernel params    |
+| `save_for_tuning(traces, fs, path)`                     | Save traces for CaTune browser tool       |
+| `load_tuning_data(path)`                                | Load traces saved by save_for_tuning      |
+| `load_export_params(path)`                              | Load params from CaTune export JSON       |
+| `deconvolve_from_export(traces, params_path)`           | Full pipeline: load params + deconvolve   |

calab-0.1.0/README.md

@@ -0,0 +1,145 @@
+# CaLab Python
+
+Calcium imaging analysis tools — deconvolution and data preparation. Python companion package for the [CaLab](https://github.com/miniscope/CaLab) tools.
+
+## Installation
+
+```bash
+pip install calab
+```
+
+## Quick Start
+
+```python
+import calab
+
+# Build a calcium kernel
+kernel = calab.build_kernel(tau_rise=0.02, tau_decay=0.4, fs=30.0)
+
+# Get AR(2) coefficients
+g1, g2, d, r = calab.tau_to_ar2(tau_rise=0.02, tau_decay=0.4, fs=30.0)
+
+# Compute Lipschitz constant for FISTA step size
+L = calab.compute_lipschitz(kernel)
+```
+
+## Deconvolution
+
+Run FISTA deconvolution matching the CaTune web app's Rust solver exactly
+(baseline estimation + lambda scaling by kernel DC gain):
+
+```python
+import numpy as np
+import calab
+
+# Load your calcium traces (n_cells x n_timepoints)
+traces = np.load("my_traces.npy")
+
+# Basic: returns non-negative activity array
+activity = calab.run_deconvolution(traces, fs=30.0, tau_r=0.02, tau_d=0.4, lam=0.01)
+
+# Full: returns activity, baseline, reconvolution, iterations, converged
+result = calab.run_deconvolution_full(traces, fs=30.0, tau_r=0.02, tau_d=0.4, lam=0.01)
+print(f"Baseline: {result.baseline}, Converged: {result.converged}")
+```
+
+> **Note:** The deconvolved output represents scaled neural activity, not discrete
+> spikes or firing rates. The signal is scaled by an unknown constant (indicator
+> expression level, optical path, etc.), so absolute values should not be
+> interpreted as spike counts.
+
+## Bandpass Filter
+
+Apply the same FFT bandpass filter used in the CaTune web app:
+
+```python
+filtered = calab.bandpass_filter(trace, tau_rise=0.02, tau_decay=0.4, fs=100.0)
+```
+
+## Using CaTune Export JSON
+
+Load parameters from a CaTune export JSON and run deconvolution:
+
+```python
+import calab
+
+# Load export params
+params = calab.load_export_params("catune-params-2025-01-15.json")
+# -> {'tau_rise': 0.02, 'tau_decay': 0.4, 'lambda_': 0.01, 'fs': 30.0, 'filter_enabled': False}
+
+# One-step pipeline: loads params, optionally filters, and deconvolves
+activity = calab.deconvolve_from_export(traces, "catune-params-2025-01-15.json")
+```
+
+## Saving Data for CaTune
+
+```python
+import calab
+
+calab.save_for_tuning(traces, fs=30.0, path="my_recording")
+# Creates my_recording.npy + my_recording_metadata.json
+# Load into CaTune browser tool via the .npy file
+```
+
+## Converting from CaImAn / Minian
+
+CaLab works with raw calcium traces extracted by any pipeline. Use
+`save_for_tuning()` to convert extracted traces into CaTune-compatible
+format. No additional dependencies are required -- users extract arrays
+with their existing pipeline tools.
+
+### CaImAn
+
+```python
+import h5py
+import calab
+
+with h5py.File("caiman_results.hdf5", "r") as f:
+    traces = f["estimates/C"][:]       # shape: (n_cells, n_timepoints)
+    fs = float(f["params/data/fr"][()])
+
+calab.save_for_tuning(traces, fs, "my_recording")
+# -> my_recording.npy + my_recording_metadata.json, ready for CaTune
+```
+
+### Minian
+
+```python
+import zarr
+import calab
+
+store = zarr.open("minian_output", mode="r")
+traces = store["C"][:]  # shape: (n_cells, n_frames)
+fs = 30.0  # user must know their frame rate
+
+calab.save_for_tuning(traces, fs, "my_recording")
+```
+
+### Then deconvolve
+
+After tuning parameters in CaTune's browser interface, export your settings
+and apply them in Python:
+
+```python
+import numpy as np
+import calab
+
+traces = np.load("my_recording.npy")
+activity = calab.deconvolve_from_export(traces, "catune-params.json")
+# activity is non-negative deconvolved neural activity (scaled by unknown constant)
+```
+
+## API Reference
+
+| Function                                                | Description                               |
+| ------------------------------------------------------- | ----------------------------------------- |
+| `build_kernel(tau_rise, tau_decay, fs)`                 | Build double-exponential calcium kernel   |
+| `tau_to_ar2(tau_rise, tau_decay, fs)`                   | Derive AR(2) coefficients from tau values |
+| `compute_lipschitz(kernel)`                             | Lipschitz constant for FISTA step size    |
+| `run_deconvolution(traces, fs, tau_r, tau_d, lam)`      | FISTA deconvolution, returns activity     |
+| `run_deconvolution_full(traces, fs, tau_r, tau_d, lam)` | Full result with baseline, reconvolution  |
+| `bandpass_filter(trace, tau_rise, tau_decay, fs)`       | FFT bandpass filter from kernel params    |
+| `save_for_tuning(traces, fs, path)`                     | Save traces for CaTune browser tool       |
+| `load_tuning_data(path)`                                | Load traces saved by save_for_tuning      |
+| `load_export_params(path)`                              | Load params from CaTune export JSON       |
+| `deconvolve_from_export(traces, params_path)`           | Full pipeline: load params + deconvolve   |

calab-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "calab"
+version = "0.1.0"
+description = "CaLab: calcium imaging analysis tools — deconvolution and data preparation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Aharoni" }]
+keywords = ["calcium-imaging", "deconvolution", "neuroscience", "FISTA", "spike-inference"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.urls]
+Homepage = "https://github.com/miniscope/CaLab"
+Repository = "https://github.com/miniscope/CaLab"
+Issues = "https://github.com/miniscope/CaLab/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/calab"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

calab-0.1.0/src/calab/__init__.py

@@ -0,0 +1,21 @@
+"""CaLab: calcium imaging analysis tools — deconvolution and data preparation."""
+
+from ._kernel import build_kernel, compute_lipschitz, tau_to_ar2
+from ._fista import run_deconvolution, run_deconvolution_full, DeconvolutionResult
+from ._filter import bandpass_filter
+from ._io import load_tuning_data, save_for_tuning, load_export_params, deconvolve_from_export
+
+__version__ = "0.2.0"
+__all__ = [
+    "build_kernel",
+    "tau_to_ar2",
+    "compute_lipschitz",
+    "run_deconvolution",
+    "run_deconvolution_full",
+    "DeconvolutionResult",
+    "bandpass_filter",
+    "save_for_tuning",
+    "load_tuning_data",
+    "load_export_params",
+    "deconvolve_from_export",
+]

calab-0.1.0/src/calab/_filter.py

@@ -0,0 +1,103 @@
+"""Bandpass filter -- port of wasm/catune-solver/src/filter.rs.
+
+Pure numpy FFT-based bandpass filter derived from kernel time constants.
+Uses cosine-tapered gain curve matching Rust's implementation exactly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# Margin factors for deriving bandpass cutoffs from kernel time constants.
+# HP cutoff = 1/(2*pi*tau_decay*M_HP), LP cutoff = M_LP/(2*pi*tau_rise).
+# HP uses 16x to preserve the slow calcium decay tail.
+# LP uses 4x for tighter noise rejection above the kernel's rise band.
+_MARGIN_FACTOR_HP = 16.0
+_MARGIN_FACTOR_LP = 4.0
+
+
+def bandpass_filter(
+    trace: np.ndarray,
+    tau_rise: float,
+    tau_decay: float,
+    fs: float,
+) -> np.ndarray:
+    """Apply FFT bandpass filter derived from kernel time constants.
+
+    Cutoffs are computed from time constants (matching filter.rs:62-90):
+      - f_hp = 1 / (2*pi * tau_decay * 16)
+      - f_lp = min(4 / (2*pi * tau_rise), fs/2)
+
+    The gain curve uses cosine tapers at transitions (matching filter.rs:130-162).
+
+    Parameters
+    ----------
+    trace : np.ndarray
+        1-D calcium trace to filter.
+    tau_rise : float
+        Rise time constant in seconds.
+    tau_decay : float
+        Decay time constant in seconds.
+    fs : float
+        Sampling rate in Hz.
+
+    Returns
+    -------
+    np.ndarray
+        Filtered trace. Returns input unchanged if filter would be invalid
+        (f_hp >= f_lp) or trace is too short (< 8 samples).
+    """
+    n = len(trace)
+    if n < 8:
+        return trace.copy()
+
+    nyquist = fs / 2.0
+
+    # Compute cutoffs (matching filter.rs:62-90)
+    f_hp = 1.0 / (2.0 * np.pi * tau_decay * _MARGIN_FACTOR_HP)
+    f_lp = _MARGIN_FACTOR_LP / (2.0 * np.pi * tau_rise)
+
+    # Clamp LP to Nyquist
+    if f_lp > nyquist:
+        f_lp = nyquist
+
+    # Invalid if HP >= LP
+    if f_hp >= f_lp:
+        return trace.copy()
+
+    # Build cosine-tapered gain curve (matching filter.rs:130-162)
+    spectrum_len = n // 2 + 1
+    df = fs / n
+    freqs = np.arange(spectrum_len) * df
+
+    # Taper widths: 50% of respective cutoff frequency
+    w_hp = f_hp * 0.5
+    w_lp = f_lp * 0.5
+
+    gain = np.zeros(spectrum_len)
+    for i in range(spectrum_len):
+        f = freqs[i]
+        if f < f_hp - w_hp:
+            # Stopband (below high-pass)
+            gain[i] = 0.0
+        elif f < f_hp + w_hp:
+            # HP transition (cosine taper 0 -> 1)
+            t = (f - (f_hp - w_hp)) / (2.0 * w_hp)
+            gain[i] = 0.5 * (1.0 - np.cos(np.pi * t))
+        elif f < f_lp - w_lp:
+            # Passband
+            gain[i] = 1.0
+        elif f < f_lp + w_lp:
+            # LP transition (cosine taper 1 -> 0)
+            t = (f - (f_lp - w_lp)) / (2.0 * w_lp)
+            gain[i] = 0.5 * (1.0 + np.cos(np.pi * t))
+        else:
+            # Stopband (above low-pass)
+            gain[i] = 0.0
+
+    # Apply via rfft -> multiply -> irfft
+    spectrum = np.fft.rfft(trace)
+    spectrum *= gain
+    filtered = np.fft.irfft(spectrum, n=n)
+
+    return filtered