Документация Engee

Указатель API

CategoricalArray{T}(undef, dims::Dims; levels=nothing, ordered=false)
CategoricalArray{T}(undef, dims::Int...; levels=nothing, ordered=false)

Создает неинициализированный CategoricalArray с уровнями типа T <: Union{AbstractChar, AbstractString, Number} и измерениями dims.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

CategoricalArray{T, N, R}(undef, dims::Dims; levels=nothing, ordered=false)
CategoricalArray{T, N, R}(undef, dims::Int...; levels=nothing, ordered=false)

Аналогичен определению выше, но использует ссылочный тип R вместо типа по умолчанию (UInt32).

CategoricalArray(A::AbstractArray; levels=nothing, ordered=false)

Создает новый CategoricalArray со значениями из A и тем же типом элементов.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Если аргумент levels опущен, а тип элемента поддерживает его, уровни сортируются в порядке возрастания. В противном случае они сохраняются в порядке появления в A. Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

Если A уже является CategoricalArray, его уровни, упорядоченность и ссылочный тип сохраняются, если они не переопределены явным образом.

CategoricalMatrix{T}(undef, m::Int, n::Int; levels=nothing, ordered=false)

Создает неинициализированный CategoricalMatrix с уровнями типа T <: Union{AbstractChar, AbstractString, Number} и измерениями dim. Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

CategoricalMatrix{T, R}(undef, m::Int, n::Int; levels=nothing, ordered=false)

Аналогичен определению выше, но использует ссылочный тип R вместо типа по умолчанию (UInt32).

CategoricalMatrix(A::AbstractMatrix; levels=nothing, ordered=false)

Создает новый CategoricalMatrix со значениями из A и тем же типом элементов.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Если аргумент levels опущен, а тип элемента поддерживает его, уровни сортируются в порядке возрастания. В противном случае они сохраняются в порядке появления в A. Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

Если A уже является CategoricalMatrix, его уровни, упорядоченность и ссылочный тип сохраняются, если они не переопределены явным образом.

CategoricalValue{T <: Union{AbstractChar, AbstractString, Number}, R <: Integer}

Оболочка вокруг значения типа T, соответствующего уровню в CategoricalPool.

Объекты CategoricalValue считаются равными значению типа T, которое они заключают в оболочку с помощью == и isequal. Однако сравнения порядка, такие как < и isless, возможны только в том случае, если isordered имеет значение true для пула значений, и в этом случае используется порядок levels пула, а не стандартное упорядочение значений типа T.

CategoricalValue(value, source::Union{CategoricalValue, CategoricalArray})

Возвращает объект CategoricalValue, заключающий в оболочку value и присоединенный к CategoricalPool источника (source).

CategoricalVector{T}(undef, m::Int; levels=nothing, ordered=false)

Создает неинициализированный CategoricalVector с уровнями типа T <: Union{AbstractChar, AbstractString, Number} и измерениями dim.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

CategoricalVector{T, R}(undef, m::Int; levels=nothing, ordered=false)

Аналогичен определению выше, но использует ссылочный тип R вместо типа по умолчанию (UInt32).

CategoricalVector(A::AbstractVector; levels=nothing, ordered=false)

Создает новый CategoricalVector со значениями из A и тем же типом элементов.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Если аргумент levels опущен, а тип элемента поддерживает его, уровни сортируются в порядке возрастания. В противном случае они сохраняются в порядке появления в A. Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

Если A уже является CategoricalVector, его уровни, упорядоченность и ссылочный тип сохраняются, если они не переопределены явным образом.

categorical(A::AbstractArray; levels=nothing, ordered=false, compress=false)

Строит категориальный массив со значениями из A.

Именованный аргумент levels может быть вектором, задающим возможные значения для данных (это эквивалентно, но более эффективно, чем вызов функции levels! для результирующего массива). Если аргумент levels опущен, а тип элемента поддерживает его, уровни сортируются в порядке возрастания. В противном случае они сохраняются в порядке появления в A. Именованный аргумент ordered определяет, можно ли сравнивать значения массива в соответствии с упорядочением уровней или нет (см. описание isordered).

Если compress является true, будет использован наименьший ссылочный тип, способный хранить количество уникальных значений в A. Хотя это сократит использование памяти, передача этого параметра приведет к нестабильности типа, что может повлиять на производительность внутри функции, в которой выполняется вызов. Поэтому эту возможность следует использовать с осторожностью (одноаргументная версия не подвержена действию этой проблемы).

categorical(A::CategoricalArray; compress=false, levels=nothing, ordered=false)

Если A уже является CategoricalArray, его уровни, упорядоченность и ссылочный тип сохраняются, если они не переопределены явным образом.

compress(A::CategoricalArray)

Возвращает копию категориального массива A, используя наименьший ссылочный тип, способный хранить количество уровней (levels) A.

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

cut(x::AbstractArray, breaks::AbstractVector;
    labels::Union{AbstractVector,Function},
    extend::Union{Bool,Missing}=false, allowempty::Bool=false)

Делит числовой массив на интервалы в разрывах (breaks) значений и возвращает упорядоченный CategoricalArray, указывающий интервал, в который попадает каждая запись. Интервалы имеют вид [lower, upper), т. е. нижняя граница включается, а верхняя исключается, кроме случаев, когда extend=true для последнего интервала, который затем замыкается с обоих концов, т. е. [lower, upper].

Если x принимает отсутствующие значения (т. е. eltype(x) >: Missing), возвращаемый массив также будет их принимать.

Именованные аргументы

  • extend::Union{Bool, Missing}=false: когда задано значение false, будет выдана ошибка, если некоторые значения в x выходят за пределы разрывов; когда задано значение true, разрывы автоматически добавляются, чтобы включать все значения в x, и верхняя граница включается в последний интервал; когда задано значение missing, значения за пределами разрывов генерируют записи missing.

  • labels::Union{AbstractVector, Function}: вектор строк, символов или чисел, задающих имена для интервалов; или функция f(from, to, i; leftclosed, rightclosed), которая генерирует метки от левой и правой границ интервалов и индекса группы. По умолчанию используется "[from, to)" (или "[from, to]" для крайнего правого интервала, если extend == true).

  • allowempty::Bool=false: когда задано значение false, будет выдана ошибка, если некоторые разрывы появляются несколько раз, создавая пустые интервалы; когда задано значение true, дублирующие разрывы разрешены, а создаваемые ими интервалы сохраняются как неиспользуемые уровни (но повторяющиеся метки не разрешены).

Примеры

julia> using CategoricalArrays

julia> cut(-1:0.5:1, [0, 1], extend=true)
5-element CategoricalArray{String,1,UInt32}:
 "[-1.0, 0.0)"
 "[-1.0, 0.0)"
 "[0.0, 1.0]"
 "[0.0, 1.0]"
 "[0.0, 1.0]"

julia> cut(-1:0.5:1, 2)
5-element CategoricalArray{String,1,UInt32}:
 "Q1: [-1.0, 0.0)"
 "Q1: [-1.0, 0.0)"
 "Q2: [0.0, 1.0]"
 "Q2: [0.0, 1.0]"
 "Q2: [0.0, 1.0]"

julia> cut(-1:0.5:1, 2, labels=["A", "B"])
5-element CategoricalArray{String,1,UInt32}:
 "A"
 "A"
 "B"
 "B"
 "B"

julia> cut(-1:0.5:1, 2, labels=[-0.5, +0.5])
5-element CategoricalArray{Float64,1,UInt32}:
 -0.5
 -0.5
 0.5
 0.5
 0.5

julia> fmt(from, to, i; leftclosed, rightclosed) = "grp $i ($from//$to)"
fmt (generic function with 1 method)

julia> cut(-1:0.5:1, 3, labels=fmt)
5-element CategoricalArray{String,1,UInt32}:
 "grp 1 (-1.0//-0.3333333333333335)"
 "grp 1 (-1.0//-0.3333333333333335)"
 "grp 2 (-0.3333333333333335//0.33333333333333326)"
 "grp 3 (0.33333333333333326//1.0)"
 "grp 3 (0.33333333333333326//1.0)"
cut(x::AbstractArray, ngroups::Integer;
    labels::Union{AbstractVector{<:AbstractString},Function},
    allowempty::Bool=false)

Делит числовой массив на ngroups квантилей, определяемых с помощью quantile.

Если x содержит значения missing, они автоматически пропускаются при вычислении квантилей.

Именованные аргументы

  • labels::Union{AbstractVector, Function}: вектор строк, символов или чисел, задающих имена для интервалов; или функция f(from, to, i; leftclosed, rightclosed), которая генерирует метки от левой и правой границ интервалов и индекса группы. По умолчанию используется "Qi: [from, to)" (или "Qi: [from, to]" для крайнего правого интервала).

  • allowempty::Bool=false: когда задано значение false, будет выдана ошибка, если некоторые точки разрыва квантилей равны, создавая пустые интервалы; когда задано значение true, дублирующие разрывы разрешены, а создаваемые ими интервалы сохраняются как неиспользуемые уровни (но повторяющиеся метки не разрешены).

decompress(A::CategoricalArray)

Возвращает копию категориального массива A, используя заданный по умолчанию ссылочный тип (UInt32). Если A использует небольшой ссылочный тип (например, UInt8 или UInt16), в развернутом массиве будет достаточно места для дополнительного количества уровней.

Чтобы не вызывать функцию decompress, убедитесь, что функция compress не вызывается при создании категориального массива.

droplevels!(A::CategoricalArray)

Отбрасывает уровни, которые не появляются в категориальном массиве A (чтобы они больше не возвращались с помощью levels).

isordered(A::CategoricalArray)

Проверяет, можно ли сравнивать записи в A с помощью <, > и подобных операторов, используя упорядочение уровней.

levelcode(x::CategoricalValue)

Получает код категориального значения x, т. е. его индекс в наборе возможных значений, возвращаемых levels(x).

levelcode(x::Missing)

Возвращает missing.

levels!(A::CategoricalArray, newlevels::Vector; allowmissing::Bool=false)

Задает уровни категориального массива A. Порядок появления уровней будет соблюдаться методом levels, что может повлиять на отображение результатов в некоторых операциях; если массив A упорядочен (см. описание isordered), он также будет использоваться при сравнении порядков с помощью <, > и подобных операторов. Переупорядочение уровней никогда не повлияет на значения записей в массиве.

Если A принимает отсутствующие значения (т. е. eltype(A) >: Missing) и allowmissing=true, записи, соответствующие опущенным уровням, будут заданы как missing. В противном случае newlevels должен включать все уровни, которые появляются в данных.

ordered!(A::CategoricalArray, ordered::Bool)

Задает, можно ли сравнивать записи в A с помощью <, > и подобных операторов, используя упорядочение уровней. Возвращает измененный A.

recode(a::AbstractArray[, default::Any], pairs::Pair...)

Возвращает копию a, заменяя элементы, соответствующие ключу pairs, соответствующим значением. Тип массива выбирается таким образом, чтобы он мог содержать все перекодированные элементы (но не обязательно исходные элементы из a).

Для каждой пары (Pair) в pairs, если элемент равен (согласно isequal) или in ключу (первый элемент пары), то используется соответствующее значение (второй элемент). Если элемент не соответствует ни одному ключу и значение по умолчанию (default) не указано или nothing, он копируется как есть; если значение по умолчанию (default) указано, оно используется вместо исходного элемента. Если элемент соответствует нескольким ключам, используется первое совпадение.

recode(a::CategoricalArray[, default::Any], pairs::Pair...)

Если a является CategoricalArray, порядок результирующих уровней определяется порядком переданных pairs, и default будет последним уровнем (если это значение указано).

Примеры

julia> using CategoricalArrays

julia> recode(1:10, 1=>100, 2:4=>0, [5; 9:10]=>-1)
10-element Vector{Int64}:
 100
   0
   0
   0
  -1
   6
   7
   8
  -1
  -1
 recode(a::AbstractArray{>:Missing}[, default::Any], pairs::Pair...)

Если a содержит отсутствующие значения, они никогда не заменяются default: используйте missing в паре для их перекодирования. Если это не так, возвращаемый массив будет принимать отсутствующие значения.

Примеры

julia> using CategoricalArrays

julia> recode(1:10, 1=>100, 2:4=>0, [5; 9:10]=>-1, 6=>missing)
10-element Vector{Union{Missing, Int64}}:
 100
   0
   0
   0
  -1
    missing
   7
   8
  -1
  -1
    <☼☼>
recode!(dest::AbstractArray, src::AbstractArray[, default::Any], pairs::Pair...)

Заполняет dest элементами из src, заменяя те из них, которые соответствуют ключу pairs, соответствующим значением.

Для каждой пары (Pair) в pairs, если элемент равен (согласно isequal) ключу (первому элементу пары) или одной из его записей, если это коллекция, соответствующее значение (второй элемент) копируется в dest. Если элемент не соответствует ни одному ключу и значение по умолчанию (default) не указано или nothing, он копируется как есть; если значение по умолчанию (default) указано, оно используется вместо исходного элемента. dest и src должны быть одинаковой длины, но не обязательно одного типа. Элементы src, а также значения из pairs будут по возможности преобразованы (convert) при присваивании. Если элемент соответствует нескольким ключам, используется первое совпадение.

recode!(dest::CategoricalArray, src::AbstractArray[, default::Any], pairs::Pair...)

Если dest является CategoricalArray, порядок результирующих уровней определяется порядком переданных pairs, и default будет последним уровнем (если это значение указано).

recode!(dest::AbstractArray, src::AbstractArray{>:Missing}[, default::Any], pairs::Pair...)

Если src содержит отсутствующие значения, они никогда не заменяются default: используйте missing в паре для их перекодирования.

recode!(a::AbstractArray[, default::Any], pairs::Pair...)

Вспомогательная функция для перекодирования на месте, эквивалентная recode!(a, a, ...).

Примеры

julia> using CategoricalArrays

julia> x = collect(1:10);

julia> recode!(x, 1=>100, 2:4=>0, [5; 9:10]=>-1);

julia> x
10-element Vector{Int64}:
 100
   0
   0
   0
  -1
   6
   7
   8
  -1
  -1
levels(x::CategoricalArray; skipmissing=true)
levels(x::CategoricalValue)

Return the levels of categorical array or value x. This may include levels which do not actually appear in the data (see droplevels!). missing will be included only if it appears in the data and skipmissing=false is passed.

The returned vector is an internal field of x which must not be mutated as doing so would corrupt it.

unwrap(x::CategoricalValue)
unwrap(x::Missing)

Получает значение, заключенное в категориальное значение x. Если x является Missing, возвращает missing.