Metadata-Version: 2.4
Name: ethopy-analysis
Version: 0.1.2
Summary: Data analysis and visualization package for Ethopy behavioral experiments
Author: Ethopy Analysis Contributors
License: MIT
Project-URL: Homepage, https://github.com/ef-lab/ethopy_analysis
Project-URL: Repository, https://github.com/ef-lab/ethopy_analysis
Project-URL: Documentation, https://ef-lab.github.io/ethopy_analysis
Project-URL: Bug Tracker, https://github.com/ef-lab/ethopy_analysis/issues
Keywords: neuroscience,behavior,data-analysis,visualization,ethopy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: datajoint>=0.13.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: click>=8.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: ipykernel>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Requires-Dist: ipykernel>=6.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=8.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.19.0; extra == "docs"

# 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)
