lamindb.Run¶

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.
name – str | None = None An optional name.
params – dict | None = None A dictionary of parameters.
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.
initiated_by_run – Run | None = None The run that triggers this run.

See also

track(): Globally track a script or notebook run.
tracked(): Track a function with this decorator.

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  # global run

Track a global run context for a notebook or script:

ln.track()
ln.context.run  # global run

You can pass parameters to Run(transform, params=params) or add them later:

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

In contrast to .params, features are indexed in the Feature registry and can reference relational categorical values. If you want to link feature values, use:

run.features.add_values({
    "experiment": "My experiment 1",
})

Guide: Track parameters & features

Attributes¶

property cli_args: str | None¶: CLI arguments if the run was invoked from the command line.

property features: FeatureManager¶: Manage annotations with features.

property status: str¶

Get status of run.

Returns the status as a string, one of: scheduled, re-started, started, completed, errored, or aborted.

Examples

See the status of a run:

run.status
#> 'completed'

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.

params: dict¶: JSON-like parameters.

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.

is_locked: bool¶: Whether the record is locked for edits.

Relational fields¶

branch: Branch¶

Life cycle state of record.

branch.name can be “main” (default branch), “trash” (trash), branch.name = "archive" (archived), or any other user-created branch typically planned for merging onto main after review.

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.

linked_in_records: Record¶: This run is linked in these records as a value.

artifacts: Artifact¶: The artifacts annotated by this run.

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.

output_records: Record¶: The collections generated by this run.

input_records: Record¶: The collections serving as input for this run.

records: Record¶: Records that annotate this run.

projects: Project¶: Linked projects.

blocks: RunBlock¶: Blocks that annotate this run.

Class methods¶

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

record = ln.Record.get("FvtpPJLJ")
record = ln.Record.get(name="my-label")

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

Evaluate and convert to pd.DataFrame.

By default, maps simple fields and foreign keys onto DataFrame columns.

Guide: Query & search registries

Parameters:

include (str | list[str] | None, default: None) – Related data to include as columns. Takes strings of form "records__name", "cell_types__name", etc. or a list of such strings. For Artifact, Record, and Run, can also pass "features" to include features with data types pointing to entities in the core schema. If "privates", includes private fields (fields starting with _).
features (bool | list[str], default: False) – Configure the features to include. Can be a feature name or a list of such names. If "queryset", infers the features used within the current queryset. Only available for Artifact, Record, and Run.
limit (int, default: 100) – Maximum number of rows to display. If None, includes all results.
order_by – Field name to order the records by. Prefix with ‘-’ for descending order. Defaults to ‘-id’ to get the most recent records. This argument is ignored if the queryset is already ordered or if the specified field does not exist.

Return type:

DataFrame

Examples

Include the name of the creator:

ln.Record.to_dataframe(include="created_by__name"])

Include features:

ln.Artifact.to_dataframe(include="features")

Include selected features:

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

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

records = ln.Record.from_values(["Label1", "Label2", "Label3"], field="name").save()
ln.Record.search("Label2")

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

Lookup via auto-complete on .:

import bionty as bt
bt.Gene.from_source(symbol="ADGB-DT").save()
lookup = bt.Gene.lookup()
lookup.adgb_dt

Look up via auto-complete in dictionary:

lookup_dict = lookup.dict()
lookup_dict['ADGB-DT']

Look up via a specific field:

lookup_by_ensembl_id = bt.Gene.lookup(field="ensembl_gene_id")
genes.ensg00000002745

Return a specific field value instead of the full record:

lookup_return_symbols = bt.Gene.lookup(field="ensembl_gene_id", return_field="symbol")

classmethod connect(instance)¶

Query a non-default LaminDB instance.

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

Examples

ln.Record.connect("account_handle/instance_name").search("label7", field="name")

Methods¶

describe(return_str=False)¶

Describe record including relations.

Parameters:: return_str (bool, default: False) – Return a string instead of printing.
Return type:: None | str

restore()¶

Restore from trash onto the main branch.

Does not restore descendant records if the record is HasType with is_type = True.

Return type:: None

delete(permanent=None, **kwargs)¶

Delete record.

If record is HasType with is_type = True, deletes all descendant records, too.

Parameters:: permanent (bool | None, default: None) – Whether to permanently delete the record (skips trash). If None, performs soft delete if the record is not already in the trash.
Return type:: None

Examples

For any SQLRecord object record, call:

>>> record.delete()

save(*args, **kwargs)¶

Save.

Always saves to the default database.

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

refresh_from_db(using=None, fields=None, from_queryset=None)¶

Reload field values from the database.

By default, the reloading happens from the database this instance was loaded from, or by the read router if this instance wasn’t loaded from any database. The using parameter will override the default.

Fields can be used to specify which fields to reload. The fields should be an iterable of field attnames. If fields is None, then all non-deferred fields are reloaded.

When accessing deferred fields of an instance, the deferred loading of the field will call this method.

async arefresh_from_db(using=None, fields=None, from_queryset=None)¶