lenskit.data.Vocabulary

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

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 entity 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 (lenskit.data.types.IDSequence | pandas.Index | Iterable[lenskit.data.types.ID] | None) – The IDs to put in the vocabulary.

• name (str | None) – The vocabulary name (i.e. the entity class it stores IDs for).

• 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).

name: str | None

The name of the vocabulary (e.g. “user”, “item”).

property index: pandas.Index

The vocabulary as a Pandas index.

Stability:

Internal (see Stability Levels).

Return type:

pandas.Index

property size: int

Current vocabulary size.

Return type:

int

number(term: object, missing: Literal['error'] = 'error') → int

number(term: object, missing: Literal['none'] | None) → int | None

Look up the number for a vocabulary ID.

numbers(terms: Sequence[Hashable] | numpy.typing.ArrayLike, missing: Literal['error', 'negative'] = 'error', *, format: Literal['numpy'] = 'numpy') → numpy.typing.NDArray[numpy.int32]

numbers(terms: Sequence[Hashable] | numpy.typing.ArrayLike, missing: Literal['error', 'negative', 'null'] = 'error', *, format: Literal['arrow']) → pyarrow.Int32Array

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

term(num)

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

Parameters:

num (int)

Return type:

object

terms(nums: list[int] | numpy.typing.NDArray[numpy.integer] | pandas.Series | None = None, *, format: Literal['numpy'] = 'numpy') → lenskit.data.types.IDArray

terms(nums: list[int] | numpy.typing.NDArray[numpy.integer] | pandas.Series | None = None, *, format: Literal['arrow']) → pyarrow.Array

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

Parameters:

nums – 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.

id(num)

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

Parameters:

num (int)

Return type:

object

ids(nums: list[int] | numpy.typing.NDArray[numpy.integer] | pandas.Series | None = None, *, format: Literal['numpy'] = 'numpy') → lenskit.data.types.IDArray

ids(nums: list[int] | numpy.typing.NDArray[numpy.integer] | pandas.Series | None = None, *, format: Literal['arrow']) → pyarrow.Array

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

id_array()

Return type:

pyarrow.Array

__eq__(other)

Parameters:

other (Vocabulary)

Return type:

bool

__contains__(key)

Parameters:

key (object)

Return type:

bool

__iter__()

Return type:

Iterator[object]

__len__()

Return type:

int

__array__(dtype=None)

Return type:

numpy.ndarray

__getstate__()

__setstate__(state)

__str__()

Return type:

str

__repr__()

Return type:

str