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:

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:

$ 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:

$ 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:

$ 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.

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.

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