[![PyPI Install](https://img.shields.io/pypi/v/spirepy.svg)](https://pypi.org/project/spirepy/)
[![Test Status](https://github.com/BigDataBiology/SPIREpy/actions/workflows/python-package.yml/badge.svg)](https://github.com/BigDataBiology/SPIREpy/actions/workflows/python-package.yml)
[![Documentation Status](https://readthedocs.org/projects/spirepy/badge/?version=latest)](https://spirepy.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

# SPIREpy

<!--toc:start-->
- [SPIREpy](#spirepy)
  - [Installation](#installation)
  - [Quickstart](#quickstart)
  - [Documentation](#documentation)
  - [Credits](#credits)
<!--toc:end-->

SPIREpy is a Python package and command-line tool that allows users to interact
with the [SPIRE](https://spire.embl.de/) database in a more convinient way.

## Installation

SPIREpy is available on PyPI and can be installed via

```{bash}
pip install spirepy  
```

## Quickstart

### Python package

The Python package encapsulates the study and samples types from SPIRE into
classes with properties that allow you to access and interact with their data.
To load a study, we do:

```{python}
from spirepy import Study

study = Study("Lloyd-Price_2019_HMP2IBD")
```

We can then obtain the list of samples that belong to this study.

```{python}
study.get_samples()  
```

The study's metadata:

```{python}
study.get_metadata()
```

Or even the assembled genomes:

```{python}
study.get_mags()
```

Likewise, many of these attributes and operations are parallel to samples
(`Sample` class) as well. For the full documentation and how to interact with
them, see [here](#documentation)

### Command-line tool

The command-line interface tool allows the interaction with data from SPIRE directly in the terminal. It possesses 2 main interfaces:

- `view`
- `download`

These 2 sub-commands allows us to print tables and download data from both studies and samples. For more information on the available commands use:

```{bash}
spire --help
```

 To view a study's metadata we can use:

```{bash}
spire --study view metadata Lloyd-Price_2019_HMP2IBD
```

And to download the same table as a `.csv` file we can instead:

```{bash}
spire --study download metadata Lloyd-Price_2019_HMP2IBD -o study/
``` 

## Documentation

Documentation for the Python package and CLI tool can be found [here](https://spirepy.readthedocs.io/en/latest/).

## Credits

These tools have been developed by the [Big Data Biology
Lab](https://www.big-data-biology.org/) at the [Centre for Microbiome
Research](https://research.qut.edu.au/cmr/) at the [Queensland University
of Technology](https://www.qut.edu.au/) (Brisbane, Australia). It
is part of the [SPIRE: a Searchable, Planetary-scale mIcrobiome
REsource](https://spire.embl.de/) project.


SPIRE is published in

```{}
Thomas S B Schmidt, Anthony Fullam, Pamela Ferretti, Askarbek Orakov, Oleksandr
M Maistrenko, Hans-Joachim Ruscheweyh, Ivica Letunic, Yiqian Duan, Thea Van
Rossum, Shinichi Sunagawa, Daniel R Mende, Robert D Finn, Michael Kuhn, Luis
Pedro Coelho, Peer Bork, SPIRE: a Searchable, Planetary-scale mIcrobiome
REsource, Nucleic Acids Research, Volume 52, Issue D1, 5 January 2024, Pages
D777–D783
https://doi.org/10.1093/nar/gkad943
```

Please cite this publication when referencing SPIREpy.
