pycbas 0.1.0__tar.gz

pycbas-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Pixi
+.pixi/
+
+# MkDocs build output
+site/
+
+# Pytest
+.pytest_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Cached results (regenerable)
+**/*.npz
+
+# Reference materials (not for distribution)
+papers/
+cbas_paper_docling/
+igor_cbas/
+DanielStudentImplementation/
+utilities/
+notes/
+notes.md
+
+# Raw downloaded data (regenerable from source)
+data/noel_ibl_mice/raw/
+data/ibl_mice/raw/

pycbas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Demetris Roumis
+
+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.

pycbas-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: pycbas
+Version: 0.1.0
+Summary: Choice-Wide Behavioral Association Study — identify behavioral sequences that differ between groups or correlate with continuous measures
+Project-URL: Repository, https://github.com/droumis/pycbas
+Author: Demetris Roumis
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numba>=0.59
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: scipy>=1.11; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: bokeh>=3.3; extra == 'gui'
+Requires-Dist: holoviews>=1.18; extra == 'gui'
+Requires-Dist: pandas>=2.0; extra == 'gui'
+Requires-Dist: panel>=1.4; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# pycbas
+
+Python implementation of the [CBAS algorithm](https://github.com/dbkastner/CBAS) (Choice-Wide Behavioral Association Study) for identifying behavioral sequences that differ significantly between experimental groups or correlate with a continuous measure.
+
+Uses Romano-Wolf step-down for multiple comparison correction and k-FWER iteration for false discovery proportion control.
+
+**Reference:** Kastner et al., "Choice-Wide Behavioral Association Study" [(2026 preprint)](https://www.biorxiv.org/content/10.1101/2024.02.26.582115v4)
+
+## Interactive GUI
+
+A no-code interface for running CBAS analyses. Load data from a local folder, auto-detect parameters and analysis mode, run the pipeline, and explore results visually.
+
+```bash
+git clone https://github.com/droumis/pycbas.git
+cd pycbas
+
+# option 1: pixi (recommended)
+pixi run gui
+
+# option 2: conda/mamba + pip
+conda create -n pycbas python=3.11
+conda activate pycbas
+pip install -e ".[gui]"
+pycbas gui
+```
+
+See the [GUI documentation](https://droumis.github.io/pycbas/app/) for details.
+
+## Installation
+
+We recommend installing in a dedicated environment (conda, mamba, or pixi) rather than your base environment.
+
+```bash
+git clone https://github.com/droumis/pycbas.git
+cd pycbas
+
+# option 1: pixi (handles everything)
+pixi install
+
+# option 2: conda/mamba + pip
+conda create -n pycbas python=3.11
+conda activate pycbas
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Comparative mode (group differences)
+
+```python
+from pycbas import CBASParams, load_subject_data, run_cbas_comparative
+
+subjects_data = [load_subject_data(f) for f in data_files]
+group_labels = [0, 0, 0, 1, 1, 1]
+
+params = CBASParams(
+    num_arms=6,
+    seq_len_max=6,
+    criterion=800,
+    resample_number=10000,
+)
+
+result = run_cbas_comparative(subjects_data, group_labels, params)
+print(f"{result.n_significant} significant sequences (k={result.k_final})")
+```
+
+### Correlative mode (continuous covariate)
+
+```python
+from pycbas import run_cbas_correlative
+
+result = run_cbas_correlative(subjects_data, cbit_scores, params)
+```
+
+### Resource estimation
+
+```python
+from pycbas import estimate_resources, print_resource_estimate
+
+est = estimate_resources(num_arms=12, seq_len_max=8, n_observed=5000)
+print_resource_estimate(est)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `num_arms` | 6 | Number of base symbols (choices) |
+| `seq_len_max` | 6 | Maximum sequence length L |
+| `criterion` | 800 | Number of trials used per subject |
+| `resample_number` | 10,000 | Bootstrap resamples M |
+| `alpha` | 0.5 | Significance threshold for FDP control |
+| `gamma` | 0.05 | FDP tolerance |
+| `centering` | False | Center bootstrap null (False matches Igor) |
+| `block_aware` | False | Prevent sequences from spanning block/session boundaries |
+
+## Performance
+
+| Dataset | Subjects | Sequences | Time | Peak RAM |
+|---|---|---|---|---|
+| Flies (2-arm, L=10) | 1,566 | 2,046 | ~21s | ~560 MB |
+| Humans (6-arm, L=4) | 1,413 | 408 | ~3s | ~155 MB |
+| Rats (6-arm, L=6) | 105 | 16,378 | ~7s | ~3.6 GB |
+
+Timings on Apple M-series. The chunked pipeline (`chunked=True`, default) trades ~30% more time for ~40% less memory. Bootstrap and step-down are parallelized via numba. Set `NUMBA_DISABLE_JIT=1` to disable for debugging.
+
+## Validation
+
+Exact match with the original Igor implementation on flies (1,605/2,046, k=81) and humans (31/408, k=2). Test statistics match to floating-point precision. Rats (105 subjects, `block_aware=True`): 572/16,378 significant (k=29), exact match with David's Igor implementation. Test statistics agree within 1e-4 on all 16,376 overlapping sequences.
+
+See [results/validation_summary.md](results/validation_summary.md) for details, or per-dataset reports:
+- [Flies](results/flies/validation_report.md)
+- [Humans](results/humans/validation_report.md)
+- [Rats](results/rats/validation_report.md)
+
+## Documentation
+
+Full docs at **[droumis.github.io/pycbas](https://droumis.github.io/pycbas/)**
+
+- [User Guide](https://droumis.github.io/pycbas/guide/) - data format, parameter selection, working with results
+- [Algorithm](https://droumis.github.io/pycbas/algorithm/) - the step-down and k-FWER procedure in detail
+- [API Reference](https://droumis.github.io/pycbas/api/) - all public functions and classes
+
+## Development
+
+```bash
+pixi install          # set up environment
+pixi run test         # run tests
+pixi run flies        # run fly analysis (paper params)
+pixi run human        # run human analysis
+pixi run rats         # run rat analysis
+```
+
+## License
+
+MIT

pycbas-0.1.0/README.md

@@ -0,0 +1,136 @@
+# pycbas
+
+Python implementation of the [CBAS algorithm](https://github.com/dbkastner/CBAS) (Choice-Wide Behavioral Association Study) for identifying behavioral sequences that differ significantly between experimental groups or correlate with a continuous measure.
+
+Uses Romano-Wolf step-down for multiple comparison correction and k-FWER iteration for false discovery proportion control.
+
+**Reference:** Kastner et al., "Choice-Wide Behavioral Association Study" [(2026 preprint)](https://www.biorxiv.org/content/10.1101/2024.02.26.582115v4)
+
+## Interactive GUI
+
+A no-code interface for running CBAS analyses. Load data from a local folder, auto-detect parameters and analysis mode, run the pipeline, and explore results visually.
+
+```bash
+git clone https://github.com/droumis/pycbas.git
+cd pycbas
+
+# option 1: pixi (recommended)
+pixi run gui
+
+# option 2: conda/mamba + pip
+conda create -n pycbas python=3.11
+conda activate pycbas
+pip install -e ".[gui]"
+pycbas gui
+```
+
+See the [GUI documentation](https://droumis.github.io/pycbas/app/) for details.
+
+## Installation
+
+We recommend installing in a dedicated environment (conda, mamba, or pixi) rather than your base environment.
+
+```bash
+git clone https://github.com/droumis/pycbas.git
+cd pycbas
+
+# option 1: pixi (handles everything)
+pixi install
+
+# option 2: conda/mamba + pip
+conda create -n pycbas python=3.11
+conda activate pycbas
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+### Comparative mode (group differences)
+
+```python
+from pycbas import CBASParams, load_subject_data, run_cbas_comparative
+
+subjects_data = [load_subject_data(f) for f in data_files]
+group_labels = [0, 0, 0, 1, 1, 1]
+
+params = CBASParams(
+    num_arms=6,
+    seq_len_max=6,
+    criterion=800,
+    resample_number=10000,
+)
+
+result = run_cbas_comparative(subjects_data, group_labels, params)
+print(f"{result.n_significant} significant sequences (k={result.k_final})")
+```
+
+### Correlative mode (continuous covariate)
+
+```python
+from pycbas import run_cbas_correlative
+
+result = run_cbas_correlative(subjects_data, cbit_scores, params)
+```
+
+### Resource estimation
+
+```python
+from pycbas import estimate_resources, print_resource_estimate
+
+est = estimate_resources(num_arms=12, seq_len_max=8, n_observed=5000)
+print_resource_estimate(est)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `num_arms` | 6 | Number of base symbols (choices) |
+| `seq_len_max` | 6 | Maximum sequence length L |
+| `criterion` | 800 | Number of trials used per subject |
+| `resample_number` | 10,000 | Bootstrap resamples M |
+| `alpha` | 0.5 | Significance threshold for FDP control |
+| `gamma` | 0.05 | FDP tolerance |
+| `centering` | False | Center bootstrap null (False matches Igor) |
+| `block_aware` | False | Prevent sequences from spanning block/session boundaries |
+
+## Performance
+
+| Dataset | Subjects | Sequences | Time | Peak RAM |
+|---|---|---|---|---|
+| Flies (2-arm, L=10) | 1,566 | 2,046 | ~21s | ~560 MB |
+| Humans (6-arm, L=4) | 1,413 | 408 | ~3s | ~155 MB |
+| Rats (6-arm, L=6) | 105 | 16,378 | ~7s | ~3.6 GB |
+
+Timings on Apple M-series. The chunked pipeline (`chunked=True`, default) trades ~30% more time for ~40% less memory. Bootstrap and step-down are parallelized via numba. Set `NUMBA_DISABLE_JIT=1` to disable for debugging.
+
+## Validation
+
+Exact match with the original Igor implementation on flies (1,605/2,046, k=81) and humans (31/408, k=2). Test statistics match to floating-point precision. Rats (105 subjects, `block_aware=True`): 572/16,378 significant (k=29), exact match with David's Igor implementation. Test statistics agree within 1e-4 on all 16,376 overlapping sequences.
+
+See [results/validation_summary.md](results/validation_summary.md) for details, or per-dataset reports:
+- [Flies](results/flies/validation_report.md)
+- [Humans](results/humans/validation_report.md)
+- [Rats](results/rats/validation_report.md)
+
+## Documentation
+
+Full docs at **[droumis.github.io/pycbas](https://droumis.github.io/pycbas/)**
+
+- [User Guide](https://droumis.github.io/pycbas/guide/) - data format, parameter selection, working with results
+- [Algorithm](https://droumis.github.io/pycbas/algorithm/) - the step-down and k-FWER procedure in detail
+- [API Reference](https://droumis.github.io/pycbas/api/) - all public functions and classes
+
+## Development
+
+```bash
+pixi install          # set up environment
+pixi run test         # run tests
+pixi run flies        # run fly analysis (paper params)
+pixi run human        # run human analysis
+pixi run rats         # run rat analysis
+```
+
+## License
+
+MIT

pycbas-0.1.0/pycbas/__init__.py

@@ -0,0 +1,48 @@
+"""
+pycbas -- Choice-Wide Behavioral Association Study.
+
+A Python implementation of the CBAS algorithm for identifying behavioral
+sequences that differ between experimental groups or correlate with a
+continuous measure. Uses Romano-Wolf step-down for multiple comparison
+correction and k-FWER iteration for false discovery proportion control.
+
+Reference: Kastner et al., "Choice-Wide Behavioral Association Study"
+(2026 preprint) https://www.biorxiv.org/content/10.1101/2024.02.26.582115v4
+"""
+
+from .params import CBASParams, CBASResult
+from .io import (load_subject_data, extract_choice_stream, extract_choice_streams_by_block,
+                 enumerate_sequences, enumerate_sequences_block_aware)
+from .core import build_count_matrix, compute_test_stats, compute_test_stats_correlative
+from .bootstrap import bootstrap_test_stats, bootstrap_test_stats_correlative
+from .stepdown import (
+    romano_wolf_stepdown,
+    find_k_fwer,
+    find_k_fwer_k1,
+    find_k_fwer_chunked,
+)
+from .resources import estimate_resources, print_resource_estimate
+from .pipeline import run_cbas_comparative, run_cbas_correlative
+
+__all__ = [
+    "CBASParams",
+    "CBASResult",
+    "load_subject_data",
+    "extract_choice_stream",
+    "extract_choice_streams_by_block",
+    "enumerate_sequences",
+    "enumerate_sequences_block_aware",
+    "build_count_matrix",
+    "compute_test_stats",
+    "compute_test_stats_correlative",
+    "bootstrap_test_stats",
+    "bootstrap_test_stats_correlative",
+    "romano_wolf_stepdown",
+    "find_k_fwer",
+    "find_k_fwer_k1",
+    "find_k_fwer_chunked",
+    "run_cbas_comparative",
+    "run_cbas_correlative",
+    "estimate_resources",
+    "print_resource_estimate",
+]