sl-behavior

A Python library that provides tools for processing non-visual behavior data acquired in the Sun (NeuroAI) lab.

---

Detailed Description

This library is used to extract and process the data from the .npz log archives generated by the sl-experiment library. It saves the extracted data as a set of uncompressed .feather files that are later read and integrated into unified project datasets using the sl-forgery library.

The library is purpose-built to work with the data acquired by the current and former data acquisition systems used in the Sun lab. It is designed to be called via the bindings in the sl-forgery library and run on remote compute servers. End users should not use any assets from this library directly.

---

Features

• Extracts and processes camera frame acquisition timestamps from video camera log archives.
• Extracts and processes runtime (task) and data acquisition system configuration data.
• Extracts and processes hardware module data from microcontroller log archives.
• Uses parallel processing to optimize data extraction performance.
• GPL 3 License.

---

Table of Contents

• Dependencies
• Installation
• Usage
• API Documentation
• Developers
• Versioning
• Authors
• License
• Acknowledgements

---

Dependencies

For users, all library dependencies are installed automatically by all supported installation methods (see the Installation section).

Note! Developers should see the Developers section for information on installing additional development dependencies.

---

Installation

Source

Note, installation from source is highly discouraged for anyone who is not an active project developer.

1. Download this repository to the local machine using the preferred method, such as git-cloning. Use one of the stable releases that include precompiled binary and source code distribution (sdist) wheels.
2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.
3. cd to the root directory of the prepared project distribution.
4. Run python -m pip install . to install the project. Alternatively, if using a distribution with precompiled binaries, use python -m pip install WHEEL_PATH, replacing 'WHEEL_PATH' with the path to the wheel file.

pip

Use the following command to install the library using pip: pip install sl-behavior

---

Usage

Primarily, the library is designed to be used on a remote compute server via the bindings in the sl-forgery library. Due to the centralized approach to data collection and processing in the lab, all experiment and training sessions require processing with this library.

It is also possible to manually call this library to process target sessions by using the sl-behavior CLI command exposed by this library as part of its installation into a Python environment. See the API documentation section below to learn more about the CLI and API interfaces of this library.

---

API Documentation

See the API documentation for the detailed description of the methods and classes exposed by components of this library.

Note! The API documentation includes important information about Command-Line Interfaces (CLIs) exposed by this library as part of installation into a Python environment.

---

Developers

This section provides installation, dependency, and build-system instructions for project developers.

Installing the Project

Note! This installation method requires mamba version 2.3.2 or above. Currently, all Sun lab automation pipelines require that mamba is installed through the miniforge3 installer.

1. Download this repository to the local machine using the preferred method, such as git-cloning.
2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.
3. cd to the root directory of the prepared project distribution.
4. Install the core Sun lab development dependencies into the base mamba environment via the mamba install tox uv tox-uv command.
5. Use the tox -e create command to create the project-specific development environment followed by tox -e install command to install the project into that environment as a library.

Additional Dependencies

In addition to installing the project and all user dependencies, install the following dependencies:

1. Python distributions, one for each version supported by the developed project. Currently, this library supports the three latest stable versions. It is recommended to use a tool like pyenv to install and manage the required versions.

Development Automation

This project comes with a fully configured set of automation pipelines implemented using tox. Check the tox.ini file for details about the available pipelines and their implementation. Alternatively, call tox list from the root directory of the project to see the list of available tasks.

Note! All pull requests for this project have to successfully complete the tox task before being merged. To expedite the task’s runtime, use the tox --parallel command to run some tasks in-parallel.

Automation Troubleshooting

Many packages used in 'tox' automation pipelines (uv, mypy, ruff) and 'tox' itself may experience runtime failures. In most cases, this is related to their caching behavior. If an unintelligible error is encountered with any of the automation components, deleting the corresponding .cache (.tox, .ruff_cache, .mypy_cache, etc.) manually or via a CLI command typically solves the issue.

---

Versioning

This project uses semantic versioning. See the tags on this repository for the available project releases.

---

Authors

• Ivan Kondratyev (Inkaros)
• Kushaan Gupta (kushaangupta)
• Natalie Yeung

---

License

This project is licensed under the GPL3 License: see the LICENSE file for details.

---

Acknowledgments

• All Sun lab members for providing the inspiration and comments during the development of this library.
• The creators of all other dependencies and projects listed in the pyproject.toml file.

---