From b5883dd07fdf1e0fa11bfa4f70e16a230f10acd9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 30 Nov 2024 09:29:15 +0000 Subject: [PATCH] Added navbar and removed insert_navbar.sh --- dev/api/index.html | 461 ++++++++++++++++- dev/index.html | 461 ++++++++++++++++- dev/tutorials/custom_priors/index.html | 473 ++++++++++++++++- dev/tutorials/hierarchical_models/index.html | 472 ++++++++++++++++- dev/tutorials/linear_regression/index.html | 474 +++++++++++++++++- dev/tutorials/logistic_regression/index.html | 472 ++++++++++++++++- .../negative_binomial_regression/index.html | 472 ++++++++++++++++- dev/tutorials/poisson_regression/index.html | 473 ++++++++++++++++- dev/tutorials/robust_regression/index.html | 472 ++++++++++++++++- index.html | 1 + 10 files changed, 4141 insertions(+), 90 deletions(-) diff --git a/dev/api/index.html b/dev/api/index.html index 65ed4a9..b4e3132 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,2 +1,461 @@ -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 7df3947..f2300fd 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,461 @@ -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/tutorials/custom_priors/index.html b/dev/tutorials/custom_priors/index.html index 7cecf77..27b3612 100644 --- a/dev/tutorials/custom_priors/index.html +++ b/dev/tutorials/custom_priors/index.html @@ -1,5 +1,463 @@ -Custom Priors · TuringGLM.jl
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub
      + + + +
      GitHub