diff --git a/docs/src/api.md b/docs/src/api.md index 8bfee40f3..42b840280 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -1,6 +1,6 @@ # API -In addition to its own functionality, MixedModels.jl also implements extensive support for the [`StatsAPI.StatisticalModel`](https://github.com/JuliaStats/StatsAPI.jl/blob/main/src/statisticalmodel.jl) and [`StatsAPI.RegressionModel`](https://github.com/JuliaStats/StatsAPI.jl/blob/main/src/regressionmodel.jl) API. +In addition to its own functionality, `MixedModels.jl` also implements extensive support for the [`StatsAPI.StatisticalModel`](https://github.com/JuliaStats/StatsAPI.jl/blob/main/src/statisticalmodel.jl) and [`StatsAPI.RegressionModel`](https://github.com/JuliaStats/StatsAPI.jl/blob/main/src/regressionmodel.jl) API. ## Types @@ -55,9 +55,9 @@ vcov weights ``` -### MixedModels.jl "alternatives" and extensions to StatsAPI and GLM functions +### `MixedModels.jl` "alternatives" and extensions to StatsAPI and GLM functions -The following are MixedModels.jl-specific functions and not simply methods for functions defined in StatsAPI and GLM.jl. +The following are `MixedModels.jl`-specific functions and not simply methods for functions defined in `StatsAPI` and `GLM.jl`. ```julia coefpvalues diff --git a/docs/src/constructors.md b/docs/src/constructors.md index da09ecbfc..b6cf4a642 100644 --- a/docs/src/constructors.md +++ b/docs/src/constructors.md @@ -24,7 +24,7 @@ describe(DataFrame(dyestuff)) ### The `@formula` language in Julia -MixedModels.jl builds on the the *Julia* formula language provided by [StatsModels.jl](https://juliastats.org/StatsModels.jl/stable/formula/), which is similar to the formula language in *R* and is also based on the notation from Wilkinson and Rogers ([1973](https://dx.doi.org/10.2307/2346786)). There are two ways to construct a formula in Julia. The first way is to enclose the formula expression in the `@formula` macro: +`MixedModels.jl` builds on the *Julia* formula language provided by [StatsModels.jl](https://juliastats.org/StatsModels.jl/stable/formula/), which is similar to the formula language in *R* and is also based on the notation from Wilkinson and Rogers ([1973](https://dx.doi.org/10.2307/2346786)). There are two ways to construct a formula in Julia. The first way is to enclose the formula expression in the `@formula` macro: ```@docs @formula ``` @@ -35,7 +35,7 @@ The second way is to combine `Term`s with operators like `+`, `&`, `~`, and othe @formula(y ~ 1 + a + b + a & b) == (term(:y) ~ term(1) + term(:a) + term(:b) + term(:a) & term(:b)) ``` -MixedModels.jl provides additional formula syntax for representing *random-effects terms*. Most importantly, `|` separates random effects and their grouping factors (as in the formula extension used by the *R* package [`lme4`](https://cran.r-project.org/web/packages/lme4/index.html). Much like with the base formula language, `|` can be used within the `@formula` macro and to construct a formula programmatically: +`MixedModels.jl` provides additional formula syntax for representing *random-effects terms*. Most importantly, `|` separates random effects and their grouping factors (as in the formula extension used by the *R* package [`lme4`](https://cran.r-project.org/web/packages/lme4/index.html)). Much like with the base formula language, `|` can be used within the `@formula` macro and to construct a formula programmatically: ```@example Main @formula(y ~ 1 + a + b + (1 + a + b | g)) @@ -154,7 +154,7 @@ DisplayAs.Text(ans) # hide ### Simplifying the random effect correlation structure -MixedModels.jl estimates not only the *variance* of the effects for each random effect level, but also the *correlation* between the random effects for different predictors. +`MixedModels.jl` estimates not only the *variance* of the effects for each random effect level, but also the *correlation* between the random effects for different predictors. So, for the model of the *sleepstudy* data above, one of the parameters that is estimated is the correlation between each subject's random intercept (i.e., their baseline reaction time) and slope (i.e., their particular change in reaction time per day of sleep deprivation). In some cases, you may wish to simplify the random effects structure by removing these correlation parameters. This often arises when there are many random effects you want to estimate (as is common in psychological experiments with many conditions and covariates), since the number of random effects parameters increases as the square of the number of predictors, making these models difficult to estimate from limited data. @@ -171,7 +171,7 @@ fit(MixedModel, @formula(reaction ~ 1 + days + (1|subj) + (days|subj)), sleepstu DisplayAs.Text(ans) # hide ``` -Finally, for predictors that are categorical, MixedModels.jl will estimate correlations between each level. +Finally, for predictors that are categorical, `MixedModels.jl` will estimate correlations between each level. Notice the large number of correlation parameters if we treat `days` as a categorical variable by giving it contrasts: ```@example Main fit(MixedModel, @formula(reaction ~ 1 + days + (1 + days|subj)), sleepstudy, diff --git a/docs/src/index.md b/docs/src/index.md index 07005dbce..fd6eeddb8 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -4,8 +4,8 @@ CurrentModule = MixedModels ``` -*MixedModels.jl* is a Julia package providing capabilities for fitting and examining linear and generalized linear mixed-effect models. -It is similar in scope to the [*lme4*](https://github.com/lme4/lme4) package for `R`. +`MixedModels.jl` is a Julia package providing capabilities for fitting and examining linear and generalized linear mixed-effect models. +It is similar in scope to the [`lme4`](https://github.com/lme4/lme4) package for `R`. # Quick Start diff --git a/docs/src/mime.md b/docs/src/mime.md index c14d10b00..9dd1d16c8 100644 --- a/docs/src/mime.md +++ b/docs/src/mime.md @@ -1,9 +1,9 @@ # Alternative display and output formats -In the documentation, we have presented the output from MixedModels.jl in the same format you will see when working in the REPL. +In the documentation, we have presented the output from `MixedModels.jl` in the same format you will see when working in the REPL. You may have noticed, however, that output from other packages received pretty printing. -For example, DataFrames are converted into nice HTML tables. -In MixedModels, we recently (v3.2.0) introduced limited support for such pretty printing. +For example, `DataFrame`s are converted into nice HTML tables. +In `MixedModels.jl`, we recently (v3.2.0) introduced limited support for such pretty printing. (For more details on how the print and display system in Julia works, check out [this NextJournal post](https://nextjournal.com/sdanisch/julias-display-system).) In particular, we have defined Markdown, HTML and LaTeX output, i.e. `show` methods, for our types. diff --git a/docs/src/rankdeficiency.md b/docs/src/rankdeficiency.md index 3c8ac0444..44b874f2a 100644 --- a/docs/src/rankdeficiency.md +++ b/docs/src/rankdeficiency.md @@ -12,7 +12,7 @@ The simplest case of rank deficiency is a duplicated predictor or a predictor th However, rank deficiency can also arise in more subtle ways, such as from missing cells in a two-factor experimental design. Rank deficiency can also arise as an extreme case of multicollinearity. In all cases, it is important to remember that we can only assess the numerical rank of a matrix, which may be less than its theoretical rank, and that evaluation of this numerical rank requires setting some numerical tolerance levels. -These choices are not always well defined. +These choices are not always well-defined. In other words, the rank of a matrix is well-defined in theory but in practice can be difficult to evaluate. Rank deficiency can occur in two ways in mixed-effects models: in the fixed effects and in the random effects. @@ -24,7 +24,7 @@ The consequences of rank deficiency in the fixed effects are similar to those in If one or more predictors can be expressed as a linear combination of the other columns, then this column is redundant and the model matrix is rank deficient. Note however, that the redundant column is not defined uniquely. For example, in the case that of two columns `a` and `b` where `b = 2a`, then the rank deficiency can be handled by eliminating either `a` or `b`. -While we defined `b` here in terms of `a`, it may be that `b` is actually the more 'fundamental' predictor and hence we may define `a` in terms of `b` as `a = 0.5b`. +While we defined `b` here in terms of `a`, it may be that `b` is actually the more 'fundamental' predictor and hence we may define `a` in terms of `b` as `a = 0.5b`. The user may of course possess this information, but the choice is not apparent to the modelling software. As such, the handling of rank deficiency in `MixedModels.jl` should not be taken as a replacement for thinking about the nature of the predictors in a given model. @@ -35,12 +35,12 @@ move the surplus columns to the right side of the model matrix. In subsequent calculations, these columns are effectively ignored (as their estimates are zero and thus won't contribute to any other computations). For display purposes, this pivoting is unwound when the `coef` values are displayed. -Both the pivoted and unpivoted coefficients are available in MixedModels. -The [`fixef`](@ref) extractor returns the pivoted, truncated estimates (i.e. the non redundant terms), while the [`coef`](@ref) extractor returns the unpivoted estimates (i.e. all terms, included the redundant ones). +Both the pivoted and unpivoted coefficients are available in `MixedModels.jl`. +The [`fixef`](@ref) extractor returns the pivoted, truncated estimates (i.e. the non-redundant terms), while the [`coef`](@ref) extractor returns the unpivoted estimates (i.e. all terms, included the redundant ones). The same holds for the associated [`fixefnames`](@ref) and [`coefnames`](@ref). ### Pivoting is platform dependent -In MixedModels.jl, we use standard numerical techniques to detect rank deficiency. +In `MixedModels.jl`, we use standard numerical techniques to detect rank deficiency. We currently offer no guarantees as to which exactly of the standard techniques (pivoted QR decomposition, pivoted Cholesky decomposition, etc.) will be used. This choice should be viewed as an implementation detail. Similarly, we offer no guarantees as to which of columns will be treated as redundant.