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

Справка по API

Указатель

Моделирование

@model(expr[, warn = false])

Макрос для задания вероятностной модели.

Если warn имеет значение true, выводится предупреждение, когда в определении модели используются имена внутренних переменных.

Примеры

Определение модели:

@model function model(x, y = 42)
    ...
end

Для создания модели Model следует вызывать model(xvalue) или model(xvalue, yvalue).

Сэмплеры

Sampler{T}

Универсальный тип сэмплера для алгоритмов вывода типа T в DynamicPPL.

Сэмплер (Sampler) должен реализовывать интерфейс AbstractMCMC, и, в частности, AbstractMCMC.step. Имеется заданная по умолчанию реализация начального шага выборки, которая поддерживает возобновление выборки из предыдущего состояния и задание начальных значений параметров. Она требует перегрузки loadstate и initialstep для загрузки предыдущих состояний и собственно выполнения начального шага выборки, соответственно. Кроме того, иногда может потребоваться реализовать initialsampler, который определяет, как будет осуществляться выборка начальных значений параметров, если они не заданы. По умолчанию значения выбираются из априорного распределения.

Gibbs(algs...)

Составной интерфейс MCMC. Выборка Гиббса объединяет один или несколько алгоритмов выборки, каждый из которых делает выборку из разного набора переменных в модели.

Пример:

@model function gibbs_example(x)
    v1 ~ Normal(0,1)
    v2 ~ Categorical(5)
end

# Используем PG для переменной 'v2' и используем HMC для переменной 'v1'.
# Обратите внимание, что v2 дискретна, поэтому сэмплер PG подходит больше,
# чем HMC.
alg = Gibbs(HMC(0.2, 3, :v1), PG(20, :v2))

Можно также передать количество итераций для каждого компонента Гиббса, используя следующий синтаксис:

  • alg = GibbsHMC(0.2, 3, :v1), n_hmc), (PG(20, :v2), n_pg

где n_hmc и n_pg — это количество итераций HMC и PG для каждой итерации Гиббса.

Советы:

  • HMC и NUTS являются быстрыми сэмплерами и могут отбрасывать методы, основанные на частицах,

такие как метод Гиббса на основе частиц. Вы можете повысить эффективность выборки частиц, включив больше частиц в сэмплер частиц.

HMC(ϵ::Float64, n_leapfrog::Int)

Сэмплер гамильтониана Монте-Карло со статической траекторией.

Аргументы:

  • ϵ::Float64: используемый размер шага с перешагиванием.

  • n_leapfrog::Int: количество используемых шагов с перешагиванием.

Использование:

HMC(0.05, 10)

Советы:

  • Если вы получаете ошибки градиента при использовании HMC, попробуйте уменьшить размер шага с перешагиванием ϵ, как показано далее:

# Исходный размер шага
sample(gdemo([1.5, 2]), HMC(0.1, 10), 1000)

# Сокращенный размер шага
sample(gdemo([1.5, 2]), HMC(0.01, 10), 1000)
HMCDA(n_adapts::Int, δ::Float64, λ::Float64; ϵ::Float64=0.0)

Сэмплер гамильтониана Монте-Карло с алгоритмом двойного среднего.

Использование:

HMCDA(200, 0.65, 0.3)

Аргументы:

  • n_adapts::Int: количество выборок, используемых для адаптации.

  • δ::Float64: целевой коэффициент принятия. Часто рекомендуется 65 %.

  • λ::Float64: целевая длина перешагивания.

  • ϵ::Float64=0.0: начальный размер шага; 0 означает автоматический поиск с использованием Turing.

Дополнительные сведения см. в следующем документе (ссылка на arXiv):

  • Hoffman, Matthew D., and Andrew Gelman. The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. Journal of Machine Learning Research 15, no. 1 (2014): 1593-1623.

IS()

Алгоритм выборки по значимости.

Использование:

IS()

Пример:

# Определим простую нормальную модель с неизвестными средним и дисперсией.
@model function gdemo(x)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0,sqrt.(s))
    x[1] ~ Normal(m, sqrt.(s))
    x[2] ~ Normal(m, sqrt.(s))
    return s², m
end

sample(gdemo([1.5, 2]), IS(), 1000)
MH(space...)

Строит алгоритм Метрополиса-Гастингса.

Аргументами space могут быть

  • пустое значение (т. е. MH()); в этом случае MH по умолчанию использует априорное распределение для каждого параметра в качестве распределения предложения;

  • набор из одного или нескольких символов для выборки с помощью MH в сочетании с Gibbs, т. е. Gibbs(MH(:m), PG(10, :s));

  • итерируемый объект пар или кортежей, сопоставляющих Symbol с AdvancedMH.Proposal, Distribution, или функция (Function), которая возвращает условное распределение предложения;

  • ковариационная матрица, которую следует использовать для многомерных нормальных предложений с нулевым средним.

Примеры

MH по умолчанию будет использовать предлагаемые образцы из априорного распределения с помощью AdvancedMH.StaticProposal.

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

chain = sample(gdemo(1.5, 2.0), MH(), 1_000)
mean(chain)

Кроме того, вы можете указать конкретные параметры для выборки, если хотите объединить выборку из нескольких сэмплеров:

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

# Выбирает s с помощью MH и m с помощью PG
chain = sample(gdemo(1.5, 2.0), Gibbs(MH(:s), PG(10, :m)), 1_000)
mean(chain)

Применение пользовательских дистрибутивов по умолчанию приводит к использованию статического MH:

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

# Используем статическое предложение для s и случайное блуждание со стандартным
# отклонением предложения в 0,25 для m.
chain = sample(
    gdemo(1.5, 2.0),
    MH(
        :s => InverseGamma(2, 3),
        :m => Normal(0, 1)
    ),
    1_000
)
mean(chain)

Задание явных предложений с помощью интерфейса AdvancedMH:

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

# Используем статическое предложение для s и случайное блуждание со стандартным
# отклонением предложения в 0,25 для m.
chain = sample(
    gdemo(1.5, 2.0),
    MH(
        :s => AdvancedMH.StaticProposal(InverseGamma(2,3)),
        :m => AdvancedMH.RandomWalkProposal(Normal(0, 0.25))
    ),
    1_000
)
mean(chain)

Использование пользовательской функции для задания условного распределения:

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

# Используем статическое предложение для s и условное предложение для m,
# где предложение сосредоточено вокруг текущего образца.
chain = sample(
    gdemo(1.5, 2.0),
    MH(
        :s => InverseGamma(2, 3),
        :m => x -> Normal(x, 1)
    ),
    1_000
)
mean(chain)

Предоставление ковариационной матрицы заставит MH выполнить выборку случайных блужданий в преобразованном пространстве с предложениями, взятыми из многомерного нормального распределения. Предоставленная матрица должна быть положительной полуопределенной и квадратной. Использование:

@model function gdemo(x, y)
    s² ~ InverseGamma(2,3)
    m ~ Normal(0, sqrt(s²))
    x ~ Normal(m, sqrt(s²))
    y ~ Normal(m, sqrt(s²))
end

# Предоставление пользовательской дисперсионно-ковариационной матрицы
chain = sample(
    gdemo(1.5, 2.0),
    MH(
        [0.25 0.05;
         0.05 0.50]
    ),
    1_000
)
mean(chain)
NUTS(n_adapts::Int, δ::Float64; max_depth::Int=10, Δ_max::Float64=1000.0, init_ϵ::Float64=0.0)

Сэмплер без разворота (NUTS).

Использование:

NUTS()            # Используем конфигурацию NUTS по умолчанию.
NUTS(1000, 0.65)  # Используем 1000 шагов адаптации и целевой коэффициент принятия, равный 0,65.

Аргументы:

  • n_adapts::Int: количество выборок, используемых при адаптации.

  • δ::Float64: целевой коэффициент принятия для двойного среднего.

  • max_depth::Int: максимальная глубина удвоенного дерева.

  • Δ_max::Float64: максимальная дивергенция при удвоении дерева.

  • init_ϵ::Float64: начальный размер шага; 0 означает автоматический поиск с использованием эвристической процедуры.

struct PG{space, R} <: Turing.Inference.ParticleInference

Сэмплер Гиббса на основе частиц.

Поля

  • nparticles::Int64: количество частиц.

  • resampler::Any: алгоритм повторной выборки.

struct SMC{space, R} <: Turing.Inference.ParticleInference

Последовательный сэмплер Монте-Карло.

Поля

  • resampler::Any

Распределения

Flat()

Плоское распределение — это неправильное распределение вещественных чисел, которое имеет неправильную функцию плотности вероятности

FlatPos(l::Real)

Положительное плоское распределение с вещественным параметром l — это неправильное распределение вещественных чисел, которое имеет неправильную функцию плотности вероятности

BinomialLogit(n, logitp)

Биномиальное распределение с логит-параметризацией характеризует количество успешных выполнений в последовательности независимых попыток.

Оно имеет два параметра: n — количество попыток и logitp — логит вероятности вероятности успеха в отдельной попытке с распределением

См. также описание Binomial.

OrderedLogistic(η, c::AbstractVector)

Упорядоченное логистическое распределение с вещественным параметром η и точками сочленения c имеет вероятностную функцию массы

где K = length(c) + 1.