Python API¶

The public Python API consists of two classes, Model and Catalog. They mirror the CLI commands, with the same options, defaults and checks. They print nothing unless verbose=True is given, never prompt or end the process, and raise an ErsiliaError subclass when something goes wrong.

from ersilia.api import Model

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

Model¶

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

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.

Catalog¶

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

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