lamindb.Run

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

Bases: Record

Runs of transforms.

Parameters:
  • transformTransform A Transform record.

  • referencestr | None = None For instance, an external ID or a download URL.

  • reference_typestr | None = None For instance, redun_id, nextflow_id or url.

See also

track()

Track global run & transform records for a notebook or pipeline.

Notes

See guide: Data lineage.

A run can have inputs and outputs:

  • References to outputs are stored in the run field of registries.

  • References to inputs are stored in the input_of_runs field of Artifact and Collection.

Examples

Create a run record:

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

Create a global run context for a custom transform:

>>> ln.context.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

params: ParamManager

Param manager.

What .features is to dataset-like artifacts, .params is to model-like artifacts.

Annotate with params & values:

artifact.params.add_values({
    "hidden_size": 32,
    "bottleneck_size": 16,
    "batch_size": 32
})

Simple fields

uid: str

Universal id, valid across DB instances.

started_at: datetime

Start time of run.

finished_at: datetime

Finished time of run.

is_consecutive: bool

Indicates whether code was consecutively executed. Is relevant for notebooks.

reference: str

A reference like a URL or external ID (such as from a workflow manager).

reference_type: str

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

transform

The transform Transform that is being run.

report: Artifact

Report of run, e.g.. n html file.

environment: Artifact

Computational environment for the run.

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

created_by: User

Creator of run. User

parent: Run

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.

Be careful with using this field at this point.

children: Run

The runs that are triggered by this run.

output_artifacts: Artifact

The artifacts generated by this run.

input_artifacts: Artifact

The artifacts serving as input for this run.

output_collections: Collection

The collections generated by this run.

input_collections: Collection

The collections serving as input for this run.

Class methods

classmethod df(include=None, join='inner', limit=100)

Convert to pd.DataFrame.

By default, shows all direct fields, except created_at.

If you’d like to include related fields, use parameter include.

Parameters:
  • include (str | list[str] | None, default: None) – Related fields to include as columns. Takes strings of form "labels__name", "cell_types__name", etc. or a list of such strings.

  • join (str, default: 'inner') – The join parameter of pandas.

Return type:

DataFrame

Examples

>>> labels = [ln.ULabel(name="Label {i}") for i in range(3)]
>>> ln.save(labels)
>>> ln.ULabel.filter().df(include=["created_by__name"])
classmethod filter(*queries, **expressions)

Query records.

Parameters:
  • queries – One or multiple Q objects.

  • expressions – Fields and values passed as Django query expressions.

Return type:

QuerySet

Returns:

A QuerySet.

See also

Examples

>>> ln.ULabel(name="my ulabel").save()
>>> ulabel = ln.ULabel.get(name="my ulabel")
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.

Return type:

Record

Returns:

A record.

Raises:

lamindb.core.exceptions.DoesNotExist – In case no matching record is found.

See also

Examples

>>> ulabel = ln.ULabel.get("2riu039")
>>> 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.

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()
Return type:

None

save(*args, **kwargs)

Save.

Always saves to the default database.

Return type:

Record