lamindb.Record ¶

Bases: SQLRecord, HasType, HasParents, CanCurate, TracksRun, TracksUpdates

Structured records with support for notes.

Useful for managing notes, experiments, samples, donors, cells, compounds, sequences, and other custom entities.

A record is one of three kinds:

Record page — a notes page in a hierarchy, which can act like a folder for other records (record.is_page)
Record frame — a schema-validated collection of data records (record.is_frame)
Data record — a simple data record (record.is_data)

Record pages and frames are record types, in analogy to all other entities that inherit from HasType.

Parameters:

name – str | None = None A name.
description – str | None = None A description.
type – Record | None = None The type of this record.
is_type – bool = False Whether this record is a type.
features – dict[str | Feature, Any] | None = None Feature annotations.
schema – Schema | None = None A schema defining allowed features for data records of this type. Only applicable when is_type=True; turns the type into a record frame.
reference – str | None = None For instance, an external ID or a URL.
reference_type – str | None = None For instance, "url".
branch – Branch | None = None A branch. If None, uses the current branch.
space – Space | None = None A space. If None, uses the current space.

See also

Feature: Measurable properties.
Schema: Constrain record frame features; index defines row keys.
ULabel: Simple labels.

Examples¶

Also see the guide: Manage records & ontologies.

Create a data record with a single feature:

# create a feature if you don't yet have one
gc_content = ln.Feature(name="gc_content", dtype=float).save()

# create a data record to track a sample
sample1 = ln.Record(name="Sample 1", features={"gc_content": 0.5}).save()

# describe the data record
sample1.describe()

Group data records under a record type, optionally turning it into a record frame with a Schema:

# create an Experiments record page
experiments = ln.Record(name="Experiments", is_type=True).save()
experiment1 = ln.Record(name="Experiment 1", type=experiments).save()

# create a feature to link experiments
experiment = ln.Feature(name="experiment", dtype=experiments).save()

# create a record frame by constraining a record page with a schema
schema = ln.Schema([experiment, gc_content.with_config(optional=True)], name="sample_schema").save()
samplesheet = ln.Record(name="Samples", is_type=True, schema=schema).save()

# move the data record into the record frame
sample1.type = samplesheet
sample1.save()

# reset the feature values for the data record including the experiment
sample1.features.set_values({gc_content: 0.5,
    experiment: "Experiment 1",  # automatically resolves by name, also accepts the experiment1 object
})

Export all data records of a type to a DataFrame:

experiments.to_dataframe()
#> __lamindb_record_name__   ...
#>            Experiment 1   ...
#>            Experiment 2   ...

Use index on a schema to define row keys:

sample_id = ln.Feature(name="sample_id", dtype=str).save()
score = ln.Feature(name="score", dtype=float).save()
schema = ln.Schema(features=[score], index=sample_id).save()
indexed_frame = ln.Record(name="Indexed samples", is_type=True, schema=schema).save()

record = ln.Record(type=indexed_frame, features={"sample_id": "S-001", "score": 1.5}).save()
assert record.name == "S-001"

df = indexed_frame.to_dataframe()
assert df.index.name == "sample_id"
assert "sample_id" not in df.columns

Import data records from a dataframe from_dataframe():

records = ln.Record.from_dataframe(df, type="my_df").save()  # creates a record frame my_df with inferred schema

If you try to set incomplete features on a data record in a record frame, you’ll get a validation error:

sample2 = ln.Record(name="Sample 2", type=samplesheet).save()
sample2.features.set_values({gc_content: 0.6})  # raises ValidationError because experiment is missing

Query data records by features:

ln.Record.filter(gc_content == 0.55)  # exact match
ln.Record.filter(gc_content > 0.5)    # greater than

Query data records by field:

ln.Record.filter(type=samplesheet)   # just the data records in the record frame

Notes¶

Attributes¶

property features: FeatureManager¶

Manage the linked feature values.

For examples, see Record.

property is_data: bool¶: Whether this record is a data record (not is_type).

property is_frame: bool¶: Whether this record is a record frame (is_type and schema is set).

property is_page: bool¶: Whether this record is a record page (is_type and no schema).

property notes: str | None¶

Notes.

Returns the latest content of an attached block of kind readme.

You can populate it via the UI or via lamin annotate ... --readme README.md.

property settings: SQLRecordSettings¶: Settings.

Simple fields¶

uid: str¶: A universal random id, valid across DB instances.

name: str¶: Name or title of record (optional).

description: str | None¶: A description.

reference: str | None¶: A simple reference like a URL or external ID.

reference_type: str | None¶: Type of simple reference.

extra_data: dict | None¶: Extra data in JSON format, not validated as features.

is_type: bool¶

Indicates if record is a type.

For Record, a type is a record page or record frame. For Feature, ULabel, Schema, and Project, a type is a feature type, ULabel type, schema type, or project type.

For example, if a record “Compound” is a type, the actual compounds “darerinib”, “tramerinib”, would be data records of that type.

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

created_at: datetime¶: Time of creation of record.

updated_at: datetime¶: Time of last update to record.

Relational fields¶

branch: Branch¶: The branch on which the object is defined.

created_on: Branch¶: The branch on which the object was created.

space: Space¶: The space in which the object is defined.

created_by: User¶: The user that created the object.

type: Record | None¶

Type of record, e.g., Sample, Donor, Cell, Compound, Sequence ← records.

Allows to group data records by type, e.g., all samples, all donors, all cells, all compounds, all sequences.

schema: Schema | None¶

A schema to enforce for a record type ← records.

This is analogous to the schema attribute of an Artifact. If is_type is True and a schema is set, this record is a record frame and the schema is used to validate the features of each data record of this type.

run: Run¶: Run that created the record ← output_records.

parents: RelatedManager[Record]¶

Ontological parents of this record ← children.

You can build an ontology under a given type. For example, introduce a type CellType and model the hiearchy of cell types under it via parents and children.

input_of_runs: RelatedManager[Run]¶: Runs that use this record as an input ← input_records.

artifacts: RelatedManager[Artifact]¶: Artifacts annotated by this record ← records.

runs: RelatedManager[Run]¶: Runs annotated by this record ← records.

transforms: RelatedManager[Transform]¶: Transforms annotated by this record ← records.

collections: RelatedManager[Collection]¶: Collections annotated by this record ← records.

records: RelatedManager[Record]¶: If a record type (is_type=True), the data records of this type.

children: RelatedManager[Record]¶: Ontological children of this record. Is reverse accessor for parents.

references: RelatedManager[Reference]¶: References that annotate this record ← records.

projects: RelatedManager[Project]¶: Projects that annotate this record ← records.

ablocks: RelatedManager[RecordBlock]¶: Attached blocks ← record.

linked_records: RelatedManager[Record]¶: Records linked in this record as a value ← linked_in_records.

linked_users: RelatedManager[User]¶: Users linked in this record as values ← linked_in_records.

linked_runs: RelatedManager[Run]¶: Runs linked in this record as values ← linked_in_records.

linked_transforms: RelatedManager[Transform]¶: Transforms linked in this record as values ← linked_in_records.

linked_ulabels: RelatedManager[ULabel]¶: ULabels linked in this record as values ← linked_in_records.

linked_artifacts: RelatedManager[Artifact]¶: Artifacts linked in this record as values ← linked_in_records.

linked_collections: RelatedManager[Collection]¶: Collections linked in this record as values ← linked_in_records.

linked_in_records: RelatedManager[Record]¶: Records linking this record as a value. Is reverse accessor for linked_records.

linked_references: RelatedManager[Reference]¶: References linked in this record as values ← linked_in_records.

linked_projects: RelatedManager[Project]¶: Projects linked in this record as values ← linked_in_records.

values_json: RelatedManager[RecordJson]¶: JSON values (record_id, feature_id, value).

values_record: RelatedManager[RecordRecord]¶: Record values with their features (record_id, feature_id, value_id).

values_ulabel: RelatedManager[RecordULabel]¶: ULabel values with their features (record_id, feature_id, value_id).

values_user: RelatedManager[RecordUser]¶: User values with their features (record_id, feature_id, value_id).

values_run: RelatedManager[RecordRun]¶: Run values with their features (record_id, feature_id, value_id).

values_artifact: RelatedManager[RecordArtifact]¶: Artifact values with their features (record_id, feature_id, value_id).

values_collection: RelatedManager[RecordCollection]¶: Collection values with their features (record_id, feature_id, value_id).

values_transform: RelatedManager[RecordTransform]¶: Transform values with their features (record_id, feature_id, value_id).

values_reference: RelatedManager[RecordReference]¶: Reference values with their features (record_id, feature_id, value_id).

values_project: RelatedManager[RecordProject]¶: Project values with their features (record_id, feature_id, value_id).

Class methods¶

from_dataframe(*, type, name_field='__lamindb_record_name__')¶

Construct a dataframe-backed batch of records for bulk saving.

Returns a RecordBatch. Follow with records.save().

When the target record frame schema defines index, the index feature may be passed on df.index (named after the feature) or as a column.

Parameters:

df (pd.DataFrame) – A dataframe where rows represent data records.
type (Record | str) – Record page or record frame for all rows as either a Record object or a string. If passing a string, a new record frame with that name is created under Imports with an inferred schema from the dataframe. If that type name already exists, raise an error and pass an existing Record object for reuse. If the resolved type is a record frame (type.schema is not None), feature values are validated against that schema at save time.
name_field (str, default: '__lamindb_record_name__') – Column used for data record names when no schema index is configured. Falls back to name if absent. If neither exists, data records are created without names.

Return type:

RecordBatch

Examples

Create a new record frame and import data records:

records = ln.Record.from_dataframe(df, type="my_df").save()

Import data records into an existing record frame:

records = ln.Record.from_dataframe(df, type=samplesheet).save()

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

See also

Guide: Query & search
Django documentation: Queries

Examples

>>> ln.Project(name="my label").save()
>>> ln.Project.filter(name__startswith="my").to_dataframe()

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.ObjectDoesNotExist – In case no matching record is found.

Return type:

SQLRecord

See also

Guide: Query & search
Django documentation: Queries

Examples

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

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.ULabel.from_values(["Label1", "Label2", "Label3"]).save()
ln.ULabel.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")

classmethod inspect(field=None, *, mute=False, organism=None, source=None, from_source=True, strict_source=False)¶

Inspect if values are mappable to a field.

Being mappable means that an exact match exists.

Parameters:

values (ListLike) – Values that will be checked against the field.
field (StrField | None, default: None) – The field of values. Examples are 'ontology_id' to map against the source ID or 'name' to map against the ontologies field names.
mute (bool, default: False) – Whether to mute logging.
organism (Union[str, SQLRecord, None], default: None) – An Organism name or record.
source (SQLRecord | None, default: None) – A bionty.Source record that specifies the version to inspect against.
strict_source (bool, default: False) – Determines the validation behavior against records in the registry. - If False, validation will include all records in the registry, ignoring the specified source. - If True, validation will only include records in the registry that are linked to the specified source. Note: this parameter won’t affect validation against public sources.

Return type:

InspectResult

See also

validate()

Example

Inspect gene symbols:

import bionty as bt

# populate the gene registry
bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol", organism="human").save()

# inspect gene symbols
symbols = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
result = bt.Gene.inspect(symbols, field=bt.Gene.symbol, organism="human")
assert result.validated == ["A1CF", "A1BG"]
assert result.non_validated == ["FANCD1", "FANCD20"]

classmethod validate(field=None, *, mute=False, organism=None, source=None, strict_source=False)¶

Validate values against existing values of a string field.

Note this is strict_source validation, only asserts exact matches.

Parameters:

values (ListLike) – Values that will be validated against the field.
field (StrField | None, default: None) – The field of values. Examples are 'ontology_id' to map against the source ID or 'name' to map against the ontologies field names.
mute (bool, default: False) – Whether to mute logging.
organism (Union[str, SQLRecord, None], default: None) – An Organism name or record.
source (SQLRecord | None, default: None) – A bionty.Source record that specifies the version to validate against.
strict_source (bool, default: False) – Determines the validation behavior against records in the registry. - If False, validation will include all records in the registry, ignoring the specified source. - If True, validation will only include records in the registry that are linked to the specified source. Note: this parameter won’t affect validation against public sources.

Return type:

np.ndarray

Returns:

A vector of booleans indicating if an element is validated.

See also

inspect()

Example

Validate gene symbols:

import bionty as bt

# populate the gene registry
bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol", organism="human").save()

# validate gene symbols
symbols = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
bt.Gene.validate(symbols, field=bt.Gene.symbol, organism="human")
#> array([ True,  True, False, False])

classmethod from_values(field=None, create=False, organism=None, source=None, mute=False)¶

Bulk create validated records by parsing values for an identifier such as a name or an id).

Parameters:

values (ListLike) – A list of values for an identifier, e.g. ["name1", "name2"].
field (StrField | None, default: None) – A SQLRecord field to look up, e.g., bt.CellMarker.name.
create (bool, default: False) – Whether to create records if they don’t exist.
organism (Union[SQLRecord, str, None], default: None) – A bionty.Organism name or record.
source (SQLRecord | None, default: None) – A bionty.Source record to validate against to create records for.
mute (bool, default: False) – Whether to mute logging.

Return type:

SQLRecordList

Returns:

A list of validated records. For bionty registries. Also returns knowledge-coupled records.

Notes

For more info, see tutorial: Manage biological ontologies.

Example

Bulk create labels:

# from invalid values logs warnings & returns an empty list
ulabels = ln.ULabel.from_values(["benchmark", "prediction", "test"])
assert len(ulabels) == 0

# from valid values or via `create=True` returns label objects
ulabels = ln.ULabel.from_values(["benchmark", "prediction", "test"], create=True).save()
assert len(ulabels) == 3

# bulk create cell type labels from a public ontology
import bionty as bt
bt.CellType.from_values(["T cell", "B cell"]).save()

classmethod standardize(field=None, *, return_field=None, return_mapper=False, case_sensitive=False, mute=False, from_source=True, keep='first', synonyms_field='synonyms', organism=None, source=None, strict_source=False)¶

Maps input synonyms to standardized names.

Parameters:

values (ListLike) – Identifiers that will be standardized.
field (StrField | None, default: None) – The field representing the standardized names.
return_field (StrField | None, default: None) – The field to return. Defaults to field.
return_mapper (bool, default: False) – If True, returns {input_value: standardized_name}.
case_sensitive (bool, default: False) – Whether the mapping is case sensitive.
mute (bool, default: False) – Whether to mute logging.
from_source (bool, default: True) – Whether to standardize from public source. Defaults to True for BioRecord registries.
keep (Literal[‘first’, ‘last’, False], default: 'first') –
When a synonym maps to multiple names, determines which duplicates to mark as pd.DataFrame.duplicated: - "first": returns the first mapped standardized name - "last": returns the last mapped standardized name - False: returns all mapped standardized name.

When keep is False, the returned list of standardized names will contain nested lists in case of duplicates.

When a field is converted into return_field, keep marks which matches to keep when multiple return_field values map to the same field value.
synonyms_field (str, default: 'synonyms') – A field containing the concatenated synonyms.
organism (Union[str, SQLRecord, None], default: None) – An Organism name or record.
source (SQLRecord | None, default: None) – A bionty.Source record that specifies the version to validate against.
strict_source (bool, default: False) – Determines the validation behavior against records in the registry. - If False, validation will include all records in the registry, ignoring the specified source. - If True, validation will only include records in the registry that are linked to the specified source. Note: this parameter won’t affect validation against public sources.

Return type:

list[str] | dict[str, str]

Returns:

If return_mapper is False – a list of standardized names. Otherwise, a dictionary of mapped values with mappable synonyms as keys and standardized names as values.

See also

add_synonym(): Add synonyms.
remove_synonym(): Remove synonyms.

Example

Standardize gene identifiers:

import bionty as bt

# save some gene objects
bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol", organism="human").save()

# standardize gene synonyms
gene_synonyms = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
bt.Gene.standardize(gene_synonyms)
#> ['A1CF', 'A1BG', 'BRCA2', 'FANCD20']

Methods¶

save(*args, **kwargs)¶

Save.

Parameters:: transfer – If this record was queried on another instance: “sqlrecord” (default) copies the row and foreign keys only; “notes” also copies the readme; “annotations” also copies feature values.
Return type:: lamindb.Record

query_parents()¶

Query all parents of a record recursively.

While .parents retrieves the direct parents, this method retrieves all ancestors of the current record.

Return type:: QuerySet

query_children()¶

Query all children of a record recursively.

While .children retrieves the direct children, this method retrieves all descendants of a parent.

Return type:: QuerySet

query_records(depth=None)¶

Query records of sub types.

While .records retrieves the records with the current type, this method also retrieves sub types and the records with sub types of the current type.

Parameters:: depth (int | None, default: None) – How many type hops to follow. None walks the whole subtree. 1 returns only the direct records of this type.
Return type:: QuerySet

to_dataframe(is_run_input=None, link_individual_inputs=True, use_export_run=False, **kwargs)¶

Evaluate and convert to pd.DataFrame.

By default, this returns up to 20 rows for a fast overview. Pass limit=None to fetch all matching records.

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

Guide: Query & search

Parameters:

include – 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 measured in the current queryset. If "privates", includes private fields (fields starting with _).
features – Configure the features to include. Can be a feature name or a list of such names. Only available for Artifact, Record, and Run.
limit – Maximum number of rows to display. Defaults to 20. 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:

pd.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"])

to_artifact(key=None, suffix=None, is_run_input=None, link_individual_inputs=True, **kwargs)¶

Calls to_dataframe() to create an artifact.

The format defaults to .csv unless suffix is passed or key specifies another format.

The key defaults to lamindb_record_exports/{self.name}{suffix} unless a key is passed.

When the record frame schema defines index, the CSV is written with index=True so the index feature is preserved on export.

Example

Export all data records in a record frame to an artifact:

recordframe.to_artifact()

Parameters:

key (str | None, default: None) – The artifact key.
suffix (str | None, default: None) – The suffix to append to the default key if no key is passed.
is_run_input (bool | Run | None, default: None) – Whether to track the record as a run input.
link_individual_inputs (bool, default: True) – Whether to link all exported data records as inputs of the export run. If False, only links the record page or record frame.
**kwargs – Keyword arguments passed to to_dataframe().

Return type:

Artifact

restore()¶

Restore from trash onto the main branch.

Does not restore descendant objects if the object is HasType with is_type = True.

Return type:: None

delete(permanent=None, **kwargs)¶

Delete object.

If object is HasType with is_type = True, deletes all descendant objects, too.

Parameters:: permanent (bool | None, default: None) – Whether to permanently delete the object (skips trash). If None, performs soft delete if the object is not already in the trash.
Returns:: When permanent=True, returns Django’s delete return value – a tuple of (deleted_count, {registry_name: count}). Otherwise returns None.

Examples

For any SQLRecord object sqlrecord, call:

sqlrecord.delete()

classmethod describe(include=None, n_max_features=None)¶

Describe record including relations.

Parameters:

return_str (bool, default: False) – Return a string instead of printing.
include (None | Literal['comments'], default: None) – Include additional content. Use "comments" to display readme and comment blocks.
n_max_features (int | None, default: None) – Max number of internal schema members shown in Artifact.describe() previews.

Return type:

None | str

query_types()¶

Query types of a record recursively.

While .type retrieves the type, this method retrieves all super types of that type:

# Create type hierarchy
type1 = model_class(name="Type1", is_type=True).save()
type2 = model_class(name="Type2", is_type=True, type=type1).save()
type3 = model_class(name="Type3", is_type=True, type=type2).save()

# Create a record with type3
record = model_class(name=f"{model_name}3", type=type3).save()

# Query super types
super_types = record.query_types()
assert super_types[0] == type3
assert super_types[1] == type2
assert super_types[2] == type1

Return type:: SQLRecordList

view_parents(field=None, with_children=False, distance=5)¶

View parents in an ontology.

Parameters:

field (StrField | None, default: None) – Field to display on graph
with_children (bool, default: False) – Whether to also show children.
distance (int, default: 5) – Maximum distance still shown.

Ontological hierarchies: ULabel (project & sub-project), CellType (cell type & subtype).

Examples

>>> import bionty as bt
>>> bt.Tissue.from_source(name="subsegmental bronchus").save()
>>> record = bt.Tissue.get(name="respiratory tube")
>>> record.view_parents()
>>> tissue.view_parents(with_children=True)

view_children(field=None, distance=5)¶

View children in an ontology.

Parameters:

field (StrField | None, default: None) – Field to display on graph
distance (int, default: 5) – Maximum distance still shown.

Ontological hierarchies: ULabel (project & sub-project), CellType (cell type & subtype).

Examples

>>> import bionty as bt
>>> bt.Tissue.from_source(name="subsegmental bronchus").save()
>>> record = bt.Tissue.get(name="respiratory tube")
>>> record.view_parents()
>>> tissue.view_parents(with_children=True)

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.