Ext basic

Airscope

A 1-gram wireless mesoscope for cortex-wide, single-cell-resolution imaging during unrestricted behaviour

Device Docs · Software Docs · Data Release

Airscope is an open hardware and software platform for wireless mesoscopic calcium imaging in freely behaving mice. The device achieves a 6 mm field of view at ~4 µm lateral resolution, streams or logs 1600 × 1200 px images at 10 Hz, and weighs approximately 1 g.

This repository accompanies the manuscript:

Deciphering cortex-wide neural dynamics of naturally behaving mice by a 1-gram wireless mesoscope Zhang et al., Nature, 2025 （Manuscript in preparation）

Repository Structure

Key Capabilities

• Cortex-wide cellular imaging — 6 mm FOV with single-cell spatial resolution across the dorsal cortex
• Untethered operation — wireless data transfer and on-board logging for freely moving, multi-animal, and aquatic paradigms
• Integrated acquisition stack — firmware + host software for discovery, preview, timestamping, and recording
• Reproducible calcium processing — motion correction → background removal → neuron segmentation → trace extraction
• Behavioural analysis — SAM2Mice for multi-animal tracking; Neuron-BERT for decoding social-interaction outcomes

Software Modules

Calcium-imaging processing · Software/Airscope_ca_processing

End-to-end pipeline from raw frames to segmented ROI traces. Accepts image sequences, TIFF stacks, and MP4 input; configured with Hydra for reproducible batch runs.

cd Software/Airscope_ca_processing
conda create -n PICO python=3.10 && conda activate PICO
pip install -r requirements.txt && pip install -e .

airscope-process \
  data_path=/path/to/session/frames \
  out_path=/path/to/session/analysis \
  rmbg.gpu_ids=0 rmbg.multi_gpu=false

Primary outputs: seg_results_filtered.mat, infer_results_filtered.mat, cm_filtered.mat

SAM2Mice · Software/SAM2Mice

SAM 2–based mouse segmentation and tracking. Supports manual prompts, YOLOv11 auto-prompts, and bootstrapped inference for videos that exceed GPU memory.

cd Software/SAM2Mice
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
pip install -e ".[notebooks]" && python setup.py build_ext --inplace

Notebooks in Software/SAM2Mice/notebooks_SAM2-MICE cover basic segmentation, long-video bootstrapping, automatic tracking, and public-dataset examples.

Neuron-BERT · Software/Neuron_BERT

Transformer-based decoder for predicting social-interaction outcomes from dual-animal neural activity recordings.

Host acquisition software · DAQ_software/

Dependency-free Python backend — runs without any additional packages:

cd DAQ_software/airscope_pybackend
python server.py
# UI available at http://127.0.0.1:8765/

A packaged Windows installer is also provided at DAQ_software/airscope.msi.

Data Release

Example datasets are hosted on Google Drive and documented in Data_release/README.md. The Google Drive root README is maintained at Data_release/README_google_drive.md and can be uploaded to Drive as README_google_drive.md.

Each dataset directory includes a README.md and a visualize_data.ipynb notebook.

Requirements

See the component-level README.md files for exact commands and configuration.

Licensing

Airscope is distributed as a multi-licence repository:

See LICENSE, LICENSES/, and NOTICE.md for the authoritative licence map and third-party notices.

Citation

@article{airscope2025,
  title   = {Deciphering cortex-wide neural dynamics of naturally
             behaving mice by a 1-gram wireless mesoscope},
  author  = {Zhang, Yuanlong and Li, Angran and Yuan, Lekang and
             Wang, Mingrui and Zhao, Weihao and Wang, Zhenbo and
             Zang, Boyang and Zhou, Yangxuan and Yu, Tao and Gao, Lin
             and Wu, Yu and Zhu, Rongkang and Tian, Mengyi and Li, Kun
             and Wu, Jiamin and Dai, Pu and Dai, Qionghai},
  journal = {Nature},
  year    = {2025},
  note    = {Manuscript in preparation}
}

Documentation

• Device assembly, acquisition, and operation: https://airscope.org/devkit/
• Processing pipelines, notebooks, and examples: https://airscope-docxs.readthedocs.io/en/latest/

Contact

Questions, bug reports, and suggestions can be submitted via the issue tracker or sent to the corresponding authors listed in the manuscript.