The BioMA services toolkit for Python Notebooks and beyond

You can get BioMA and code your own models in C# or you can use the online ready-made ones hosted by AnaEE and CREA, needless to say, if you are not planning to re-invent the wheel, but you just need some quick simulation, the second option is the most straightpforard, as it removes the need for a local installation, i.e. you don't need to download, install, and configure any additional software.

What does this do?

This package provides a simple wrapper over the BioMA cloud installations, sparing the Python user the hassle of getting through the API specification, and abstracting over BioMA formats.

To get a response from teh BioMA cloud APIs, you will need an API key, which is free, but you'll have to register either here or here to get one.

Why should I use it?

Because it wraps the BioMA web APIs in a pythonic way, sparing you the hassle of writing a lot of network code.

Setup

Firstly, you need to install this package into your local environment with:

pip install bioma-modelling

The package expects a service key to work, you can ge tone for free as there exist BioMA cloud public distributions, currently public accessible instances are:

• the one hosted by AnaEE
• the one hosted by CREA

Private instances exist as well, and unless the owner of said instances committed heresy customized the original interfaces, this packages hould work for them as well.

By default, the package exptects you to store the key in a environmental varliable named BIOMA_API_KEY, however, you can hard code it into the ModelClient object instantiation and/or tell it to read it from a different environmental variable of your choice.

You can, of course, avoid defining an actual environmental variable by using tools such as dotenv.

Quickstart

The ModelClient client object allows you to communicate with the BioMA Cloud instance, to create it, just pass it the base address of your BioMA instance of choice.

from biomatools.clients import ModelClient

client = ModelClient('https://api.progettoagridigit.it/model/v1/')

The client allows you to interact with the BioMA cloud instance and to interactively build your model run request. See the attached notebooks for working examples.

Run a model

Once you are happy with your model configuration, you can load it into the client like this:

client.add_model_run('test', model_run)

You can load as many as you like, as long as you assign them different labels, then you can run them all with the run_all method or one by one with the run method that expects the label of the model configuration you'd like to run.

result = client.run('test')

The returned object can easily be transformed into a data frame.

result.get_data_table('weather').to_df()

Acknowledgements

This project is funded by the Agro-Serv project. The project received funding from the European Union under grant agreement No 101058020.