agrobiota-sdk 0.1.0a10
An official SDK library for the AGROBIOTA environment
License: MIT
Requires Python: <4.0,>=3.12
Keywords: Bioinformatics, AGROBIOTA, SDK

# AGROBIOTA SDK

This package contains the code for the Agrobiota Environment.

## Usage

The AGROBIOTA SDK simplifies the integration and transformation of AGROBIOTA
data. It is available for Python 3.12+ and can be installed using pip:

```bash
python3.12 -m pip install agrobiota-sdk
```

It can be used through a CLI or as a Python library.

### CLI

To discover the available options in the AGROBIOTA SDK CLI, use the `--help`
option at the root of the project:

```bash
$ agb-sdk --help
                                                                
 Usage: agb-sdk [OPTIONS] COMMAND [ARGS]...                     
                                                                
 Agrobiota SDK CLI                                              
                                                                
╭─ Options ────────────────────────────────────────────────────╮
│ --version      Show the version and exit.                    │
│ --help         Show this message and exit.                   │
╰──────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────╮
│ analysis   Operations over analysis from Agroportal API      │
│ convert    Convert data between formats                      │
╰──────────────────────────────────────────────────────────────╯
```

As shown in the example above, the AGROBIOTA SDK CLI has two commands:
`analysis` and `convert`.

The `analysis` command allows viewing analyses and bioindex reports. To see the
available options, simply run the command with the `--help` option:

```bash
$ agb-sdk analysis list --help
                                                                            
 Usage: agb-sdk analysis list [OPTIONS] [REPORT_ID]                         
                                                                            
╭─ Options ────────────────────────────────────────────────────────────────╮
│ --connection-string        TEXT     The connection string to the         │
│                                     Agroportal API.                      │
│                                     [env var: AGB_CONNECTION_STRING]     │
│ --term                -t   TEXT     The term to search for in the        │
│                                     analysis.                            │
│ --skip                -sk  INTEGER  The number of records to skip.       │
│                                     [default: 0]                         │
│ --size                -s   INTEGER  The number of records to return.     │
│                                     [default: 25]                        │
│ --save-to-file             PATH     If provided, the analysis will be    │
│                                     saved to a file. This option is only │
│                                     available when the Biotrop Bioindex  │
│                                     is provided.                         │
│ --stdout-json         -j            If true, the analysis will be        │
│                                     printed to the console as JSON. This │
│                                     command should be used when the      │
│                                     `REPORT_ID` parameter is provided.   │
│ --resolve-taxonomies                If true, the taxonomies will be      │
│                                     resolved from the taxonomy service.  │
│                                     Otherwise the TaxID values will be   │
│                                     used as is. This command should be   │
│                                     used when the `REPORT_ID` parameter  │
│                                     is provided.                         │
│                                     [default: True]                      │
│ --taxonomy-url             TEXT     The URL to the taxonomy service.     │
│                                     This command should be used when the │
│                                     `REPORT_ID` parameter is provided.   │
│                                     [default:                            │
│                                     https://dev.api.agrobiota.biotrop.a… │
│ --help                              Show this message and exit.          │
╰──────────────────────────────────────────────────────────────────────────╯
```

Note that the `list` command uses the `--connection-string` parameter to connect
to the Agroportal API. This parameter can be omitted if the
`AGB_CONNECTION_STRING` environment variable is set.

The `list` command also has a `REPORT_ID` parameter. This parameter is used to
specify the report ID to be viewed. If this parameter is not provided, the
command will print the bioindex details as a simple list of tables included in
the results, or if the parameter `--save-to-file` is provided, the command will
save the bioindex details to a file.

Note also the `--stdout-json`, `--resolve-taxonomies` and `--taxonomy-url`
options. They are used to resolve the taxonomies of the results, when the
`REPORT_ID` parameter is provided.

The `--resolve-taxonomies` option is used to resolve the taxonomies of the
results, when the `REPORT_ID` parameter is provided. The `--taxonomy-url` option
is used to specify the URL to the taxonomy service.

---

The AGROBIOTA SDK CLI can be used to convert data between formats and perform
other tasks. To do this, run the following command:

```bash
$ agb-sdk convert bioindex-to-tabular --help
                                                                            
 Usage: agb-sdk convert bioindex-to-tabular [OPTIONS] INPUT_PATH OUTPUT_PATH
                                                                            
╭─ Options ────────────────────────────────────────────────────────────────╮
│ --resolve-taxonomies          If true, the taxonomies will be resolved   │
│                               from the taxonomy service. Otherwise the   │
│                               TaxID values will be used as is. This      │
│                               command should be used when the            │
│                               `REPORT_ID` parameter is provided.         │
│                               [default: True]                            │
│ --taxonomy-url          TEXT  The URL to the taxonomy service. This      │
│                               command should be used when the            │
│                               `REPORT_ID` parameter is provided.         │
│                               [default:                                  │
│                               https://dev.api.agrobiota.biotrop.agr.br/… │
│ --help                        Show this message and exit.                │
╰──────────────────────────────────────────────────────────────────────────╯
```

The `bioindex-to-tabular` command converts a bioindex to a tabular format. The
input is a JSON file with the bioindex data and the output is an Excel file with
the converted data.

### Python

The AGROBIOTA SDK can also be used as a Python library. To do this, import the
SDK and use the available functions.

```python
from agb_sdk.core.use_cases import convert_bioindex_to_tabular

(
    info_data_frame,
    by_sample_data_frame,
    by_dimension_data_frame,
    by_process_data_frame,
    diversity_data_frame,
    community_composition_data_frame,
) = await convert_bioindex_to_tabular(
    input_path="input.json",
    output_path="output.xlsx",
    resolve_taxonomies=True,
)
```

Note that the `convert_bioindex_to_tabular` function is asynchronous, then, you
need to use the `await` keyword to call it. The function outputs six DataFrames
with the converted data, which can be used as needed. The content of the
DataFrames is the same as the one returned by the CLI command, but into a
Pythonic format.

> [!IMPORTANT]
> The library is constantly evolving and new features are being added. If you
> have any suggestions or feedback, please open an
> [issue](https://github.com/agrobiota/agrobiota-sdk/issues) or contact us
> via email at [bioinfo@biotrop.com.br](mailto:bioinfo@biotrop.com.br).

---

This SDK was tested in Linux. It may work in other operating systems, but this
is not guaranteed. For windows, we recommend using WSL (Windows Subsystem for
Linux).