Metadata-Version: 2.4
Name: minerva-ml
Version: 0.3.8b0
Summary: A framework for training machine learning models for researchers.
Author-email: Gabriel Gutierrez <gabriel.bgs00@gmail.com>, Otávio Napoli <otavio.napoli@ic.unicamp.br>, Fernando Gubitoso Marques <fernandogubitosom@gmail.com>, Edson Borin <borin@unicamp.br>
License: MIT License
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Bug Tracker, https://github.com/discovery-unicamp/Minerva/issues
Project-URL: Homepage, https://github.com/discovery-unicamp/Minerva
Keywords: Deep Learning,Machine Learning,Pytorch,Research,Self-Supervised Learning,SSL
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gitpython>=3
Requires-Dist: jsonargparse[omegaconf]==4.37.0
Requires-Dist: kaleido>=0.2.1
Requires-Dist: lightning>=2.1.9
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.23.5
Requires-Dist: opencv-python>=4.10.0.84
Requires-Dist: pandas>=2.2.2
Requires-Dist: perlin-noise>=1.12
Requires-Dist: plotly>=5.18
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.13
Requires-Dist: tifffile>=2024
Requires-Dist: timm>=1.0.2
Requires-Dist: torch>=2.5.0
Requires-Dist: torchinfo>=1.8.0
Requires-Dist: torchmetrics>=1.3.0
Requires-Dist: torchvision>=0.15
Requires-Dist: transformers>=4.47.1
Requires-Dist: wrapt>=1.16
Requires-Dist: zarr>=2.17
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: interrogate; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: mock; extra == "dev"
Requires-Dist: nbformat; extra == "dev"
Requires-Dist: pytest-coverage; extra == "dev"
Provides-Extra: docs
Requires-Dist: Ipython; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Provides-Extra: analysis
Requires-Dist: codecarbon>=2.8.3; extra == "analysis"
Requires-Dist: ultralytics-thop>=2.0.14; extra == "analysis"
Dynamic: license-file

# Minerva

[![Continuous Test](https://github.com/discovery-unicamp/Minerva-Dev/actions/workflows/continuous-testing.yml/badge.svg)](https://github.com/discovery-unicamp/Minerva/actions/workflows/python-app.yml)

[![Release to PyPI](https://github.com/discovery-unicamp/Minerva/actions/workflows/release_to_pypi.yml/badge.svg)](https://github.com/discovery-unicamp/Minerva/actions/workflows/release_to_pypi.yml)

Minerva is a Pytorch-Lightning-based framework for training machine learning models for researchers.
Check documentation and examples in [Minerva Documentation](https://discovery-unicamp.github.io/Minerva/).

## Description

This project aims to provide a robust and flexible framework for researchers working on machine learning projects. It includes various utilities and modules for data transformation, model creation, analysis metrics, and reproducibility. Minerva is designed to be modular and extensible, allowing researchers to easily add new features and functionalities.

### Features

Minerva offers a wide range of features to help you with your machine learning projects:

- **Model Creation**: Minerva offers a variety of models and architectures to choose from.
- **Training and Evaluation**: Minerva provides tools to train and evaluate your models, including loss functions, optimizers, and evaluation metrics.
- **Data Transformation**: Minerva provides tools to preprocess and transform your data, including data loaders, data augmentation, and data normalization.
- **Modular Design**: Minerva is designed to be modular and extensible, allowing you to easily add new features and functionalities.
- **Reproducibility**: Minerva ensures reproducibility by providing tools for versioning, configuration, and logging of experiments.
- **Self-Supervised Learning (SSL) Support**: Minerva supports Self-Supervised Learning (SSL) for training models with limited labeled data.
- **Development Environment**: Minerva provides a development environment with all dependencies pre-installed and configured for you.

### Near Future Features

- **Hyperparameter Optimization**: Minerva will offer tools for hyperparameter optimization powered by Ray Tune.
- **PyPI Package**: Minerva will be available as a PyPI package for easy installation.
- **Pre-trained Models**: Minerva will offer pre-trained models for common tasks and datasets.
- **Experiment Management**: Minerva will offer tools for managing and tracking experiments using well-known tools like MLflow.

## Installation

Minerva is currently under development and not yet available as a PyPI package. You can install it:
- Locally, as any other Python package.
- Using a Docker container, if you want to use the development environment.

### Install With pip
```bash
pip install minerva-ml
```

### Install Locally

1. Clone the repository:

```bash
git clone https://github.com/discovery-unicamp/Minerva.git
```

2. And then navigate to the project directory and install the dependencies:

```bash
cd Minerva
pip install .
```


### VSCode Development Environment using DevContainer

Check the [Using Minerva DevContainer for developing with Minerva](.devcontainer/README.md) guide for instructions on how to set up a development environment using Visual Studio Code and Docker.

## Modules

Once installed, Minerva is just like any other Python package. You can import its modules and classes in your Python code using:

```python
import minerva
```

The main modules available in Minerva are:
- `minerva.analysis`: Tools for analyzing and visualizing model performance.
- `minerva.callback`: Callbacks for monitoring and logging training progress (Pytorch-Lightning based).
- `minerva.data`: Readers, Datasets and Data Modules.
- `minerva.losses`: Loss functions.
- `minerva.models`: Models and Architectures for supervised and self-supervised learning. Check out the available models and SSL techniques at [minerva.models README.md file](minerva/models/README.md).
- `minerva.pipeline`: Tools for training and evaluating models in a reproducible way.
- `minerva.samplers`: Data samplers to allow for more complex sampling strategies during data loading.
- `minerva.transforms`: Data transformations and augmentations.
- `minerva.utils`: Utility functions and classes.

## Usage

For more information on how to use Minerva, check the [documentation for example notebooks](docs/notebooks).


## Testing

To run the tests, you must install the development dependencies:

```bash
pip install -e .[dev]
```

### Unit Tests

Then, you can run the tests using the following command:

```bash
pytest tests/
```

### Coverage

To generate a coverage report (in HTML), you can use the following command:

```bash
pytest --cov=minerva --cov=tests --cov-report=term --cov-report=html
```


## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Contact

For any questions or concerns, please open an issue on our [GitHub issue tracker](https://github.com/discovery-unicamp/Minerva/issues).

## Contribute

If you want to contribute to this project make sure to read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing guide](CONTRIBUTING.md) pages.

## Acknowledgements

This project is maintained by Gabriel Gutierrez, Otávio Napoli, Fernando Gubitoso Marques, and Edson Borin.
