polars.datatypes.Categories

class polars.datatypes.Categories(
    name: str | None = None,
    namespace: str = '',
    physical: PolarsDataType = UInt32,
)

Именованная коллекция категорий для Categorical.

Две категории считаются равными (и будут использовать одно и то же физическое сопоставление категорий строкам), если у них совпадают имя, пространство имён и физический базовый тип, даже если они созданы в отдельных вызовах Categories.

Предупреждение

В настоящее время эта функциональность считается нестабильной. Она может быть изменена в любой момент, и такие изменения не будут считаться нарушающими совместимость.

Параметры:

name

Имя этого Categories. Если задано None или пустая строка, оно указывает на глобальные категории.

namespace

Необязательное пространство имён для этого Categories. По умолчанию — пустая строка. Если имя пустое или равно None, что указывает на глобальные категории, пространство имён также должно быть пустым.

physical{UInt8, UInt16, UInt32}

Физический тип, используемый для представления категорий. По умолчанию — UInt32.

См. также

Categorical

Примеры

Экземпляр Categories можно индексировать с помощью строковых или целочисленных ключей:

>>> fruit = pl.Categories("fruit")
>>> s = pl.Series(["apple", "banana", "orange"], dtype=pl.Categorical(fruit))
>>> fruit[0]
'apple'
>>> fruit["apple"]
0

Все объекты Categories с одинаковыми именем, пространством имён и физическим типом используют одно и то же сопоставление, даже если они созданы отдельно:

>>> fruit2 = pl.Categories("fruit")
>>> fruit2["banana"]
1

Чтобы получить список всех категорий, можно выполнить итерацию по экземпляру Categories:

>>> list(fruit)
['apple', 'banana', 'orange']

Примечание

Поскольку категории хранятся в конкурентной структуре данных, физические значения категорий могут быть зарезервированы до того, как им будет присвоено строковое лексическое значение, если выполняются конкурентные запросы. В результате полученный Series может содержать значения None.

Экземпляр Categories является лишь слабой ссылкой на фактическое сопоставление, хранящееся в Polars. Если нет фактических данных, использующих это сопоставление (например, Series или DataFrame), Polars удаляет сопоставление:

>>> del s
>>> print(fruit["apple"])
None

Чтобы сохранить сопоставление, достаточно поддерживать жизнь какого-либо объекта, использующего его, например keepalive = pl.Series([], dtype=pl.Categorical(fruit)).

__init__(
    name: str | None = None,
    namespace: str = '',
    physical: PolarsDataType = UInt32,
) → None

Методы

__init__([name, namespace, physical])
is_global()	Возвращает, указывает ли этот объект на глобальные категории.
name()	Имя этого Categories.
namespace()	Пространство имён этого Categories.
physical()	Физический тип, используемый для представления категорий.
random([namespace, physical])	Создаёт новый Categories со случайным именем.
to_dict()	Возвращает словарь, сопоставляющий строки категорий их физическим значениям.
to_series()	Возвращает Series, содержащий все категории этого Categories.