lamindb.Run¶

class lamindb.Run(transform: Transform, reference: str | None = None, reference_type: str | None = None, initiated_by_run: Run | 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.
initiated_by_run – Run | None = None The run that triggers this run.
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(): Globally track a script or notebook run.

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.

output_records: Record¶: The collections generated by 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.

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

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 a list of feature names, filters Feature down to these features. If True, prints all features with dtypes in the core schema module. If "queryset", infers the features used within the set of artifacts or records. Only available for Artifact and Record.
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)