lamindb.Run

class lamindb.Run(transform: Transform, name: str | None = None, params: dict | None = None, 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.

  • 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 run parameters

Attributes

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

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.

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

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:

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

Return type:

SQLRecord

See also

Examples

ulabel = ln.ULabel.get("FvtpPJLJ")
ulabel = ln.ULabel.get(name="my-label")
classmethod to_dataframe(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.to_dataframe(include="created_by__name"])

Include display of features for Artifact:

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

Only include select features:

>>> df = 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

>>> ulabels = ln.ULabel.from_values(["ULabel1", "ULabel2", "ULabel3"], field="name")
>>> ln.save(ulabels)
>>> ln.ULabel.search("ULabel2")
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 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

restore()

Restore from trash onto the main branch.

Return type:

None

delete(permanent=None, **kwargs)

Delete record.

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)

get_deferred_fields()

Return a set containing names of deferred fields for this instance.

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)
serializable_value(field_name)

Return the value of the field name for this instance. If the field is a foreign key, return the id value instead of the object. If there’s no Field object with this name on the model, return the model attribute’s value.

Used to serialize a field’s value (in the serializer, or form output, for example). Normally, you would just access the attribute directly and not use this method.

async asave(*args, force_insert=False, force_update=False, using=None, update_fields=None)
save_base(raw=False, force_insert=False, force_update=False, using=None, update_fields=None)

Handle the parts of saving which should be done only once per save, yet need to be done in raw saves, too. This includes some sanity checks and signal sending.

The ‘raw’ argument is telling save_base not to save any parent models and not to do any changes to the values before save. This is used by fixture loading.

async adelete(using=None, keep_parents=False)
prepare_database_save(field)
clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

validate_unique(exclude=None)

Check unique constraints on the model and raise ValidationError if any failed.

date_error_message(lookup_type, field_name, unique_for)
unique_error_message(model_class, unique_check)
get_constraints()
validate_constraints(exclude=None)
clean_fields(exclude=None)

Clean all fields and raise a ValidationError containing a dict of all validation errors if any occur.