lamindb.core.Registry

class lamindb.core.Registry(*args, **kwargs)

Bases: Model

Registry base class.

Extends django.db.models.Model.

Why does LaminDB call it Registry and not Model? The term “Registry” can’t lead to confusion with statistical, machine learning or biological models.

Fields

Methods

classmethod df(include=None)

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.

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(**expressions)

Query records (see Query & search registries).

Parameters:

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.filter(name="my ulabel").one()
classmethod from_values(values, field=None, create=False, organism=None, public_source=None, mute=False)

Bulk create validated records by parsing values for an identifier (a name, an id, etc.).

Parameters:
  • values (List[str] | Series | array) – A list of values for an identifier, e.g. ["name1", "name2"].

  • field (str | DeferredAttribute | None, default: None) – A Registry field to look up, e.g., bt.CellMarker.name.

  • create (bool, default: False) – Whether to create records if they don’t exist.

  • organism (str | Registry | None, default: None) – A bionty.Organism name or record.

  • public_source (Registry | None, default: None) – A bionty.PublicSource record.

  • mute (bool, default: False) – Do not show logging.

Return type:

list[Registry]

Returns:

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

Notes

For more info, see tutorial: Manage biological registries.

Examples

Bulk create from non-validated values will log warnings & returns empty list:

>>> ulabels = ln.ULabel.from_values(["benchmark", "prediction", "test"], field="name")
>>> assert len(ulabels) == 0

Bulk create records from validated values returns the corresponding existing records:

>>> ln.save([ln.ULabel(name=name) for name in ["benchmark", "prediction", "test"]])
>>> ulabels = ln.ULabel.from_values(["benchmark", "prediction", "test"], field="name")
>>> assert len(ulabels) == 3

Bulk create records from public reference:

>>> import bionty as bt
>>> records = bt.CellType.from_values(["T cell", "B cell"], field="name")
>>> records

.

classmethod get(idlike)

Get a single record.

Parameters:

idlike (int | str) – Either a uid stub, a uid or an integer id.

Return type:

Registry

Returns:

A record.

See also

Examples

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

.

save(*args, **kwargs)

Save.

Always saves to the default database.

Return type:

Registry

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, a 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) – 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

.