ethopy-analysis 0.1.2
Data analysis and visualization package for Ethopy behavioral experiments
License: MIT
Requires Python: >=3.8
Keywords: neuroscience, behavior, data-analysis, visualization, ethopy

# Ethopy Analysis

A comprehensive Python package for analyzing and visualizing behavioral data from Ethopy experiments.

## Overview

Ethopy Analysis provides a modern, modular approach to behavioral data analysis with the following key features:

- **DataFrame-based**: Most of plotting functions work with pandas DataFrames, making them independent of data source
- **Modular Design**: Composable functions for different analysis levels (animal, session, comparison)
- **Database Agnostic**: Works with DataJoint databases, CSV files, or any pandas-compatible data source
- **Extensible**: Plugin system for custom plots and analysis functions
- **Production Ready**: Command-line interface, proper packaging, and configuration management

## Installation

### From Source (Development)

Setting Up a Virtual Environment¶

Before installing dependencies, it's recommended to use a virtual environment to keep your project isolated and manageable.
```bash
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
```
installing dependencies:
```bash
# Clone the repository
git clone <repository-url>
cd Visualisations

# Install in development mode
pip install -e .
```

### Dependencies

- pandas >= 1.3.0
- matplotlib >= 3.5.0
- seaborn >= 0.11.0
- numpy >= 1.20.0
- plotly >= 5.0.0
- datajoint >= 0.13.0 (for database access)
- click >= 8.0.0 (for CLI)

## Package Structure

```
ethopy-analysis/
├── src/ethopy_analysis/
│   ├── data/                   # Data loading and processing
│   │   ├── loaders.py          # Main data loading functions
│   │   ├── analysis.py         # Data analysis functions
│   │   └── utils.py            # Data processing utilities
│   ├── plots/                  # Plotting functions (DataFrame-based)
│   │   ├── animal.py           # Animal-level plots
│   │   ├── session.py          # Session-level plots
│   │   ├── comparison.py       # Multi-animal/condition comparisons
│   │   └── utils.py            # Plotting utilities and plugin system
│   ├── db/                     # Database connectivity
│   │   ├── schemas.py          # Database schema management
│   │   └── utils.py            # Database utility functions
│   ├── config/                 # Configuration management
│   │   └── settings.py         # Configuration loading and validation
│   └── cli.py                  # Command-line interface
├── examples/                   # Example notebooks and scripts
│   ├── load_example.ipynb
│   ├── animal_analysis_example.ipynb
│   └── session_analysis_example.ipynb
├── pyproject.toml              # Package configuration
└── README.md
```

## Configuration

### Database Setup

Create a configuration file for database access:

```bash
ethopy-analysis create-config --output-path config.json
```

Edit the configuration file:

```json
{
  "database": {
    "host": "your-database.org:3306",
    "user": "your_username",
    "password": "your_password",
    "schemas": {
      "experiment": "lab_experiments",
      "stimulus": "lab_stimuli",
      "behavior": "lab_behavior"
    }
  }
}
```

### Environment Variables

Alternatively, use environment variables:

```bash
export DJ_HOST="database.example.org:3306"
export DJ_USER="your_username"
export DJ_PASSWORD="your_password"
```

## Examples and Tutorials

Check out the `examples/` directory for comprehensive notebooks:

- **`load_example.ipynb`**: Comprehensive animal-level analysis
- **`animal_analysis_example.ipynb`**: Comprehensive animal-level analysis
- **`session_analysis_example.ipynb`**: Detailed session-level analysis

## Contributing

### Adding New Plot Functions

1. Create your plotting function in the appropriate module
2. Follow the DataFrame-based input convention
3. Return `(fig, ax)` or `(fig, axes)` tuple
4. Import and use directly in your analysis

### Code Style

- Functions over classes where possible
- Clear, descriptive function names
- Pandas DataFrames for data exchange
- Matplotlib for plotting (with optional Plotly support)