lamindb.Run¶

class lamindb.Run(transform: Transform, reference: str | None = None, reference_type: str | None = None)¶

Bases: SQLRecord

Runs of transforms such as the execution of a script.

A registry to store runs of transforms, such as an executation of a script.

Parameters:

transform – Transform A Transform record.
reference – str | None = None For instance, an external ID or a download URL.
reference_type – str | None = None For instance, redun_id, nextflow_id or url.

See also

track(): Track global runs & transforms for a notebook or script.

Examples

Create a run record:

>>> ln.Transform(key="Cell Ranger", version="7.2.0", type="pipeline").save()
>>> transform = ln.Transform.get(key="Cell Ranger", version="7.2.0")
>>> run = ln.Run(transform)

Create a global run context for a custom transform:

>>> ln.track(transform=transform)
>>> ln.context.run  # globally available run

Track a global run context for a notebook or script:

>>> ln.track()  # Jupyter notebook metadata is automatically parsed
>>> ln.context.run

Attributes¶

property features: FeatureManager¶

Features manager.

Run parameters are tracked via the Feature registry, just like all other variables.

Guide: Track run parameters

Example:

run.features.add_values({
    "learning_rate": 0.01,
    "input_dir": "s3://my-bucket/mydataset",
    "downsample": True,
    "preprocess_params": {
        "normalization_type": "cool",
        "subset_highlyvariable": True,
    },
})

Simple fields¶

uid: str¶: Universal id, valid across DB instances.

name: str | None¶: A name.

started_at: datetime¶: Start time of run.

finished_at: datetime | None¶: Finished time of run.

reference: str | None¶: A reference like a URL or external ID (such as from a workflow manager).

reference_type: str | None¶: Type of reference such as a workflow manager execution ID.

created_at: datetime¶: Time of first creation. Mismatches started_at if the run is re-run.

Relational fields¶

branch: Branch¶: Whether record is on a branch or in another “special state”.

space: Space¶: The space in which the record lives.

transform: Transform¶: The transform Transform that is being run.

report: Artifact | None¶: Report of run, e.g.. n html file.

environment: Artifact | None¶

Computational environment for the run.

For instance, Dockerfile, docker image, requirements.txt, environment.yml, etc.

created_by: User¶: Creator of run.

initiated_by_run: Run | None¶

The run that triggered the current run.

This is not a preceding run. The preceding runs (“predecessors”) is the set of runs that produced the output artifacts that serve as the inputs for the present run.

ulabels: ULabel¶: ULabel annotations of this transform.

initiated_runs: Run¶: Runs that were initiated by this run.

output_artifacts: Artifact¶

The artifacts generated by this run.

Related accessor: via run

input_artifacts: Artifact¶

The artifacts serving as input for this run.

Related accessor: input_of_runs.

output_collections: Collection¶: The collections generated by this run.

input_collections: Collection¶: The collections serving as input for this run.

records¶

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

projects: Project¶: Linked projects.

Class methods¶

classmethod df(include=None, features=False, limit=100)¶

Convert to pd.DataFrame.

By default, shows all direct fields, except updated_at.

Use arguments include or feature to include other data.

Parameters:

include (str | list[str] | None, default: None) – Related fields to include as columns. Takes strings of form "ulabels__name", "cell_types__name", etc. or a list of such strings.
features (bool | list[str], default: False) – If True, map all features of the Feature registry onto the resulting DataFrame. Only available for Artifact.
limit (int, default: 100) – Maximum number of rows to display from a Pandas DataFrame. Defaults to 100 to reduce database load.

Return type:

DataFrame

Examples

Include the name of the creator in the DataFrame:

>>> ln.ULabel.df(include="created_by__name"])

Include display of features for Artifact:

>>> df = ln.Artifact.df(features=True)
>>> ln.view(df)  # visualize with type annotations

Only include select features:

>>> df = ln.Artifact.df(features=["cell_type_by_expert", "cell_type_by_model"])

classmethod filter(*queries, **expressions)¶

Query a set of artifacts.

Parameters:

*queries – Q expressions.
**expressions – Params, fields, and values passed via the Django query syntax.

Return type:

QuerySet

See also

Guide: Query & search registries

Examples

Query by fields:

ln.Run.filter(key="examples/my_file.parquet")

Query by params:

ln.Run.filter(hyperparam_x=100)

classmethod get(idlike=None, **expressions)¶

Get a single record.

Parameters:

idlike (int | str | None, default: None) – Either a uid stub, uid or an integer id.
expressions – Fields and values passed as Django query expressions.

Raises:

lamindb.errors.DoesNotExist – In case no matching record is found.

Return type:

SQLRecord

See also

Guide: Query & search registries
Django documentation: Queries

Examples

ulabel = ln.ULabel.get("FvtpPJLJ")
ulabel = ln.ULabel.get(name="my-label")

classmethod lookup(field=None, return_field=None)¶

Return an auto-complete object for a field.

Parameters:

field (str | DeferredAttribute | None, default: None) – The field to look up the values for. Defaults to first string field.
return_field (str | DeferredAttribute | None, default: None) – The field to return. If None, returns the whole record.
keep – When multiple records are found for a lookup, how to return the records. - "first": return the first record. - "last": return the last record. - False: return all records.

Return type:

NamedTuple

Returns:

A NamedTuple of lookup information of the field values with a dictionary converter.

See also

search()

Examples

>>> import bionty as bt
>>> bt.settings.organism = "human"
>>> bt.Gene.from_source(symbol="ADGB-DT").save()
>>> lookup = bt.Gene.lookup()
>>> lookup.adgb_dt
>>> lookup_dict = lookup.dict()
>>> lookup_dict['ADGB-DT']
>>> lookup_by_ensembl_id = bt.Gene.lookup(field="ensembl_gene_id")
>>> genes.ensg00000002745
>>> lookup_return_symbols = bt.Gene.lookup(field="ensembl_gene_id", return_field="symbol")

classmethod search(string, *, field=None, limit=20, case_sensitive=False)¶

Search.

Parameters:

string (str) – The input string to match against the field ontology values.
field (str | DeferredAttribute | None, default: None) – The field or fields to search. Search all string fields by default.
limit (int | None, default: 20) – Maximum amount of top results to return.
case_sensitive (bool, default: False) – Whether the match is case sensitive.

Return type:

QuerySet

Returns:

A sorted DataFrame of search results with a score in column score. If return_queryset is True. QuerySet.

See also

filter() lookup()

Examples

>>> ulabels = ln.ULabel.from_values(["ULabel1", "ULabel2", "ULabel3"], field="name")
>>> ln.save(ulabels)
>>> ln.ULabel.search("ULabel2")

classmethod using(instance)¶

Use a non-default LaminDB instance.

Parameters:: instance (str | None) – An instance identifier of form “account_handle/instance_name”.
Return type:: QuerySet

Examples

>>> ln.ULabel.using("account_handle/instance_name").search("ULabel7", field="name")
            uid    score
name
ULabel7  g7Hk9b2v  100.0
ULabel5  t4Jm6s0q   75.0
ULabel6  r2Xw8p1z   75.0

Methods¶

delete()¶

Delete.

Return type:: None

save(*args, **kwargs)¶

Save.

Always saves to the default database.

Return type:: TypeVar(T, bound= SQLRecord)