lenskit.data.Vocabulary#

class lenskit.data.Vocabulary(keys=None, name=None, *, reorder=True)#

Bases: object

Vocabularies of entity identifiers for the LensKit data model.

This class supports bidirectional mappings between key-like data and congiguous nonnegative integer indices. Its key use is to facilitate the entitie ID vocabularies in Dataset, but it can also be used for things like item tags.

IDs in a vocabulary must be unique. Constructing a vocabulary with reorder=True ensures uniqueness (and sorts the IDs), but does not preserve the order of IDs in the original input.

It is currently a wrapper around pandas.Index, but this fact is not part of the stable public API.

Parameters:

keys (IDSequence | pd.Index | Iterable[ID] | None) – The IDs to put in the vocabulary.
name (str | None) – The vocabulary name.
reorder (bool) – If True, sort and deduplicate the IDs. If False (the default), use the IDs as-is (assigning each to their position in the input sequence).

Stability:

Caller (see Stability Levels).

__init__(keys=None, name=None, *, reorder=True)#

Parameters:

keys (IDSequence | pd.Index | Iterable[ID] | None)
name (str | None)
reorder (bool)

Methods

`__init__`([keys, name, reorder])
`id`(num)	Alias for `term()` for greater readability for entity ID vocabularies.
`ids`([nums])	Alias for `terms()` for greater readability for entity ID vocabularies.
`number`()	Look up the number for a vocabulary term.
`numbers`(terms[, missing])	Look up the numbers for an array of terms or IDs.
`term`(num)	Look up the term with a particular number.
`terms`([nums])	Get a list of terms, optionally for an array of term numbers.

Attributes

`index`	The property as a Pandas index.
`size`	Current vocabulary size.
`name`	The name of the vocabulary (e.g. “user”, “item”).

name: str | None#: The name of the vocabulary (e.g. “user”, “item”).

property index: Index#: The property as a Pandas index.

property size: int#: Current vocabulary size.

number(term: object, missing: Literal['error'] = 'error') → int#
number(term: object, missing: Literal['none'] | None) → int | None: Look up the number for a vocabulary term.

numbers(terms, missing='error')#

Look up the numbers for an array of terms or IDs.

Parameters:

terms (Sequence[Hashable] | numpy.typing.ArrayLike)
missing (Literal['error', 'negative'])

Return type:

ndarray[int, dtype[int32]]

term(num)#

Look up the term with a particular number. Negative indexing is not supported.

Parameters:: num (int)
Return type:: object

terms(nums=None)#

Get a list of terms, optionally for an array of term numbers.

Parameters:: nums (list[int] | ndarray[Any, dtype[integer]] | Series | None) – The numbers (indices) for of terms to retrieve. If None, returns all terms.
Returns:: The terms corresponding to the specified numbers, or the full array of terms (in order) if nums=None.
Return type:: ndarray[tuple[int], dtype[integer[Any] | str_ | bytes_ | object_]]

id(num)#

Alias for term() for greater readability for entity ID vocabularies.

Parameters:: num (int)
Return type:: object

ids(nums=None)#

Alias for terms() for greater readability for entity ID vocabularies.

Parameters:: nums (list[int] | ndarray[Any, dtype[integer]] | Series | None)
Return type:: ndarray[tuple[int], dtype[integer[Any] | str_ | bytes_ | object_]]