From 59c60f8cd0eca399480a1ba850fd09d07e152d24 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sat, 30 Nov 2024 09:36:33 +0000 Subject: [PATCH] build based on f11ac85 --- dev/.documenter-siteinfo.json | 2 +- dev/api/index.html | 461 +---------------- dev/index.html | 461 +---------------- dev/search_index.js | 2 +- dev/tutorials/custom_priors/index.html | 477 +---------------- dev/tutorials/hierarchical_models/index.html | 476 +---------------- dev/tutorials/linear_regression/index.html | 478 +----------------- dev/tutorials/logistic_regression/index.html | 476 +---------------- .../negative_binomial_regression/index.html | 476 +---------------- dev/tutorials/poisson_regression/index.html | 477 +---------------- dev/tutorials/robust_regression/index.html | 476 +---------------- index.html | 1 - 12 files changed, 106 insertions(+), 4157 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index ac3fdd46..fe1ba707 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-30T09:28:08","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-30T09:36:22","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index b4e3132d..3eca57b5 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,461 +1,2 @@ -API reference · TuringGLM.jl - - - - - -
GitHub

TuringGLM

Documentation for TuringGLM.

TuringGLM.CustomPrior — Type
CustomPrior(predictors, intercept, auxiliary)

struct to hold information regarding user-specified custom priors.

Usage

The CustomPrior struct has 3 fields:

  1. predictors: the β coefficients.
  2. intercept: the α intercept.
  3. auxiliary: an auxiliary parameter.

In robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.

Non-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.

source
TuringGLM.NegativeBinomial2 — Method
NegativeBinomial2(μ, ϕ)

An alternative parameterization of the Negative Binomial distribution:

\[\text{Negative-Binomial}(n \mid \mu, \phi) \sim \binom{n + \phi - 1}{n} \left( \frac{\mu}{\mu + \phi} \right)^{n!} \left( \frac{\phi}{\mu + \phi} \right)^{\phi!}\]

where the expectation is μ and variance is (μ + μ²/ϕ).

The alternative parameterization is inspired by the Stan's neg_binomial_2 function.

source
TuringGLM.center_predictors — Method
center_predictors(X::AbstractMatrix)

Centers the columns of a matrix X of predictors to mean 0.

Returns a tuple with:

  1. μ_X: 1xK Matrix of Float64s of the means of the K columns in the original X

matrix.

  1. X_centered: A Matrix of Float64s with the same dimensions as the original matrix

X with the columns centered on mean μ=0.

Arguments

  • X::AbstractMatrix: a matrix of predictors where rows are observations and columns are

variables.

source
TuringGLM.convert_str_to_indices — Method
convert_str_to_indices(v::AbstractVector)

Converts a vector v to a vector of indices, i.e. a vector where all the entries are integers. Returns a tuple with the first element as the converted vector and the second element a Dict specifying which string is which integer.

This function is especially useful for random-effects varying-intercept hierarchical models. Normally v would be a vector of group membership with values such as "group_1", "group_2" etc. For random-effect models with varying-intercepts, Turing needs the group membership values to be passed as Ints.

source
TuringGLM.data_fixed_effects — Method
data_fixed_effects(formula::FormulaTerm, data)

Constructs the matrix X of fixed-effects (a.k.a. population-level) predictors.

Returns a Matrix of the fixed-effects predictors variables in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.data_random_effects — Method
data_random_effects(formula::FormulaTerm, data)

Constructs the vector(s)/matrix(ces) Z(s) of random-effects (a.k.a. group-level) slope predictors.

Returns a Dict{String, AbstractArray} of Vector/Matrix as values of the random-effects predictors slope variables (keys) in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.data_response — Method
data_response(formula::FormulaTerm, data)

Constructs the response y vector.

Returns a Vector of the response variable in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.get_idx — Method
get_idx(term::Term, data)

Returns a tuple with the first element as the ID vector of Ints that represent group membership for a specific random-effect intercept group t of observations present in data. The second element of the tuple is a Dict specifying which string is which integer in the ID vector.

source
TuringGLM.get_var — Method
get_var(term::Term, data)

Returns the corresponding vector of column in data for the a specific random-effect slope term of observations present in data.

source
TuringGLM.has_ranef — Method
has_ranef(formula::FormulaTerm)

Returns true if any of the terms in formula is a FunctionTerm or false otherwise.

source
TuringGLM.intercept_per_ranef — Method
intercept_per_ranef(terms::Tuple{RandomEffectsTerm})

Returns a vector of Strings where the entries are the grouping variables that have a group-level intercept.

source
TuringGLM.n_ranef — Method
n_ranef(formula::FormulaTerm)

Returns the number of RandomEffectsTerms in formula.

source
TuringGLM.ranef — Method
ranef(formula::FormulaTerm)

Returns a tuple of the FunctionTerms parsed as RandomEffectsTerms in formula. If there are no FunctionTerms in formula returns nothing.

source
TuringGLM.slope_per_ranef — Method
slope_per_ranef(terms::Tuple{RandomEffectsTerm})

Returns a SlopePerRanEf object where the entries are the grouping variables that have a group-level slope.

source
TuringGLM.standardize_predictors — Method
standardize_predictors(X::AbstractMatrix)

Standardizes the columns of a matrix X of predictors to mean 0 and standard deviation 1.

Returns a tuple with:

  1. μ_X: 1xK Matrix of Float64s of the means of the K columns in the original X

matrix.

  1. σ_X: 1xK Matrix of Float64s of the standard deviations of the K columns in the

original X matrix.

  1. X_std: A Matrix of Float64s with the same dimensions as the original matrix

X with the columns centered on mean μ=0 and standard deviation σ=1.

Arguments

  • X::AbstractMatrix: a matrix of predictors where rows are observations and columns are

variables.

source
TuringGLM.standardize_predictors — Method
standardize_predictors(x::AbstractVector)

Standardizes the vector x to mean 0 and standard deviation 1.

Returns a tuple with:

  1. μ_X: Float64s of the mean of the original vector x.
  2. σ_X: Float64s of the standard deviations of the original vector x.
  3. x_std: A Vector of Float64s with the same length as the original vector

x with the values centered on mean μ=0 and standard deviation σ=1.

Arguments

  • x::AbstractVector: a vector.
source
TuringGLM.turing_model — Method
turing_model(formula, data; model=Normal, priors=DefaultPrior(), standardize=false)

Create a Turing model using formula syntax and a data source.

formula

formula is the the same friendly interface to specify used to specify statistical models by brms, rstarnarm, bambi, StatsModels.jl and MixedModels.jl. The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.

Example: @formula(y ~ x1 + x2 + x3).

Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.

Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).

Example: @formula(y ~ (1 | group) + x1).

Notice: random-effects are currently only implemented for a single group-level intercept. Future versions of TuringGLM.jl will support slope random-effects and multiple group-level effets.

data

data can be any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.

model

model represents the likelihood function which you want to condition your data on. It has to be a subtype of Distributions.UnivariateDistribution. Currently, TuringGLM.jl supports:

  • Normal (the default if not specified): linear regression
  • TDist: robust linear regression
  • Bernoulli: logistic regression
  • Poisson: Poisson count data regression
  • NegativeBinomial: negative binomial robust count data regression

priors

TuringGLM.jl comes with state-of-the-art default priors, based on the literature and the Stan community. By default, turing_model will use DefaultPrior. But you can specify your own with priors=CustomPrior(predictors, intercept, auxiliary). All models take a predictors and intercept priors.

In robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.

Non-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.

Example for a non-robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), nothing)

Example for a robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), Exponential(1))

standardize

Whether true or false to standardize your data to mean 0 and standard deviation 1 before inference. Some science fields prefer to analyze and report effects in terms of standard devations. Also, whenever measurement scales differs, it is often suggested to standardize the effects for better comparison. By default, turing_model sets standardize=false.

source
- +API reference · TuringGLM.jl
GitHub

TuringGLM

Documentation for TuringGLM.

TuringGLM.CustomPrior — Type
CustomPrior(predictors, intercept, auxiliary)

struct to hold information regarding user-specified custom priors.

Usage

The CustomPrior struct has 3 fields:

  1. predictors: the β coefficients.
  2. intercept: the α intercept.
  3. auxiliary: an auxiliary parameter.

In robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.

Non-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.

source
TuringGLM.NegativeBinomial2 — Method
NegativeBinomial2(μ, ϕ)

An alternative parameterization of the Negative Binomial distribution:

\[\text{Negative-Binomial}(n \mid \mu, \phi) \sim \binom{n + \phi - 1}{n} \left( \frac{\mu}{\mu + \phi} \right)^{n!} \left( \frac{\phi}{\mu + \phi} \right)^{\phi!}\]

where the expectation is μ and variance is (μ + μ²/ϕ).

The alternative parameterization is inspired by the Stan's neg_binomial_2 function.

source
TuringGLM.center_predictors — Method
center_predictors(X::AbstractMatrix)

Centers the columns of a matrix X of predictors to mean 0.

Returns a tuple with:

  1. μ_X: 1xK Matrix of Float64s of the means of the K columns in the original X

matrix.

  1. X_centered: A Matrix of Float64s with the same dimensions as the original matrix

X with the columns centered on mean μ=0.

Arguments

  • X::AbstractMatrix: a matrix of predictors where rows are observations and columns are

variables.

source
TuringGLM.convert_str_to_indices — Method
convert_str_to_indices(v::AbstractVector)

Converts a vector v to a vector of indices, i.e. a vector where all the entries are integers. Returns a tuple with the first element as the converted vector and the second element a Dict specifying which string is which integer.

This function is especially useful for random-effects varying-intercept hierarchical models. Normally v would be a vector of group membership with values such as "group_1", "group_2" etc. For random-effect models with varying-intercepts, Turing needs the group membership values to be passed as Ints.

source
TuringGLM.data_fixed_effects — Method
data_fixed_effects(formula::FormulaTerm, data)

Constructs the matrix X of fixed-effects (a.k.a. population-level) predictors.

Returns a Matrix of the fixed-effects predictors variables in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.data_random_effects — Method
data_random_effects(formula::FormulaTerm, data)

Constructs the vector(s)/matrix(ces) Z(s) of random-effects (a.k.a. group-level) slope predictors.

Returns a Dict{String, AbstractArray} of Vector/Matrix as values of the random-effects predictors slope variables (keys) in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.data_response — Method
data_response(formula::FormulaTerm, data)

Constructs the response y vector.

Returns a Vector of the response variable in the formula and present inside data.

Arguments

  • formula: a FormulaTerm created by @formula macro.
  • data: a data object that satisfies the

Tables.jl interface such as a DataFrame.

source
TuringGLM.get_idx — Method
get_idx(term::Term, data)

Returns a tuple with the first element as the ID vector of Ints that represent group membership for a specific random-effect intercept group t of observations present in data. The second element of the tuple is a Dict specifying which string is which integer in the ID vector.

source
TuringGLM.get_var — Method
get_var(term::Term, data)

Returns the corresponding vector of column in data for the a specific random-effect slope term of observations present in data.

source
TuringGLM.has_ranef — Method
has_ranef(formula::FormulaTerm)

Returns true if any of the terms in formula is a FunctionTerm or false otherwise.

source
TuringGLM.intercept_per_ranef — Method
intercept_per_ranef(terms::Tuple{RandomEffectsTerm})

Returns a vector of Strings where the entries are the grouping variables that have a group-level intercept.

source
TuringGLM.n_ranef — Method
n_ranef(formula::FormulaTerm)

Returns the number of RandomEffectsTerms in formula.

source
TuringGLM.ranef — Method
ranef(formula::FormulaTerm)

Returns a tuple of the FunctionTerms parsed as RandomEffectsTerms in formula. If there are no FunctionTerms in formula returns nothing.

source
TuringGLM.slope_per_ranef — Method
slope_per_ranef(terms::Tuple{RandomEffectsTerm})

Returns a SlopePerRanEf object where the entries are the grouping variables that have a group-level slope.

source
TuringGLM.standardize_predictors — Method
standardize_predictors(X::AbstractMatrix)

Standardizes the columns of a matrix X of predictors to mean 0 and standard deviation 1.

Returns a tuple with:

  1. μ_X: 1xK Matrix of Float64s of the means of the K columns in the original X

matrix.

  1. σ_X: 1xK Matrix of Float64s of the standard deviations of the K columns in the

original X matrix.

  1. X_std: A Matrix of Float64s with the same dimensions as the original matrix

X with the columns centered on mean μ=0 and standard deviation σ=1.

Arguments

  • X::AbstractMatrix: a matrix of predictors where rows are observations and columns are

variables.

source
TuringGLM.standardize_predictors — Method
standardize_predictors(x::AbstractVector)

Standardizes the vector x to mean 0 and standard deviation 1.

Returns a tuple with:

  1. μ_X: Float64s of the mean of the original vector x.
  2. σ_X: Float64s of the standard deviations of the original vector x.
  3. x_std: A Vector of Float64s with the same length as the original vector

x with the values centered on mean μ=0 and standard deviation σ=1.

Arguments

  • x::AbstractVector: a vector.
source
TuringGLM.turing_model — Method
turing_model(formula, data; model=Normal, priors=DefaultPrior(), standardize=false)

Create a Turing model using formula syntax and a data source.

formula

formula is the the same friendly interface to specify used to specify statistical models by brms, rstarnarm, bambi, StatsModels.jl and MixedModels.jl. The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.

Example: @formula(y ~ x1 + x2 + x3).

Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.

Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).

Example: @formula(y ~ (1 | group) + x1).

Notice: random-effects are currently only implemented for a single group-level intercept. Future versions of TuringGLM.jl will support slope random-effects and multiple group-level effets.

data

data can be any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.

model

model represents the likelihood function which you want to condition your data on. It has to be a subtype of Distributions.UnivariateDistribution. Currently, TuringGLM.jl supports:

  • Normal (the default if not specified): linear regression
  • TDist: robust linear regression
  • Bernoulli: logistic regression
  • Poisson: Poisson count data regression
  • NegativeBinomial: negative binomial robust count data regression

priors

TuringGLM.jl comes with state-of-the-art default priors, based on the literature and the Stan community. By default, turing_model will use DefaultPrior. But you can specify your own with priors=CustomPrior(predictors, intercept, auxiliary). All models take a predictors and intercept priors.

In robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.

Non-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.

Example for a non-robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), nothing)

Example for a robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), Exponential(1))

standardize

Whether true or false to standardize your data to mean 0 and standard deviation 1 before inference. Some science fields prefer to analyze and report effects in terms of standard devations. Also, whenever measurement scales differs, it is often suggested to standardize the effects for better comparison. By default, turing_model sets standardize=false.

source
diff --git a/dev/index.html b/dev/index.html index f2300fd1..adb42485 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,461 +1,2 @@ -Home · TuringGLM.jl - - - - - -
GitHub

TuringGLM

Documentation for TuringGLM. Please file an issue if you run into any problems.

TuringGLM supports Julia version 1.7+. We recommend always using it with the latest stable Julia release.

Getting Started

TuringGLM makes easy to specify Bayesian Generalized Linear Models using the formula syntax and returns an instantiated Turing model.

Heavily inspired by brms (uses RStan or CmdStanR) and bambi (uses PyMC3).

@formula

The @formula macro is extended from StatsModels.jl along with MixedModels.jl for the random-effects (a.k.a. group-level predictors).

The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.

Example:

@formula(y ~ x1 + x2 + x3)

Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.

Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).

Example:

@formula(y ~ (1 | group) + x1)

Data

TuringGLM supports any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.

Supported Models

TuringGLM supports non-hierarchical and hierarchical models. For hierarchical models, only single random-intercept hierarchical models are supported.

Currently, for likelihoods TuringGLM.jl supports:

  • Normal (the default if not specified): linear regression
  • TDist: robust linear regression
  • Bernoulli: logistic regression
  • Poisson: Poisson count data regression
  • NegativeBinomial: negative binomial robust count data regression

Tutorials

Take a look at the tutorials for all supported likelihood and models.

    - +Home · TuringGLM.jl
    GitHub

    TuringGLM

    Documentation for TuringGLM. Please file an issue if you run into any problems.

    TuringGLM supports Julia version 1.7+. We recommend always using it with the latest stable Julia release.

    Getting Started

    TuringGLM makes easy to specify Bayesian Generalized Linear Models using the formula syntax and returns an instantiated Turing model.

    Heavily inspired by brms (uses RStan or CmdStanR) and bambi (uses PyMC3).

    @formula

    The @formula macro is extended from StatsModels.jl along with MixedModels.jl for the random-effects (a.k.a. group-level predictors).

    The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.

    Example:

    @formula(y ~ x1 + x2 + x3)

    Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.

    Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).

    Example:

    @formula(y ~ (1 | group) + x1)

    Data

    TuringGLM supports any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.

    Supported Models

    TuringGLM supports non-hierarchical and hierarchical models. For hierarchical models, only single random-intercept hierarchical models are supported.

    Currently, for likelihoods TuringGLM.jl supports:

    • Normal (the default if not specified): linear regression
    • TDist: robust linear regression
    • Bernoulli: logistic regression
    • Poisson: Poisson count data regression
    • NegativeBinomial: negative binomial robust count data regression

    Tutorials

    Take a look at the tutorials for all supported likelihood and models.

      diff --git a/dev/search_index.js b/dev/search_index.js index 8bac3660..9dee8988 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"api/","page":"API reference","title":"API reference","text":"CurrentModule = TuringGLM","category":"page"},{"location":"api/#TuringGLM","page":"API reference","title":"TuringGLM","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"Documentation for TuringGLM.","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"Modules = [TuringGLM]","category":"page"},{"location":"api/#TuringGLM.CustomPrior","page":"API reference","title":"TuringGLM.CustomPrior","text":"CustomPrior(predictors, intercept, auxiliary)\n\nstruct to hold information regarding user-specified custom priors.\n\nUsage\n\nThe CustomPrior struct has 3 fields:\n\npredictors: the β coefficients.\nintercept: the α intercept.\nauxiliary: an auxiliary parameter.\n\nIn robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.\n\nNon-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.\n\n\n\n\n\n","category":"type"},{"location":"api/#TuringGLM.NegativeBinomial2-Union{Tuple{T}, Tuple{T, T}} where T<:Real","page":"API reference","title":"TuringGLM.NegativeBinomial2","text":"NegativeBinomial2(μ, ϕ)\n\nAn alternative parameterization of the Negative Binomial distribution:\n\ntextNegative-Binomial(n mid mu phi) sim binomn + phi - 1n left( fracmumu + phi right)^n left( fracphimu + phi right)^phi\n\nwhere the expectation is μ and variance is (μ + μ²/ϕ).\n\nThe alternative parameterization is inspired by the Stan's neg_binomial_2 function.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.center_predictors-Tuple{AbstractMatrix}","page":"API reference","title":"TuringGLM.center_predictors","text":"center_predictors(X::AbstractMatrix)\n\nCenters the columns of a matrix X of predictors to mean 0.\n\nReturns a tuple with:\n\nμ_X: 1xK Matrix of Float64s of the means of the K columns in the original X\n\nmatrix.\n\nX_centered: A Matrix of Float64s with the same dimensions as the original matrix\n\nX with the columns centered on mean μ=0.\n\nArguments\n\nX::AbstractMatrix: a matrix of predictors where rows are observations and columns are\n\nvariables.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.convert_str_to_indices-Tuple{AbstractVector}","page":"API reference","title":"TuringGLM.convert_str_to_indices","text":"convert_str_to_indices(v::AbstractVector)\n\nConverts a vector v to a vector of indices, i.e. a vector where all the entries are integers. Returns a tuple with the first element as the converted vector and the second element a Dict specifying which string is which integer.\n\nThis function is especially useful for random-effects varying-intercept hierarchical models. Normally v would be a vector of group membership with values such as \"group_1\", \"group_2\" etc. For random-effect models with varying-intercepts, Turing needs the group membership values to be passed as Ints.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_fixed_effects-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_fixed_effects","text":"data_fixed_effects(formula::FormulaTerm, data)\n\nConstructs the matrix X of fixed-effects (a.k.a. population-level) predictors.\n\nReturns a Matrix of the fixed-effects predictors variables in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_random_effects-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_random_effects","text":"data_random_effects(formula::FormulaTerm, data)\n\nConstructs the vector(s)/matrix(ces) Z(s) of random-effects (a.k.a. group-level) slope predictors.\n\nReturns a Dict{String, AbstractArray} of Vector/Matrix as values of the random-effects predictors slope variables (keys) in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_response-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_response","text":"data_response(formula::FormulaTerm, data)\n\nConstructs the response y vector.\n\nReturns a Vector of the response variable in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.get_idx-Union{Tuple{D}, Tuple{StatsModels.Term, D}} where D","page":"API reference","title":"TuringGLM.get_idx","text":"get_idx(term::Term, data)\n\nReturns a tuple with the first element as the ID vector of Ints that represent group membership for a specific random-effect intercept group t of observations present in data. The second element of the tuple is a Dict specifying which string is which integer in the ID vector.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.get_var-Union{Tuple{D}, Tuple{StatsModels.Term, D}} where D","page":"API reference","title":"TuringGLM.get_var","text":"get_var(term::Term, data)\n\nReturns the corresponding vector of column in data for the a specific random-effect slope term of observations present in data.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.has_ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.has_ranef","text":"has_ranef(formula::FormulaTerm)\n\nReturns true if any of the terms in formula is a FunctionTerm or false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.intercept_per_ranef-Tuple{Tuple}","page":"API reference","title":"TuringGLM.intercept_per_ranef","text":"intercept_per_ranef(terms::Tuple{RandomEffectsTerm})\n\nReturns a vector of Strings where the entries are the grouping variables that have a group-level intercept.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.n_ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.n_ranef","text":"n_ranef(formula::FormulaTerm)\n\nReturns the number of RandomEffectsTerms in formula.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.ranef","text":"ranef(formula::FormulaTerm)\n\nReturns a tuple of the FunctionTerms parsed as RandomEffectsTerms in formula. If there are no FunctionTerms in formula returns nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.slope_per_ranef-Tuple{Tuple}","page":"API reference","title":"TuringGLM.slope_per_ranef","text":"slope_per_ranef(terms::Tuple{RandomEffectsTerm})\n\nReturns a SlopePerRanEf object where the entries are the grouping variables that have a group-level slope.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.standardize_predictors-Tuple{AbstractMatrix}","page":"API reference","title":"TuringGLM.standardize_predictors","text":"standardize_predictors(X::AbstractMatrix)\n\nStandardizes the columns of a matrix X of predictors to mean 0 and standard deviation 1.\n\nReturns a tuple with:\n\nμ_X: 1xK Matrix of Float64s of the means of the K columns in the original X\n\nmatrix.\n\nσ_X: 1xK Matrix of Float64s of the standard deviations of the K columns in the\n\noriginal X matrix.\n\nX_std: A Matrix of Float64s with the same dimensions as the original matrix\n\nX with the columns centered on mean μ=0 and standard deviation σ=1.\n\nArguments\n\nX::AbstractMatrix: a matrix of predictors where rows are observations and columns are\n\nvariables.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.standardize_predictors-Tuple{AbstractVector}","page":"API reference","title":"TuringGLM.standardize_predictors","text":"standardize_predictors(x::AbstractVector)\n\nStandardizes the vector x to mean 0 and standard deviation 1.\n\nReturns a tuple with:\n\nμ_X: Float64s of the mean of the original vector x.\nσ_X: Float64s of the standard deviations of the original vector x.\nx_std: A Vector of Float64s with the same length as the original vector\n\nx with the values centered on mean μ=0 and standard deviation σ=1.\n\nArguments\n\nx::AbstractVector: a vector.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.tuple_length-Union{Tuple{NTuple{N, Any}}, Tuple{N}} where N","page":"API reference","title":"TuringGLM.tuple_length","text":"tuple_length(::NTuple{N, Any}) where {N} = Int(N)\n\nThis is a hack to get the length of any tuple.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.turing_model-Union{Tuple{T}, Tuple{StatsModels.FormulaTerm, Any}} where T<:(UnivariateDistribution)","page":"API reference","title":"TuringGLM.turing_model","text":"turing_model(formula, data; model=Normal, priors=DefaultPrior(), standardize=false)\n\nCreate a Turing model using formula syntax and a data source.\n\nformula\n\nformula is the the same friendly interface to specify used to specify statistical models by brms, rstarnarm, bambi, StatsModels.jl and MixedModels.jl. The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.\n\nExample: @formula(y ~ x1 + x2 + x3).\n\nModerations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.\n\nRandom-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).\n\nExample: @formula(y ~ (1 | group) + x1).\n\nNotice: random-effects are currently only implemented for a single group-level intercept. Future versions of TuringGLM.jl will support slope random-effects and multiple group-level effets.\n\ndata\n\ndata can be any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.\n\nmodel\n\nmodel represents the likelihood function which you want to condition your data on. It has to be a subtype of Distributions.UnivariateDistribution. Currently, TuringGLM.jl supports:\n\nNormal (the default if not specified): linear regression\nTDist: robust linear regression\nBernoulli: logistic regression\nPoisson: Poisson count data regression\nNegativeBinomial: negative binomial robust count data regression\n\npriors\n\nTuringGLM.jl comes with state-of-the-art default priors, based on the literature and the Stan community. By default, turing_model will use DefaultPrior. But you can specify your own with priors=CustomPrior(predictors, intercept, auxiliary). All models take a predictors and intercept priors.\n\nIn robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.\n\nNon-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.\n\nExample for a non-robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), nothing)\n\nExample for a robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), Exponential(1))\n\nstandardize\n\nWhether true or false to standardize your data to mean 0 and standard deviation 1 before inference. Some science fields prefer to analyze and report effects in terms of standard devations. Also, whenever measurement scales differs, it is often suggested to standardize the effects for better comparison. By default, turing_model sets standardize=false.\n\n\n\n\n\n","category":"method"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"\n\n\n\n\n\n\n\n

      For the Robust Regression with Student-\\(t\\) distribution as the likelihood, we'll use a famous dataset called kidiq (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\";
      \n\n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n
      using TuringGLM
      \n\n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=TDist to indicate that the model is a robust regression with the Student's t-distribution:

      \n\n
      model = turing_model(fm, kidiq; model=TDist);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/robust_regression/#References","page":"Robust Regression","title":"References","text":"","category":"section"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/robust_regression.jl\"","category":"page"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"\n\n\n\n\n\n\n\n

      For our example on Negative Binomial Regression, let's use a famous dataset called roaches (Gelman & Hill, 2007), which is data on the efficacy of a pest management system at reducing the number of roaches in urban apartments. It has 262 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/roaches.csv\";
      \n\n\n
      roaches = CSV.read(download(url), DataFrame)
      \n
      yroach1treatmentseniorexposure2
      1153308.0100.8
      2127331.25100.6
      371.67101.0
      473.0101.0
      502.0101.14286
      600.0101.0
      77370.0100.8
      82464.56101.14286
      921.0001.0
      10214.0001.14286
      ...
      26280.0011.0
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and roach1, treatment, and senior as independent variables:

      \n\n
      fm = @formula(y ~ roach1 + treatment + senior)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  roach1(unknown)\n  treatment(unknown)\n  senior(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=NegativeBinomial to indicate that the model is a negative binomial regression:

      \n\n
      model = turing_model(fm, roaches; model=NegativeBinomial);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/negative_binomial_regression/#References","page":"Negative Binomial Regression","title":"References","text":"","category":"section"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/negative_binomial_regression.jl\"","category":"page"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"\n\n\n\n\n\n\n\n

      Let's cover the Linear Regression example with the kidiq dataset (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\"
      \n
      \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\"
      \n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n
      using TuringGLM
      \n\n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      Let's create our CustomPrior object. No need for the third (auxiliary) prior for this model so we leave it as nothing:

      \n\n
      priors = CustomPrior(Normal(0, 2.5), Normal(10, 20), nothing);
      \n\n\n\n

      We instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal). Notice that we are specifying the priors keyword argument:

      \n\n
      model = turing_model(fm, kidiq; priors);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/custom_priors/#References","page":"Custom Priors","title":"References","text":"","category":"section"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/custom_priors.jl\"","category":"page"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"\n\n\n\n\n\n\n\n

      Currently, TuringGLM only supports hierarchical models with a single random-intercept. This is done by using the (1 | group) inside the @formula macro.

      For our Hierarchical Model example, let's use a famous dataset called cheese (Boatwright, McCulloch & Rossi, 1999), which is data from cheese ratings. A group of 10 rural and 10 urban raters rated 4 types of different cheeses (A, B, C and D) in two samples. So we have \\(4 \\cdot 20 \\cdot 2 = 160\\) observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/cheese.csv\";
      \n\n\n
      cheese = CSV.read(download(url), DataFrame)
      \n
      cheeseraterbackgroundy
      1\"A\"1\"rural\"67
      2\"A\"1\"rural\"66
      3\"B\"1\"rural\"51
      4\"B\"1\"rural\"53
      5\"C\"1\"rural\"75
      6\"C\"1\"rural\"70
      7\"D\"1\"rural\"68
      8\"D\"1\"rural\"66
      9\"A\"2\"rural\"76
      10\"A\"2\"rural\"76
      ...
      160\"D\"10\"urban\"83
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and background is independent variable with a varying-intercept per cheese type:

      \n\n
      fm = @formula(y ~ (1 | cheese) + background)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  background(unknown)\n  (cheese)->1 | cheese
      \n\n\n

      We instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal):

      \n\n
      model = turing_model(fm, cheese);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/hierarchical_models/#References","page":"Hierarchical Models","title":"References","text":"","category":"section"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"
      \n

      Boatwright, P., McCulloch, R., & Rossi, P. (1999). Account-level modeling for trade promotion: An application of a constrained parameter hierarchical model. Journal of the American Statistical Association, 94(448), 1063–1073.

      \n\n","category":"page"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/hierarchical_models.jl\"","category":"page"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"\n\n\n\n\n\n\n\n

      Let's cover Linear Regression with a famous dataset called kidiq (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      For the purposes of this tutorial, we download the dataset from the TuringGLM repository:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      using TuringGLM
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\";
      \n\n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      Next, we instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal):

      \n\n
      model = turing_model(fm, kidiq);
      \n\n\n
      n_samples = 2_000;
      \n\n\n\n

      This model is a valid Turing model, which we can pass to the default sample function from Turing to get our parameter estimates. We use the NUTS sampler with 2000 samples.

      \n\n
      chns = sample(model, NUTS(), n_samples);
      \n\n\n
      plot_chains(chns)
      \n\n\n","category":"page"},{"location":"tutorials/linear_regression/#References","page":"Linear Regression","title":"References","text":"","category":"section"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/linear_regression.jl\"","category":"page"},{"location":"#TuringGLM","page":"Home","title":"TuringGLM","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Documentation for TuringGLM. Please file an issue if you run into any problems.","category":"page"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports Julia version 1.7+. We recommend always using it with the latest stable Julia release.","category":"page"},{"location":"#Getting-Started","page":"Home","title":"Getting Started","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM makes easy to specify Bayesian Generalized Linear Models using the formula syntax and returns an instantiated Turing model.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Heavily inspired by brms (uses RStan or CmdStanR) and bambi (uses PyMC3).","category":"page"},{"location":"#@formula","page":"Home","title":"@formula","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The @formula macro is extended from StatsModels.jl along with MixedModels.jl for the random-effects (a.k.a. group-level predictors).","category":"page"},{"location":"","page":"Home","title":"Home","text":"The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Example:","category":"page"},{"location":"","page":"Home","title":"Home","text":"@formula(y ~ x1 + x2 + x3)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).","category":"page"},{"location":"","page":"Home","title":"Home","text":"Example:","category":"page"},{"location":"","page":"Home","title":"Home","text":"@formula(y ~ (1 | group) + x1)","category":"page"},{"location":"#Data","page":"Home","title":"Data","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.","category":"page"},{"location":"#Supported-Models","page":"Home","title":"Supported Models","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports non-hierarchical and hierarchical models. For hierarchical models, only single random-intercept hierarchical models are supported.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Currently, for likelihoods TuringGLM.jl supports:","category":"page"},{"location":"","page":"Home","title":"Home","text":"Normal (the default if not specified): linear regression\nTDist: robust linear regression\nBernoulli: logistic regression\nPoisson: Poisson count data regression\nNegativeBinomial: negative binomial robust count data regression","category":"page"},{"location":"#Tutorials","page":"Home","title":"Tutorials","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Take a look at the tutorials for all supported likelihood and models.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"tutorials/linear_regression.md\",\n \"tutorials/logistic_regression.md\",\n \"tutorials/poisson_regression.md\",\n \"tutorials/negativebinomial_regression.md\",\n \"tutorials/robust_regression.md\",\n \"tutorials/hierarchical_models.md\",\n \"tutorials/custom_priors.md\"\n]\nDepth = 1","category":"page"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"\n\n\n\n\n\n\n\n

      For our tutorial on Logistic Regression, let's use a famous dataset called wells (Gelman & Hill, 2007), which is data from a survey of 3,200 residents in a small area of Bangladesh suffering from arsenic contamination of groundwater. Respondents with elevated arsenic levels in their wells had been encouraged to switch their water source to a safe public or private well in the nearby area and the survey was conducted several years later to learn which of the affected residents had switched wells. It has 3,200 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      using TuringGLM
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/wells.csv\";
      \n\n\n
      wells = CSV.read(download(url), DataFrame)
      \n
      switcharsenicdistassoceduc
      112.3616.82600
      210.7147.32200
      302.0720.967010
      411.1521.486012
      511.140.874114
      613.969.51819
      712.9780.71114
      813.2455.146010
      913.2852.64710
      1012.5275.07210
      ...
      302010.6620.84415
      \n\n\n

      Using switch as dependent variable and dist, arsenic, assoc, and educ as independent variables:

      \n\n
      fm = @formula(switch ~ dist + arsenic + assoc + educ)
      \n
      FormulaTerm\nResponse:\n  switch(unknown)\nPredictors:\n  dist(unknown)\n  arsenic(unknown)\n  assoc(unknown)\n  educ(unknown)
      \n\n\n

      Now we instantiate our model with turing_model passing a keyword argument model=Bernoulli to indicate that the model is a logistic regression:

      \n\n
      model = turing_model(fm, wells; model=Bernoulli);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/logistic_regression/#References","page":"Logistic Regression","title":"References","text":"","category":"section"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/logistic_regression.jl\"","category":"page"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"\n\n\n\n\n\n\n\n

      For our example on Poisson Regression, let's use a famous dataset called roaches (Gelman & Hill, 2007), which is data on the efficacy of a pest management system at reducing the number of roaches in urban apartments. It has 262 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/roaches.csv\";
      \n\n\n
      roaches = CSV.read(download(url), DataFrame)
      \n
      yroach1treatmentseniorexposure2
      1153308.0100.8
      2127331.25100.6
      371.67101.0
      473.0101.0
      502.0101.14286
      600.0101.0
      77370.0100.8
      82464.56101.14286
      921.0001.0
      10214.0001.14286
      ...
      26280.0011.0
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and roach1, treatment, and senior as independent variables:

      \n\n
      fm = @formula(y ~ roach1 + treatment + senior)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  roach1(unknown)\n  treatment(unknown)\n  senior(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=Poisson to indicate that the model is a Poisson Regression:

      \n\n
      model = turing_model(fm, roaches; model=Poisson);
      \n\n\n\n

      Sample the model using the NUTS sampler and 2,000 samples:

      \n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/poisson_regression/#References","page":"Poisson Regression","title":"References","text":"","category":"section"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/poisson_regression.jl\"","category":"page"}] +[{"location":"api/","page":"API reference","title":"API reference","text":"CurrentModule = TuringGLM","category":"page"},{"location":"api/#TuringGLM","page":"API reference","title":"TuringGLM","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"Documentation for TuringGLM.","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"Modules = [TuringGLM]","category":"page"},{"location":"api/#TuringGLM.CustomPrior","page":"API reference","title":"TuringGLM.CustomPrior","text":"CustomPrior(predictors, intercept, auxiliary)\n\nstruct to hold information regarding user-specified custom priors.\n\nUsage\n\nThe CustomPrior struct has 3 fields:\n\npredictors: the β coefficients.\nintercept: the α intercept.\nauxiliary: an auxiliary parameter.\n\nIn robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.\n\nNon-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.\n\n\n\n\n\n","category":"type"},{"location":"api/#TuringGLM.NegativeBinomial2-Union{Tuple{T}, Tuple{T, T}} where T<:Real","page":"API reference","title":"TuringGLM.NegativeBinomial2","text":"NegativeBinomial2(μ, ϕ)\n\nAn alternative parameterization of the Negative Binomial distribution:\n\ntextNegative-Binomial(n mid mu phi) sim binomn + phi - 1n left( fracmumu + phi right)^n left( fracphimu + phi right)^phi\n\nwhere the expectation is μ and variance is (μ + μ²/ϕ).\n\nThe alternative parameterization is inspired by the Stan's neg_binomial_2 function.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.center_predictors-Tuple{AbstractMatrix}","page":"API reference","title":"TuringGLM.center_predictors","text":"center_predictors(X::AbstractMatrix)\n\nCenters the columns of a matrix X of predictors to mean 0.\n\nReturns a tuple with:\n\nμ_X: 1xK Matrix of Float64s of the means of the K columns in the original X\n\nmatrix.\n\nX_centered: A Matrix of Float64s with the same dimensions as the original matrix\n\nX with the columns centered on mean μ=0.\n\nArguments\n\nX::AbstractMatrix: a matrix of predictors where rows are observations and columns are\n\nvariables.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.convert_str_to_indices-Tuple{AbstractVector}","page":"API reference","title":"TuringGLM.convert_str_to_indices","text":"convert_str_to_indices(v::AbstractVector)\n\nConverts a vector v to a vector of indices, i.e. a vector where all the entries are integers. Returns a tuple with the first element as the converted vector and the second element a Dict specifying which string is which integer.\n\nThis function is especially useful for random-effects varying-intercept hierarchical models. Normally v would be a vector of group membership with values such as \"group_1\", \"group_2\" etc. For random-effect models with varying-intercepts, Turing needs the group membership values to be passed as Ints.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_fixed_effects-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_fixed_effects","text":"data_fixed_effects(formula::FormulaTerm, data)\n\nConstructs the matrix X of fixed-effects (a.k.a. population-level) predictors.\n\nReturns a Matrix of the fixed-effects predictors variables in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_random_effects-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_random_effects","text":"data_random_effects(formula::FormulaTerm, data)\n\nConstructs the vector(s)/matrix(ces) Z(s) of random-effects (a.k.a. group-level) slope predictors.\n\nReturns a Dict{String, AbstractArray} of Vector/Matrix as values of the random-effects predictors slope variables (keys) in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.data_response-Union{Tuple{D}, Tuple{StatsModels.FormulaTerm, D}} where D","page":"API reference","title":"TuringGLM.data_response","text":"data_response(formula::FormulaTerm, data)\n\nConstructs the response y vector.\n\nReturns a Vector of the response variable in the formula and present inside data.\n\nArguments\n\nformula: a FormulaTerm created by @formula macro.\ndata: a data object that satisfies the\n\nTables.jl interface such as a DataFrame.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.get_idx-Union{Tuple{D}, Tuple{StatsModels.Term, D}} where D","page":"API reference","title":"TuringGLM.get_idx","text":"get_idx(term::Term, data)\n\nReturns a tuple with the first element as the ID vector of Ints that represent group membership for a specific random-effect intercept group t of observations present in data. The second element of the tuple is a Dict specifying which string is which integer in the ID vector.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.get_var-Union{Tuple{D}, Tuple{StatsModels.Term, D}} where D","page":"API reference","title":"TuringGLM.get_var","text":"get_var(term::Term, data)\n\nReturns the corresponding vector of column in data for the a specific random-effect slope term of observations present in data.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.has_ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.has_ranef","text":"has_ranef(formula::FormulaTerm)\n\nReturns true if any of the terms in formula is a FunctionTerm or false otherwise.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.intercept_per_ranef-Tuple{Tuple}","page":"API reference","title":"TuringGLM.intercept_per_ranef","text":"intercept_per_ranef(terms::Tuple{RandomEffectsTerm})\n\nReturns a vector of Strings where the entries are the grouping variables that have a group-level intercept.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.n_ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.n_ranef","text":"n_ranef(formula::FormulaTerm)\n\nReturns the number of RandomEffectsTerms in formula.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.ranef-Tuple{StatsModels.FormulaTerm}","page":"API reference","title":"TuringGLM.ranef","text":"ranef(formula::FormulaTerm)\n\nReturns a tuple of the FunctionTerms parsed as RandomEffectsTerms in formula. If there are no FunctionTerms in formula returns nothing.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.slope_per_ranef-Tuple{Tuple}","page":"API reference","title":"TuringGLM.slope_per_ranef","text":"slope_per_ranef(terms::Tuple{RandomEffectsTerm})\n\nReturns a SlopePerRanEf object where the entries are the grouping variables that have a group-level slope.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.standardize_predictors-Tuple{AbstractMatrix}","page":"API reference","title":"TuringGLM.standardize_predictors","text":"standardize_predictors(X::AbstractMatrix)\n\nStandardizes the columns of a matrix X of predictors to mean 0 and standard deviation 1.\n\nReturns a tuple with:\n\nμ_X: 1xK Matrix of Float64s of the means of the K columns in the original X\n\nmatrix.\n\nσ_X: 1xK Matrix of Float64s of the standard deviations of the K columns in the\n\noriginal X matrix.\n\nX_std: A Matrix of Float64s with the same dimensions as the original matrix\n\nX with the columns centered on mean μ=0 and standard deviation σ=1.\n\nArguments\n\nX::AbstractMatrix: a matrix of predictors where rows are observations and columns are\n\nvariables.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.standardize_predictors-Tuple{AbstractVector}","page":"API reference","title":"TuringGLM.standardize_predictors","text":"standardize_predictors(x::AbstractVector)\n\nStandardizes the vector x to mean 0 and standard deviation 1.\n\nReturns a tuple with:\n\nμ_X: Float64s of the mean of the original vector x.\nσ_X: Float64s of the standard deviations of the original vector x.\nx_std: A Vector of Float64s with the same length as the original vector\n\nx with the values centered on mean μ=0 and standard deviation σ=1.\n\nArguments\n\nx::AbstractVector: a vector.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.tuple_length-Union{Tuple{NTuple{N, Any}}, Tuple{N}} where N","page":"API reference","title":"TuringGLM.tuple_length","text":"tuple_length(::NTuple{N, Any}) where {N} = Int(N)\n\nThis is a hack to get the length of any tuple.\n\n\n\n\n\n","category":"method"},{"location":"api/#TuringGLM.turing_model-Union{Tuple{T}, Tuple{StatsModels.FormulaTerm, Any}} where T<:(UnivariateDistribution)","page":"API reference","title":"TuringGLM.turing_model","text":"turing_model(formula, data; model=Normal, priors=DefaultPrior(), standardize=false)\n\nCreate a Turing model using formula syntax and a data source.\n\nformula\n\nformula is the the same friendly interface to specify used to specify statistical models by brms, rstarnarm, bambi, StatsModels.jl and MixedModels.jl. The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.\n\nExample: @formula(y ~ x1 + x2 + x3).\n\nModerations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.\n\nRandom-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).\n\nExample: @formula(y ~ (1 | group) + x1).\n\nNotice: random-effects are currently only implemented for a single group-level intercept. Future versions of TuringGLM.jl will support slope random-effects and multiple group-level effets.\n\ndata\n\ndata can be any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.\n\nmodel\n\nmodel represents the likelihood function which you want to condition your data on. It has to be a subtype of Distributions.UnivariateDistribution. Currently, TuringGLM.jl supports:\n\nNormal (the default if not specified): linear regression\nTDist: robust linear regression\nBernoulli: logistic regression\nPoisson: Poisson count data regression\nNegativeBinomial: negative binomial robust count data regression\n\npriors\n\nTuringGLM.jl comes with state-of-the-art default priors, based on the literature and the Stan community. By default, turing_model will use DefaultPrior. But you can specify your own with priors=CustomPrior(predictors, intercept, auxiliary). All models take a predictors and intercept priors.\n\nIn robust models, e.g. Linear Regression with Student-t likelihood or Count Regression with Negative Binomial likelihood, often there is an extra auxiliary parameter that is needed to parametrize to model to overcome under- or over-dispersion. If you are specifying a custom prior for one of these type of models, then you should also specify a prior for the auxiliary parameter.\n\nNon-robust models do not need an auxiliary parameter and you can pass nothing as the auxiliary argument.\n\nExample for a non-robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), nothing)\n\nExample for a robust model: @formula(y, ...), data; priors=CustomPrior(Normal(0, 2.5), Normal(10, 5), Exponential(1))\n\nstandardize\n\nWhether true or false to standardize your data to mean 0 and standard deviation 1 before inference. Some science fields prefer to analyze and report effects in terms of standard devations. Also, whenever measurement scales differs, it is often suggested to standardize the effects for better comparison. By default, turing_model sets standardize=false.\n\n\n\n\n\n","category":"method"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"\n\n\n\n\n\n\n\n

      For the Robust Regression with Student-\\(t\\) distribution as the likelihood, we'll use a famous dataset called kidiq (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\";
      \n\n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n
      using TuringGLM
      \n\n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=TDist to indicate that the model is a robust regression with the Student's t-distribution:

      \n\n
      model = turing_model(fm, kidiq; model=TDist);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/robust_regression/#References","page":"Robust Regression","title":"References","text":"","category":"section"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/robust_regression/","page":"Robust Regression","title":"Robust Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/robust_regression.jl\"","category":"page"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"\n\n\n\n\n\n\n\n

      For our example on Negative Binomial Regression, let's use a famous dataset called roaches (Gelman & Hill, 2007), which is data on the efficacy of a pest management system at reducing the number of roaches in urban apartments. It has 262 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/roaches.csv\";
      \n\n\n
      roaches = CSV.read(download(url), DataFrame)
      \n
      yroach1treatmentseniorexposure2
      1153308.0100.8
      2127331.25100.6
      371.67101.0
      473.0101.0
      502.0101.14286
      600.0101.0
      77370.0100.8
      82464.56101.14286
      921.0001.0
      10214.0001.14286
      ...
      26280.0011.0
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and roach1, treatment, and senior as independent variables:

      \n\n
      fm = @formula(y ~ roach1 + treatment + senior)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  roach1(unknown)\n  treatment(unknown)\n  senior(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=NegativeBinomial to indicate that the model is a negative binomial regression:

      \n\n
      model = turing_model(fm, roaches; model=NegativeBinomial);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/negative_binomial_regression/#References","page":"Negative Binomial Regression","title":"References","text":"","category":"section"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/negative_binomial_regression/","page":"Negative Binomial Regression","title":"Negative Binomial Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/negative_binomial_regression.jl\"","category":"page"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"\n\n\n\n\n\n\n\n

      Let's cover the Linear Regression example with the kidiq dataset (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\"
      \n
      \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\"
      \n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n
      using TuringGLM
      \n\n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      Let's create our CustomPrior object. No need for the third (auxiliary) prior for this model so we leave it as nothing:

      \n\n
      priors = CustomPrior(Normal(0, 2.5), Normal(10, 20), nothing);
      \n\n\n\n

      We instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal). Notice that we are specifying the priors keyword argument:

      \n\n
      model = turing_model(fm, kidiq; priors);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/custom_priors/#References","page":"Custom Priors","title":"References","text":"","category":"section"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/custom_priors/","page":"Custom Priors","title":"Custom Priors","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/custom_priors.jl\"","category":"page"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"\n\n\n\n\n\n\n\n

      Currently, TuringGLM only supports hierarchical models with a single random-intercept. This is done by using the (1 | group) inside the @formula macro.

      For our Hierarchical Model example, let's use a famous dataset called cheese (Boatwright, McCulloch & Rossi, 1999), which is data from cheese ratings. A group of 10 rural and 10 urban raters rated 4 types of different cheeses (A, B, C and D) in two samples. So we have \\(4 \\cdot 20 \\cdot 2 = 160\\) observations and 4 variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/cheese.csv\";
      \n\n\n
      cheese = CSV.read(download(url), DataFrame)
      \n
      cheeseraterbackgroundy
      1\"A\"1\"rural\"67
      2\"A\"1\"rural\"66
      3\"B\"1\"rural\"51
      4\"B\"1\"rural\"53
      5\"C\"1\"rural\"75
      6\"C\"1\"rural\"70
      7\"D\"1\"rural\"68
      8\"D\"1\"rural\"66
      9\"A\"2\"rural\"76
      10\"A\"2\"rural\"76
      ...
      160\"D\"10\"urban\"83
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and background is independent variable with a varying-intercept per cheese type:

      \n\n
      fm = @formula(y ~ (1 | cheese) + background)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  background(unknown)\n  (cheese)->1 | cheese
      \n\n\n

      We instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal):

      \n\n
      model = turing_model(fm, cheese);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/hierarchical_models/#References","page":"Hierarchical Models","title":"References","text":"","category":"section"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"
      \n

      Boatwright, P., McCulloch, R., & Rossi, P. (1999). Account-level modeling for trade promotion: An application of a constrained parameter hierarchical model. Journal of the American Statistical Association, 94(448), 1063–1073.

      \n\n","category":"page"},{"location":"tutorials/hierarchical_models/","page":"Hierarchical Models","title":"Hierarchical Models","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/hierarchical_models.jl\"","category":"page"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"\n\n\n\n\n\n\n\n

      Let's cover Linear Regression with a famous dataset called kidiq (Gelman & Hill, 2007), which is data from a survey of adult American women and their respective children. Dated from 2007, it has 434 observations and 4 variables:

      For the purposes of this tutorial, we download the dataset from the TuringGLM repository:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      using TuringGLM
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/kidiq.csv\";
      \n\n\n
      kidiq = CSV.read(download(url), DataFrame)
      \n
      kid_scoremom_hsmom_iqmom_age
      1651121.11827
      298189.361925
      3851115.44327
      483199.449625
      5115192.745727
      6980107.90218
      7691138.89320
      81061125.14523
      9102181.619524
      1095195.073119
      ...
      43470191.253325
      \n\n\n

      Using kid_score as dependent variable and mom_hs along with mom_iq as independent variables with a moderation (interaction) effect:

      \n\n
      fm = @formula(kid_score ~ mom_hs * mom_iq)
      \n
      FormulaTerm\nResponse:\n  kid_score(unknown)\nPredictors:\n  mom_hs(unknown)\n  mom_iq(unknown)\n  mom_hs(unknown) & mom_iq(unknown)
      \n\n\n

      Next, we instantiate our model with turing_model without specifying any model, thus the default model will be used (model=Normal):

      \n\n
      model = turing_model(fm, kidiq);
      \n\n\n
      n_samples = 2_000;
      \n\n\n\n

      This model is a valid Turing model, which we can pass to the default sample function from Turing to get our parameter estimates. We use the NUTS sampler with 2000 samples.

      \n\n
      chns = sample(model, NUTS(), n_samples);
      \n\n\n
      plot_chains(chns)
      \n\n\n","category":"page"},{"location":"tutorials/linear_regression/#References","page":"Linear Regression","title":"References","text":"","category":"section"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/linear_regression/","page":"Linear Regression","title":"Linear Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/linear_regression.jl\"","category":"page"},{"location":"#TuringGLM","page":"Home","title":"TuringGLM","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Documentation for TuringGLM. Please file an issue if you run into any problems.","category":"page"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports Julia version 1.7+. We recommend always using it with the latest stable Julia release.","category":"page"},{"location":"#Getting-Started","page":"Home","title":"Getting Started","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM makes easy to specify Bayesian Generalized Linear Models using the formula syntax and returns an instantiated Turing model.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Heavily inspired by brms (uses RStan or CmdStanR) and bambi (uses PyMC3).","category":"page"},{"location":"#@formula","page":"Home","title":"@formula","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The @formula macro is extended from StatsModels.jl along with MixedModels.jl for the random-effects (a.k.a. group-level predictors).","category":"page"},{"location":"","page":"Home","title":"Home","text":"The syntax is done by using the @formula macro and then specifying the dependent variable followed by a tilde ~ then the independent variables separated by a plus sign +.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Example:","category":"page"},{"location":"","page":"Home","title":"Home","text":"@formula(y ~ x1 + x2 + x3)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Moderations/interactions can be specified with the asterisk sign *, e.g. x1 * x2. This will be expanded to x1 + x2 + x1:x2, which, following the principle of hierarchy, the main effects must also be added along with the interaction effects. Here x1:x2 means that the values of x1 will be multiplied (interacted) with the values of x2.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Random-effects (a.k.a. group-level effects) can be specified with the (term | group) inside the @formula, where term is the independent variable and group is the categorical representation (i.e., either a column of Strings or a CategoricalArray in data). You can specify a random-intercept with (1 | group).","category":"page"},{"location":"","page":"Home","title":"Home","text":"Example:","category":"page"},{"location":"","page":"Home","title":"Home","text":"@formula(y ~ (1 | group) + x1)","category":"page"},{"location":"#Data","page":"Home","title":"Data","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports any Tables.jl-compatible data interface. The most popular ones are DataFrames and NamedTuples.","category":"page"},{"location":"#Supported-Models","page":"Home","title":"Supported Models","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"TuringGLM supports non-hierarchical and hierarchical models. For hierarchical models, only single random-intercept hierarchical models are supported.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Currently, for likelihoods TuringGLM.jl supports:","category":"page"},{"location":"","page":"Home","title":"Home","text":"Normal (the default if not specified): linear regression\nTDist: robust linear regression\nBernoulli: logistic regression\nPoisson: Poisson count data regression\nNegativeBinomial: negative binomial robust count data regression","category":"page"},{"location":"#Tutorials","page":"Home","title":"Tutorials","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Take a look at the tutorials for all supported likelihood and models.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"tutorials/linear_regression.md\",\n \"tutorials/logistic_regression.md\",\n \"tutorials/poisson_regression.md\",\n \"tutorials/negativebinomial_regression.md\",\n \"tutorials/robust_regression.md\",\n \"tutorials/hierarchical_models.md\",\n \"tutorials/custom_priors.md\"\n]\nDepth = 1","category":"page"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"\n\n\n\n\n\n\n\n

      For our tutorial on Logistic Regression, let's use a famous dataset called wells (Gelman & Hill, 2007), which is data from a survey of 3,200 residents in a small area of Bangladesh suffering from arsenic contamination of groundwater. Respondents with elevated arsenic levels in their wells had been encouraged to switch their water source to a safe public or private well in the nearby area and the survey was conducted several years later to learn which of the affected residents had switched wells. It has 3,200 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      using TuringGLM
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/wells.csv\";
      \n\n\n
      wells = CSV.read(download(url), DataFrame)
      \n
      switcharsenicdistassoceduc
      112.3616.82600
      210.7147.32200
      302.0720.967010
      411.1521.486012
      511.140.874114
      613.969.51819
      712.9780.71114
      813.2455.146010
      913.2852.64710
      1012.5275.07210
      ...
      302010.6620.84415
      \n\n\n

      Using switch as dependent variable and dist, arsenic, assoc, and educ as independent variables:

      \n\n
      fm = @formula(switch ~ dist + arsenic + assoc + educ)
      \n
      FormulaTerm\nResponse:\n  switch(unknown)\nPredictors:\n  dist(unknown)\n  arsenic(unknown)\n  assoc(unknown)\n  educ(unknown)
      \n\n\n

      Now we instantiate our model with turing_model passing a keyword argument model=Bernoulli to indicate that the model is a logistic regression:

      \n\n
      model = turing_model(fm, wells; model=Bernoulli);
      \n\n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/logistic_regression/#References","page":"Logistic Regression","title":"References","text":"","category":"section"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/logistic_regression/","page":"Logistic Regression","title":"Logistic Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/logistic_regression.jl\"","category":"page"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"\n\n\n\n\n\n\n\n

      For our example on Poisson Regression, let's use a famous dataset called roaches (Gelman & Hill, 2007), which is data on the efficacy of a pest management system at reducing the number of roaches in urban apartments. It has 262 observations and the following variables:

      \n\n
      using CSV
      \n\n\n
      using DataFrames
      \n\n\n
      url = \"https://github.com/TuringLang/TuringGLM.jl/raw/main/data/roaches.csv\";
      \n\n\n
      roaches = CSV.read(download(url), DataFrame)
      \n
      yroach1treatmentseniorexposure2
      1153308.0100.8
      2127331.25100.6
      371.67101.0
      473.0101.0
      502.0101.14286
      600.0101.0
      77370.0100.8
      82464.56101.14286
      921.0001.0
      10214.0001.14286
      ...
      26280.0011.0
      \n\n
      using TuringGLM
      \n\n\n\n

      Using y as dependent variable and roach1, treatment, and senior as independent variables:

      \n\n
      fm = @formula(y ~ roach1 + treatment + senior)
      \n
      FormulaTerm\nResponse:\n  y(unknown)\nPredictors:\n  roach1(unknown)\n  treatment(unknown)\n  senior(unknown)
      \n\n\n

      We instantiate our model with turing_model passing a keyword argument model=Poisson to indicate that the model is a Poisson Regression:

      \n\n
      model = turing_model(fm, roaches; model=Poisson);
      \n\n\n\n

      Sample the model using the NUTS sampler and 2,000 samples:

      \n\n
      chn = sample(model, NUTS(), 2_000);
      \n\n\n
      plot_chains(chn)
      \n\n\n","category":"page"},{"location":"tutorials/poisson_regression/#References","page":"Poisson Regression","title":"References","text":"","category":"section"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"
      \n

      Gelman, A., & Hill, J. (2007). Data analysis using regression and multilevel/hierarchical models. Cambridge university press.

      \n\n","category":"page"},{"location":"tutorials/poisson_regression/","page":"Poisson Regression","title":"Poisson Regression","text":"EditURL = \"https://github.com/TuringLang/TuringGLM.jl/blob/main/docs/src/tutorials/poisson_regression.jl\"","category":"page"}] } diff --git a/dev/tutorials/custom_priors/index.html b/dev/tutorials/custom_priors/index.html index 27b36121..c77cf491 100644 --- a/dev/tutorials/custom_priors/index.html +++ b/dev/tutorials/custom_priors/index.html @@ -1,463 +1,5 @@ -Custom Priors · TuringGLM.jl - - - - - -
      GitHub
      - - - -
      GitHub
      - - - -
      GitHub
      - - - -
      GitHub
      - - - -
      GitHub
      - - - -
      GitHub
      - - - -
      GitHub