Metadata-Version: 2.1
Name: megabouts
Version: 0.0.0
Summary: Megabouts: a toolbox to quantify zebrafish locomotion
Author-email: Adrien Jouary <adrien.jouary@research.fchampalimaud.org>
License: # Non-Commercial Research and Academic Use Software License and Terms of Use
        
        
        Megabouts is a software package that includes original code created by the Fundação Champalimaud researchers listed below (the “Software”), and third-party code that may be obtained by End Users separately. The Software is designed to provide a standard approach to label zebrafish behaviors from various tracking data. The Software was developed by Adrien Jouary, Ph.D. in the laboratory of Michael B. Orger at Fundação Champalimaud. It is distributed for free academic and non-commercial research use by the Fundação D. Anna de Sommer Champalimaud e Dr. Carlos Montez Champalimaud (“Fundação Champalimaud”).
        
        Using the Software indicates your agreement to be bound by the terms of this Software Use Agreement (“Agreement”). Absent your agreement to the terms below, you (the “End User”) have no rights to hold or use the Software whatsoever.
        
        Fundação Champalimaud agrees to grant hereunder a limited non-exclusive license to End User for the use of the Software in the performance of End User’s internal, non-commercial research and academic use at End User’s academic or not-for-profit research institution (“Institution”) on the following terms and conditions:
        
        1. **NO COMMERCIAL USE.** End User shall not use the Software for Commercial use and any such use of the Software is expressly prohibited. “Commercial use” includes, but is not limited to, (i) use of the Software in fee-for-service arrangements, (ii) use of the Software by core facilities or laboratories to provide research services to (or in collaboration with) for-profit third parties for a fee, and (iii) use of the Software in industry-sponsored and/or collaborative research projects in which any commercial rights are granted to the sponsor or collaborator. If End User wishes to use the Software for Commercial use, End User must execute a separate license agreement with Fundação Champalimaud.
        
        _Requests for use of the Software for Commercial use, please contact:_
        
        Innovation Officer
        Fundação Champalimaud
        Avenida Brasília
        1400-038
        Lisboa
        E-mail: Nina Patrick <nina.patrick@research.fchampalimaud.org>
        
        2. **OWNERSHIP AND COPYRIGHT NOTICE.** Fundação Champalimaud owns all intellectual property in the Software. End User shall gain no ownership to the Software.  End User shall not remove or delete, and shall retain in the Software (including in any modifications to the Software and in any Derivative Works), the copyright, trademark, or other notices pertaining to Software as provided with the Software.
        
        3. **DERIVATIVE WORKS.** End User may create, use, and distribute Derivative Works, as such term is defined under applicable copyright laws, provided that any such Derivative Works shall be restricted to non-commercial research and academic use. End User may not distribute Derivative Works to any for-profit third parties for Commercial use.
        
        4. **FEEDBACK.** In order to improve the Software, comments from End Users may be useful. End User agrees to provide Fundação Champalimaud with feedback on the End User’s use of the Software (e.g., any bugs in the Software, the user experience, etc.). Fundação Champalimaud is permitted to use such information provided by End User in making changes and improvements to the Software without compensation or accounting to End User.
        
        5. **NON ASSERT.** End User acknowledges that Fundação Champalimaud may develop modifications to the Software that may be based on the feedback provided by End User under Section 5 above. Fundação Champalimaud shall not be restricted in any way by End User regarding its use of such information. End User acknowledges the right of Fundação Champalimaud to prepare, publish, display, reproduce, transmit and or use modifications to the Software that may be substantially similar or functionally equivalent to End User’s modifications and/or improvements if any. In the event that End User obtains patent protection for any modification or improvement to Software, End User agrees not to allege or enjoin infringement of End User’s patent against Fundação Champalimaud, or any of the researchers, medical or research staff, officers, directors and employees of those institutions.
        
        6. **PUBLICATION & ATTRIBUTION.** End User has the right to publish, present, or share results from the use of the Software. In accordance with customary academic practice, End User will acknowledge Fundação Champalimaud as the provider of the Software and may cite the relevant reference(s) from the following list of publications:
        
        Jouary A, Orger M, et al. (Year). [Relevant publication details].
        
        7.** NO WARRANTIES.** THE SOFTWARE IS PROVIDED "AS IS." TO THE FULLEST EXTENT PERMITTED BY LAW, FUNDAÇÃO CHAMPALIMAUD HEREBY DISCLAIMS ALL WARRANTIES OF ANY KIND (EXPRESS, IMPLIED OR OTHERWISE) REGARDING THE SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OWNERSHIP, AND NON-INFRINGEMENT. FUNDAÇÃO CHAMPALIMAUD MAKES NO WARRANTY ABOUT THE ACCURACY, RELIABILITY, COMPLETENESS, TIMELINESS, SUFFICIENCY OR QUALITY OF THE SOFTWARE. FUNDAÇÃO CHAMPALIMAUD DOES NOT WARRANT THAT THE SOFTWARE WILL OPERATE WITHOUT ERROR OR INTERRUPTION.
        
        8. **LIMITATIONS OF LIABILITY AND REMEDIES.** USE OF THE SOFTWARE IS AT END USER’S OWN RISK. IF END USER IS DISSATISFIED WITH THE SOFTWARE, ITS EXCLUSIVE REMEDY IS TO STOP USING IT. IN NO EVENT SHALL FUNDAÇÃO CHAMPALIMAUD BE LIABLE TO END USER OR ITS INSTITUTION, IN CONTRACT, TORT OR OTHERWISE, FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR OTHER DAMAGES OF ANY KIND WHATSOEVER ARISING OUT OF OR IN CONNECTION WITH THE SOFTWARE, EVEN IF FUNDAÇÃO CHAMPALIMAUD IS NEGLIGENT OR OTHERWISE AT FAULT, AND REGARDLESS OF WHETHER FUNDAÇÃO CHAMPALIMAUD IS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
        
        9. **INDEMNIFICATION.** To the extent permitted by law, End User shall indemnify, defend and hold harmless Fundação Champalimaud, their corporate affiliates, current or future directors, trustees, officers, faculty, medical and professional staff, employees, students and agents and their respective successors, heirs and assigns (the "Indemnitees"), against any liability, damage, loss or expense (including reasonable attorney's fees and expenses of litigation) incurred by or imposed upon the Indemnitees or any one of them in connection with any claims, suits, actions, demands or judgments arising from End User’s breach of this Agreement or its Institution’s use of the Software except to the extent caused by the gross negligence or willful misconduct of Fundação Champalimaud. This indemnification provision shall survive expiration or termination of this Agreement.
        
        10. **GOVERNING LAW.** This Agreement shall be construed and governed by the laws of Portugal regardless of otherwise applicable choice of law standards.
        
        11. **NON-USE OF NAME.** Nothing in this License and Terms of Use shall be construed as granting End Users or their Institutions any rights or licenses to use any trademarks, service marks or logos associated with the Software. End User may not use the terms “Fundação Champalimaud” (or a substantially similar term) in any way that is inconsistent with the permitted uses described herein. End Users may not use any name or emblem of Fundação Champalimaud or any of its schools or subdivisions for any purpose, or to falsely suggest any relationship between End User (or its Institution) and Fundação Champalimaud, or in any manner that would infringe or violate any of its rights.
        
        12. End User represents and warrants that it has the legal authority to enter into this License and Terms of Use on behalf of itself and its Institution.
        
        
        
Project-URL: Homepage, https://megabouts.ai
Project-URL: Documentation, https://megabouts.ai
Project-URL: Repository, https://github.com/orger-lab/megabouts.git
Project-URL: Issues, https://github.com/orger-lab/megabouts/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ipykernel
Requires-Dist: h5py
Requires-Dist: matplotlib
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-image
Requires-Dist: pybaselines
Requires-Dist: scikit-learn
Requires-Dist: torch
Requires-Dist: sporco
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: nbmake; extra == "test"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: build; extra == "docs"
Requires-Dist: twine; extra == "docs"
Requires-Dist: setuptools; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx_design; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinxcontrib-video; extra == "docs"
Requires-Dist: sphinxcontrib-jupyter; extra == "docs"
Requires-Dist: sphinx-togglebutton; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"

# Megabouts 🐟

<div align="center">

![Megabouts Logo](docs/source/_static/images/logo_color_dark.png)

[![PyPI version](https://badge.fury.io/py/megabouts.svg)](https://badge.fury.io/py/megabouts)
[![Documentation Status](https://img.shields.io/badge/docs-megabouts.ai-blue)](https://megabouts.ai)

</div>

## Overview

Megabouts is a Python toolbox designed to precisely quantify zebrafish larval locomotion. Our software supports locomotion analysis in both freely swimming and head-restrained conditions, adapting to various experimental setups and recording speeds.

**📚 Full documentation and tutorials available at: [megabouts.ai](https://megabouts.ai)**

## Features

- **Flexible Data Input**:
  - Multiple tracking methods (full tracking, head tracking, tail tracking)
  - Support various frame rates (20-700 Hz) and resolutions
  - Compatible with different tracking software (e.g., SLEAP)

- **Analysis Pipeline**:
  - Tail angle and trajectory preprocessing
  - Tail bout detection
  - Movement classification using transformer neural networks
  - Sparse coding for head-restrained experiments

## Installation

```bash
pip install megabouts
```

## Quick Start

```python
from megabouts.tracking_data import TrackingConfig, FullTrackingData, load_example_data
from megabouts.pipeline import FullTrackingPipeline

# Load example data
df_recording, fps, mm_per_unit = load_example_data("fulltracking_posture")

# Configure tracking
tracking_cfg = TrackingConfig(fps=fps, tracking="full_tracking")

# Create tracking data
head_x = df_recording["head_x"].values * mm_per_unit
head_y = df_recording["head_y"].values * mm_per_unit
head_yaw = df_recording["head_angle"].values
tail_angle = df_recording.filter(like="tail_angle").values

tracking_data = FullTrackingData.from_posture(
    head_x=head_x, 
    head_y=head_y, 
    head_yaw=head_yaw, 
    tail_angle=tail_angle
)

# Create pipeline and run
pipeline = FullTrackingPipeline(tracking_cfg)
tracking, tail, traj, segments, bouts, ethogram = pipeline.run(tracking_data)
```

## License

This software is available for non-commercial research and academic use only. The software was developed by Adrien Jouary, Ph.D. in the laboratory of Michael B. Orger at Fundação Champalimaud. For full license terms, please see the [LICENSE.md](LICENSE.md) file.

## Citation
```bibtex
@article{jouary2024megabouts,
    title={Megabouts: a flexible pipeline for zebrafish locomotion analysis},
    author={Jouary, Adrien and Laborde, Alexandre and Silva, Pedro T and Mata, J Miguel 
            and Marques, Joao C and Collins, Elena and Peterson, Randall T 
            and Machens, Christian K and Orger, Michael B},
    journal={bioRxiv},
    pages={2024--09},
    year={2024},
    publisher={Cold Spring Harbor Laboratory}
}
```

## Contact

- **Author**: Adrien Jouary
- **Email**: adrien.jouary at research.fchampalimaud.org
- **Organization**: Champalimaud Foundation

## Acknowledgments

This work was developed at the Champalimaud Foundation in the laboratory of Michael B. Orger.

