ersilia.api package¶

Submodules¶

ersilia.api.create_api module¶

The Ersilia Python API.

Model and Catalog mirror the CLI commands (ersilia fetch, serve, run, info, example, close, delete and catalog), with the same options, defaults and rules. As a library, they print nothing unless verbose=True, never prompt, never end the process, and raise an ErsiliaError subclass when something goes wrong.

class ersilia.api.create_api.Catalog(verbose=False)[source]¶

Bases: object

The Ersilia Model Hub catalog, like ersilia catalog.

Parameters:: verbose (bool, optional) – Show the same progress lines as the CLI. By default nothing is printed.

Examples

from ersilia.api import Catalog

catalog = Catalog()
hub = catalog.hub(task="Annotation")
local = catalog.local()
card = catalog.card("eos4e40")

card(model, output=None)[source]¶

Get a model’s card, like ersilia catalog --card MODEL.

Parameters:

model (str) – Model identifier or slug.
output (str, optional) – Also write the card to a .json or .csv file.

Returns:

The model card.

Return type:

dict

Raises:

InvalidModelIdentifierError – If the model is not in the Ersilia Model Hub (with suggestions).

hub(more=False, task=None, output=None)[source]¶

List the models in the Ersilia Model Hub, like ersilia catalog --hub.

Parameters:

more (bool, optional) – Include more columns.
task (str, optional) – Only “Annotation”, “Representation” or “Sampling” models.
output (str, optional) – Also write the catalog to a .csv or .json file.

Returns:

One row per model.

Return type:

pandas.DataFrame

local(more=False, task=None, output=None)[source]¶

List the models fetched on this computer, like ersilia catalog.

Parameters:

more (bool, optional) – Include more columns.
task (str, optional) – Only “Annotation”, “Representation” or “Sampling” models.
output (str, optional) – Also write the catalog to a .csv or .json file.

Returns:

One row per model; empty if no model is fetched.

Return type:

pandas.DataFrame

class ersilia.api.create_api.Model(model, verbose=False)[source]¶

Bases: object

An Ersilia model, identified by its identifier or slug.

Parameters:

model (str) – Model identifier (e.g. "eos4e40") or slug (e.g. "chemprop-antibiotic").
verbose (bool, optional) – Show the same progress lines as the CLI. By default nothing is printed.

model_id¶

The model identifier.

Type:: str

slug¶

The model slug.

Type:: str

Raises:: InvalidModelIdentifierError – If the model is not in the Ersilia Model Hub.

Examples

from ersilia.api import Model

model = Model("eos4e40")
model.fetch()
model.serve()
df = model.run(["CCO", "c1ccccc1"])
model.close()

# Or serve and close automatically:
with Model("eos4e40") as model:
    df = model.run("input.csv")

close()[source]¶

Close the served model, like ersilia close.

Returns:

True if the model was closed (also when it had already stopped), False if no model is served in this session, so there was nothing to close. A session named with ERSILIA_SESSION is removed.

Return type:

bool

Raises:

ModelNotServedError – If another model is served in this session.
DockerNotActiveError – If the model runs in Docker and Docker is not running.

delete()[source]¶

Delete the model from this computer, like ersilia delete.

Raises:

ModelNotAvailableLocallyError – If the model is not fetched.
ModelNotDeletableError – If the model cannot be deleted: it is served in this session or another one, or Docker is not running.

example(n_samples=5, mode='random', output=None)[source]¶

Generate example inputs for the model, like ersilia example.

The model must be fetched; it does not need to be served.

Parameters:

n_samples (int, optional) – Number of examples (ignored in “curated” mode).
mode (str, optional) – “random”, “curated” (the model’s own examples) or “deterministic”.
output (str, optional) – Also write the examples to this CSV file.

Returns:

The example inputs.

Return type:

list of str

Raises:

ModelNotAvailableLocallyError – If the model is not fetched.
InvalidOptionError – For an unknown mode, fewer than 1 example, a missing output folder, or curated mode on a model without curated examples.

fetch(from_dir=None, from_github=False, from_s3=False, from_hosted=None, version=None)[source]¶

Fetch the model, like ersilia fetch.

By default the model is fetched from DockerHub. Give one of the other sources to fetch it from there instead.

Parameters:

from_dir (str, optional) – Fetch from a local copy of the model repository.
from_github (bool, optional) – Fetch from GitHub.
from_s3 (bool, optional) – Fetch from Ersilia’s S3 bucket.
from_hosted (str, optional) – URL of a hosted model to connect to.
version (str, optional) – Docker image tag to fetch from DockerHub (default: the latest).

Returns:

True if the model was fetched now, False if it was already fetched.

Return type:

bool

Raises:

ModelFetchError – If the model could not be fetched.

info(output=None)[source]¶

Get the model information, like ersilia info.

The model must be fetched; it does not need to be served.

Parameters:: output (str, optional) – Also write the information to a .json or .csv file.
Returns:: The model information.
Return type:: dict
Raises:: ModelNotAvailableLocallyError – If the model is not fetched.

is_fetched()[source]¶

Tell whether the model is fetched.

Returns:: True if the model is available locally.
Return type:: bool

run(input, output=None, batch_size=100)[source]¶

Run the served model, like ersilia run.

Parameters:

input (str or list of str) – A CSV file with one column of inputs, or a list of inputs.
output (str, optional) – A .csv or .h5 file to write the results to. If not given, the results are returned as a DataFrame.
batch_size (int, optional) – Number of inputs sent to the model at a time (at least 1).

Returns:

The results, or the path of output when it is given.

Return type:

pandas.DataFrame or str

Raises:

ModelNotServedError – If this model is not served in this session, or it stopped.
InvalidOptionError – For a problem with the input or output file (the same checks as ersilia run: missing or empty file, several columns, wrong encoding or separator, missing output folder, and so on).
EmptyRunOutputError – If the model produced no output.

serve(port=None, track=False, tracking_use_case='local', enable_cache=False, read_store=False, write_store=False, access=None, nearest_neighbors=False, max_cache_memory_frac=None)[source]¶

Serve the model, like ersilia serve.

Parameters:

port (int, optional) – Port for the model server. By default a free port is used.
track (bool, optional) – Track runs to monitor model and system performance.
tracking_use_case (str, optional) – With track: one of “local”, “self-service”, “hosted” or “test”.
enable_cache (bool, optional) – Cache results in a local Redis store.
read_store (bool, optional) – Read results from, or write them to, the Isaura store.
write_store (bool, optional) – Read results from, or write them to, the Isaura store.
access (str, optional) – “public” or “private”; needed to write to the store.
nearest_neighbors (bool, optional) – Use nearest-neighbor matches when reading from the store.
max_cache_memory_frac (float, optional) – Maximum fraction (0.0-1.0) of system RAM the cache may use.

Returns:

How the model is served, as in the Serving section of ersilia info: model_id, url, docs, service, pid (None for containers), container, session and apis. If the model is already served here, it is not started again and these details are returned.

Return type:

dict

Raises:

ModelNotAvailableLocallyError – If the model is not fetched.
SessionBusyError – If another model is already served in this session.
InvalidOptionError, MissingDependencyError, ModelServeError – For invalid options, a missing Isaura installation, or a failed start.

Module contents¶

The Ersilia Python API: Model and Catalog mirror the CLI commands.

Every error is raised as an ErsiliaError subclass.