Metadata-Version: 2.5
Name: flyconn
Version: 0.1.0
Summary: Research-grade toolkit over public Drosophila connectomes: harmonized data, signed graphs, uncertainty, validated LIF simulation, declarative experiments.
Project-URL: Documentation, https://github.com/moiz-lakkadkutta/flyconn
Project-URL: Repository, https://github.com/moiz-lakkadkutta/flyconn
Author: flyconn contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: connectome,drosophila,flywire,malecns,neuroscience
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=15
Requires-Dist: pyyaml>=6
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13
Requires-Dist: scipy>=1.11
Requires-Dist: typer>=0.12
Provides-Extra: access
Requires-Dist: openpyxl>=3.1; extra == 'access'
Provides-Extra: cave
Requires-Dist: caveclient>=8; extra == 'cave'
Provides-Extra: interpret
Requires-Dist: connectome-interpreter>=2.9.5; extra == 'interpret'
Requires-Dist: torch>=2.2; extra == 'interpret'
Provides-Extra: morph
Requires-Dist: flybrains>=0.6; extra == 'morph'
Requires-Dist: navis>=1.10; extra == 'morph'
Provides-Extra: neuprint
Requires-Dist: neuprint-python>=0.6; extra == 'neuprint'
Provides-Extra: sim
Requires-Dist: torch>=2.2; extra == 'sim'
Description-Content-Type: text/markdown

# flyconn

Research-grade Python toolkit over the public *Drosophila* connectomes
(MaleCNS v1.0, FlyWire v630/v783, hemibrain, MANC, BANC): a harmonized offline
data layer, signed sparse graphs, uncertainty propagation, a validated
cross-platform LIF simulator, declarative in-silico experiments with reports,
and cross-dataset comparison.

Status: pre-alpha; milestones M0–M7 of `docs/PLAN.md` are implemented and validated against
published results on real data (`docs/GOLDEN_RESULTS.md`, `docs/PROGRESS.md`).

## Install

```bash
pip install "flyconn[sim]"            # data, graph, uncertainty, simulator
pip install "flyconn[sim,interpret]"  # + connectome_interpreter adapter
```

The interpret extra resolves `connectome-interpreter` 2.9.5 from PyPI; flyconn's parity tests
run against a newer git commit of that package (see ADR-0002), so treat the PyPI combination as
untested until upstream releases again. Documentation: https://moiz-lakkadkutta.github.io/flyconn/

## Quickstart

```bash
uv sync --extra sim --extra interpret --extra access
uv run flyconn data list
uv run flyconn data pull malecns@1.0 --level weights      # ~1.1 GB, checksummed, resumable
uv run flyconn data pull shiu@630 --level weights          # Shiu et al. 2024 model inputs (90 MB)
uv run flyconn run examples/specs/w2_malecns_lb3_silence_gng232.yaml --out runs/w2
```

Python:

```python
from flyconn.data.store import Store
from flyconn.graph import ConnectivityMatrix, find_paths
from flyconn.uncertainty import path_stability

m = ConnectivityMatrix.from_store(Store.open("malecns@1.0"), min_weight=5)
lb3 = m.meta.index[m.meta["cell_type"].str.match(r"^LB3", na=False)]
mn9 = m.meta.index[m.meta["cell_type"] == "MN9"]
paths = find_paths(m, lb3, mn9, max_hops=3, min_edge_fraction=0.01, label="cell_type")
stab = path_stability(m, lb3, mn9, thresholds=[5, 10, 20], n_samples=100, seed=0)
```

Anchor workflows: `examples/w1_pathways.py`, `examples/w4_version_drift.py`,
`examples/specs/w2_*.yaml`, `examples/w3_male_vs_female.py`, `examples/w5_driver_lines.py`.
Scientific caveats: `docs/caveats.md`.

Not to be confused with the Cambridge FlyConnectome group's tools (`cocoa`,
`flywire_annotations`); flyconn is independent and builds on that ecosystem.

## Scientific stance

A connectome is wiring. Neurotransmitter identities are predicted, weights are
synapse counts, and every simulation output is a model prediction. Controls run
by default, uncertainty is propagated, and every result carries provenance and
the citations of the datasets it used. See `docs/caveats.md` once written.

## Licence and attribution

Code: Apache-2.0. Data: CC BY 4.0 by the respective consortia; every result
object emits the citation list it depends on. Design ideas borrowed from
MIT-licensed projects are listed in `ATTRIBUTION.md`.
