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¶

DoesNotExist = <class 'lamindb.models.run.Run.DoesNotExist'>¶

Meta = <class 'lamindb.models.sqlrecord.SQLRecord.Meta'>¶

MultipleObjectsReturned = <class 'lamindb.models.run.Run.MultipleObjectsReturned'>¶

branch: int¶

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

This dictates where a record appears in exploration, queries & searches, whether a record can be edited, and whether a record acts as a template.

Branch name coding is handled through LaminHub. “Special state” coding is as defined below.

One should note that there is no “main” branch as in git, but that all five special codes (-1, 0, 1, 2, 3) act as sub-specfications for what git would call the main branch. This also means that for records that live on a branch only the “default state” exists. E.g., one can only turn a record into a template, lock it, archive it, or trash it once it’s merged onto the main branch.

3: template (hidden in queries & searches)
2: locked (same as default, but locked for edits except for space admins)
1: default (visible in queries & searches)
0: archive (hidden, meant to be kept, locked for edits for everyone)
-1: trash (hidden, scheduled for deletion)

An integer higher than >3 codes a branch that can be used for collaborators to create drafts that can be merged onto the main branch in an experience akin to a Pull Request. The mapping onto a semantic branch name is handled through LaminHub.

branch_id¶

created_by: User¶: Creator of run.

created_by_id¶

environment: Artifact | None¶

Computational environment for the run.

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

environment_id¶

features(host): FeatureManager = <class 'lamindb.models.run.FeatureManagerRun'>¶

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,
    },
})

Attributes¶

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(**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:

TypeVar(T, bound= SQLRecord)

See also

Guide: Query & search registries
Django documentation: Queries

Examples

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

Methods¶

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.

initiated_by_run_id¶

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

input_artifacts: Artifact¶

The artifacts serving as input for this run.

Related accessor: input_of_runs.

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

links_featurevalue¶

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

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

links_project¶

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

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

links_record¶

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

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

links_ulabel¶

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

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

objects = <lamindb.models.query_manager.QueryManager object>¶

output_artifacts: Artifact¶

The artifacts generated by this run.

Related accessor: via run

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

property pk¶

projects: Project¶: Linked projects.

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.

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

report_id¶

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

space_id¶

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

transform_id¶

ulabels: ULabel¶: ULabel annotations of this transform.

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)

Methods¶

async adelete(using=None, keep_parents=False)¶

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

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

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.

clean_fields(exclude=None)¶: Clean all fields and raise a ValidationError containing a dict of all validation errors if any occur.

date_error_message(lookup_type, field_name, unique_for)¶

delete()¶

Delete.

Return type:: None

get_constraints()¶

get_deferred_fields()¶: Return a set containing names of deferred fields for this instance.

prepare_database_save(field)¶

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.

save(*args, **kwargs)¶

Save.

Always saves to the default database.

Return type:: SQLRecord

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.

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.

unique_error_message(model_class, unique_check)¶

validate_constraints(exclude=None)¶

validate_unique(exclude=None)¶: Check unique constraints on the model and raise ValidationError if any failed.