Metadata-Version: 2.4
Name: rainstorm
Version: 1.0.4
Summary: Real & Artificial Intelligence for Neuroscience – Simple Tracker for Object Recognition Memory
Home-page: https://github.com/sdhers/RAINSTORM
Author: Santiago D'hers
Author-email: sdhers@fbmc.fcen.uba.ar
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: h5py==3.12.1
Requires-Dist: keras==2.10.0
Requires-Dist: keyboard==0.13.5
Requires-Dist: matplotlib==3.9.3
Requires-Dist: numpy==1.25.2
Requires-Dist: opencv-python==4.10.0.84
Requires-Dist: pandas==2.0.3
Requires-Dist: plotly==5.24.1
Requires-Dist: PyYAML==6.0.2
Requires-Dist: scikit-learn==1.6.0
Requires-Dist: scipy==1.13.1
Requires-Dist: seaborn==0.13.2
Requires-Dist: tables==3.9.2
Requires-Dist: tensorflow==2.10.1
Requires-Dist: tqdm==4.67.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

# **RAINSTORM**

### Real & Artificial Intelligence for Neuroscience – Simple Tracker for Object Recognition Memory

**A complete toolkit for analyzing rodent exploratory behavior in object recognition tasks.**

![RAINSTORM Logo](examples/images/logo.png)

</div>

**RAINSTORM** is a Python-based tool for scoring exploratory behavior in rodents 🐭. It takes pose-estimation data (e.g., from DeepLabCut) and provides a full workflow to process, analyze, and visualize recognition memory performance, from manual labeling to AI-powered automation.

-----

## Table of Contents 📋

* [Features ✨](#features-)
* [Installation 💾](#installation-)
* [Usage 💻](#usage-)
    - [Video Handling 🎥](#video-handling-)
    - [RAINSTORM Behavioral Labeler ✍️](#RAINSTORM-behavioral-labeler-)
    - [The RAINSTORM Pipeline 🔬](#the-rainstorm-pipeline-)
* [Citation 📜](#citation-)
* [Contributing 🤝](#contributing-)
* [Contact 📫](#contact-)

-----

## Features ✨

* **🎯 Frame-by-Frame Behavioral Labeling:** A versatile tool for precise manual scoring and for generating training data for your AI models.
* **🔧 Pre & Post-DLC Data Processing:** Align video points, clean tracking glitches, and interpolate data for smooth and reliable analysis.
* **📐 Geometric Analysis:** Automatically identify object exploration using distance and angle metrics.
* **🧊 Immobility Detection:** Label freezing behavior based on motion, a key indicator in memory studies.
* **⚙️ AI-Powered Automatic Labeling:** Train and deploy neural networks (including LSTMs) to automatically detect complex exploration patterns.
* **📊 Visual Label Comparison:** Easily compare manual, geometric, and AI-generated labels with intuitive visualizations.

-----

## Installation 💾

### Prerequisites

First, ensure you have the following software installed on your system.

* [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html) (or Anaconda)
* [Visual Studio Code](https://code.visualstudio.com/Download)
* [Git](https://git-scm.com/downloads)

> [!TIP]
> During the Miniconda installation, select the option to **add Conda to your system's PATH**. This will make it easier to run `conda` commands from any terminal.
> 
> Make sure to **reboot** your computer to ensure the new software is properly installed.

### Setup Steps

1.  **Clone the Repository**

    Open a terminal (or Miniconda Prompt) and run the following command.
    ```bash
    git clone https://github.com/sdhers/rainstorm.git
    ```
    This will create a `rainstorm` folder in your current directory.

2.  **Set Up the Conda Environment**

    Navigate into the cloned directory and create the dedicated environment from the provided file:
    ```bash
    cd rainstorm
    conda env create -f rainstorm_venv.yml
    ```
    Once the environment is ready, you can activate it by running `conda activate rainstorm`.

3.  **Launch VS Code & Select Kernel**

    Launch VS Code from the terminal:
    ```bash
    code .
    ```
    In VS Code, ensure the Python extension is installed:
    * Go to the Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X` on macOS).
    * Search for "Python" and install the official extension from Microsoft.

    Open a Jupyter notebook (e.g., `2a-Prepare_positions.ipynb`).
    * When prompted to select a kernel, choose the `rainstorm` Conda environment from the list of `Python Environments`.

You are all set! You can now run the notebooks to explore the RAINSTORM workflow.

-----

## Usage 💻

RAINSTORM offers two main functionalities: a full analysis pipeline using Jupyter notebooks and a standalone tool for manual video labeling.

-----

### Video Handling 🎥

We offer a quick and easy way to prepare videos for pose estimation and behavioral analysis.

**Open the file `0-Video_handling.ipynb`**
1.  **Run the Video Handling app**
    This app allows you to:
    * Trim the video to the desired length.
    * Crop the video to the desired size.
    * Align videos based on two manually selected points (very useful when batch processing videos with ROIs).
2.  **Run the Draw ROIs app**
    This app allows you to:
    * Draw ROIs and points on the video.
    * Select a distance for scaling.

-----

### RAINSTORM Behavioral Labeler ✍️

For precise, frame-by-frame annotation, use the **RAINSTORM Behavioral Labeler**.

**Open and run the file `1-Behavioral_labeler.ipynb`**
1.  **Select the video you want to label.**

2.  **(Optional) Load a previous labeling `.csv` file.**
    * This allows you to pick up where you left off.

3.  **Select the behaviors to label and their keys.**
    * Enter the behaviors you want to score (e.g., `exp_1`, `exp_2`, `freezing`, `grooming`, etc...).

> [!WARNING]
> Keys should be unique, single characters, and different from the fixed control keys: (Quit: `q`, Zoom In: `+`, Zoom Out: `-`, Margin Toggle: `m`)

4.  **Start Labeling!**
    After pressing 'Start Labeling', the video will load, and you can begin annotating frame by frame using the keys you defined.

-----

### The RAINSTORM Pipeline 🔬

The core of this project is a series of Jupyter notebooks designed to guide you from raw data to final results.

-----

#### `2a-Prepare_positions.ipynb`

🧹 **Process and clean bodypart position data.**

* Filters out frames with low tracking likelihood from DeepLabCut.
* Interpolates and smooths data to correct glitches.
* **Output:** Clean `.csv` files ready for analysis.

![1-Prepare_positions](examples/images/1-Prepare_positions.png)

-----

#### `2b-Geometric_analysis.ipynb`

📐 **Perform geometric labeling of exploration and freezing.**

* Applies a simple geometric rule for exploration:
    * Distance to object < `2.5 cm`
    * Angle towards object < `45°`
* Identifies freezing behavior based on lack of movement.

![2-Geometric_analysis](examples/images/2-Geometric_analysis.png)

-----

#### `3a-Create_Models.ipynb`

⚙️ **Train AI models for automatic behavioral labeling.**

* Uses your manually labeled data to train TensorFlow models.
    ![4-Evaluate_models_b](examples/images/4-Evaluate_models_b.png)
* Includes an LSTM network (a **wide** model) that considers temporal sequences for higher accuracy.
    ![3-Create_Models](examples/images/3-Create_models.png)
* Evaluates model performance against human labelers using Principal Components Analysis (PCA).
    ![4-Evaluate_models_a](examples/images/4-Evaluate_models_a.png)

-----

#### `3b-Automatic_analysis.ipynb`

🧠 **Automate labeling with your trained AI model.**

* Applies your best-performing model to label unseen datasets.
* Generates comparative visualizations (like polar graphs) to contrast manual, geometric, and AI-driven labels.

![6-Compare_Labels](examples/images/6-Compare_labels.png)

-----

#### `4-Seize_Labels.ipynb`

📊 **Extract, summarize, and visualize your final data.**

* Calculates key metrics like the Discrimination Index.
* Generates publication-ready plots to compare behavior across different experimental groups and sessions.

![7-Seize_Labels_ts](examples/images/7-Seize_labels_ts.png)

-----

## Citation 📜

If you use RAINSTORM in your research, please cite:

D'hers et al. (2025). RAINSTORM: Automated Analysis of Mouse Exploratory Behavior using Artificial Neural Networks. *Current Protocols*. [DOI: 10.1002/cpz1.70171](https://doi.org/10.1002/cpz1.70171)

> Note: This repository contains open-source code independently developed and released under the MIT License. The associated scientific publication is © Wiley and subject to their copyright terms.

-----

## Contributing 🤝

Contributions are welcome! If you have suggestions or find a bug, please feel free to open an issue or submit a pull request.

-----

## Contact 📫

For any questions or collaborations, please reach out to sdhers@fbmc.fcen.uba.ar.

-----

*Thanks for exploring RAINSTORM!*

![mouse_exploring](examples/images/mouse_exploring.gif)

-----
