lamindb.core.QuerySet¶

class lamindb.core.QuerySet(model=None, query=None, using=None, hints=None)¶

Bases: QuerySet, CanValidate

Sets of records returned by queries.

See also

Examples

>>> ln.ULabel(name="my label").save()
>>> queryset = ln.ULabel.filter(name="my label")
>>> queryset

Attributes¶

db¶: Return the database used if this query is executed now.

ordered¶: Return True if the QuerySet is ordered – i.e. has an order_by()

query¶

Methods¶

delete(*args, **kwargs)¶: Delete all records in the query set.

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

.

first()¶

If non-empty, the first result in the query set, otherwise None.

Return type:: Registry | None

Examples

>>> queryset.first()

inspect(values, field=None, **kwargs)¶

Inspect if values are mappable to a field.

Being mappable means that an exact match exists.

Parameters:

values (List[str] | Series | array) – Values that will be checked against the field.
field (str | DeferredAttribute | 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 – Mute logging.
organism – An Organism name or record.
public_source – A PublicSource record.

See also

validate()

Examples

>>> import bionty as bt
>>> bt.settings.organism = "human"
>>> ln.save(bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol"))
>>> gene_symbols = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
>>> result = bt.Gene.inspect(gene_symbols, field=bt.Gene.symbol)
✅ 2 terms (50.00%) are validated
🔶 2 terms (50.00%) are not validated
    🟠 detected synonyms
    to increase validated terms, standardize them via .standardize()
>>> result.validated
['A1CF', 'A1BG']
>>> result.non_validated
['FANCD1', 'FANCD20']

.

latest_version()¶

Filter every version family by latest version.

Return type:: RecordsList

list(field=None)¶

Populate a list with the results.

Return type:: list[Registry]

Examples

>>> queryset.list()  # list of records
>>> queryset.list("name")  # list of values

lookup(field=None, **kwargs)¶

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 – 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")

.

one()¶

Exactly one result. Raises error if there are more or none.

Return type:: Registry

Examples

>>> ln.ULabel.filter(name="benchmark").one()

one_or_none()¶

At most one result. Returns it if there is one, otherwise returns None.

Return type:: Registry | None

Examples

>>> ln.ULabel.filter(name="benchmark").one_or_none()
>>> ln.ULabel.filter(name="non existing label").one_or_none()

search(string, **kwargs)¶

Search.

Parameters:

string (str) – The input string to match against the field ontology values.
field – The field or fields to search. Search all string fields by default.
limit – Maximum amount of top results to return.
case_sensitive – Whether the match is case sensitive.

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")

.

standardize(values, field=None, **kwargs)¶

Maps input synonyms to standardized names.

Parameters:

values (Iterable) – Identifiers that will be standardized.
field (str | DeferredAttribute | None, default: None) – The field representing the standardized names.
return_field – The field to return. Defaults to field.
return_mapper – If True, returns {input_value: standardized_name}.
case_sensitive – Whether the mapping is case sensitive.
mute – Mute logging.
public_aware – Whether to standardize from Bionty reference. Defaults to True for Bionty registries.
keep –
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 – A field containing the concatenated synonyms.
organism – An Organism name or record.

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.

Examples

>>> import bionty as bt
>>> bt.settings.organism = "human"
>>> ln.save(bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol"))
>>> gene_synonyms = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
>>> standardized_names = bt.Gene.standardize(gene_synonyms)
>>> standardized_names
['A1CF', 'A1BG', 'BRCA2', 'FANCD20']

.

validate(values, field=None, **kwargs)¶

Validate values against existing values of a string field.

Note this is strict validation, only asserts exact matches.

Parameters:

values (List[str] | Series | array) – Values that will be validated against the field.
field (str | DeferredAttribute | 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 – Mute logging.

Returns:

A vector of booleans indicating if an element is validated.

See also

inspect()

Examples

>>> import bionty as bt
>>> bt.settings.organism = "human"
>>> ln.save(bt.Gene.from_values(["A1CF", "A1BG", "BRCA2"], field="symbol"))
>>> gene_symbols = ["A1CF", "A1BG", "FANCD1", "FANCD20"]
>>> bt.Gene.validate(gene_symbols, field=bt.Gene.symbol)
✅ 2 terms (50.00%) are validated
🔶 2 terms (50.00%) are not validated
array([ True,  True, False, False])

.