Add docs with Documenter

.travis.yml

@@ -15,4 +15,4 @@ notifications:
 #  - julia -e 'Pkg.clone(pwd()); Pkg.build("MultivariateTests"); Pkg.test("MultivariateTests"; coverage=true)'
 after_success:
   - julia -e 'Pkg.add("Coverage"); cd(Pkg.dir("MultivariateTests")); using Coverage; Coveralls.submit(Coveralls.process_folder())'
-#  - julia -e 'Pkg.add("Documenter"); cd(Pkg.dir("MultivariateTests")); include(joinpath("docs", "make.jl"))'
+  - julia -e 'Pkg.add("Documenter"); cd(Pkg.dir("MultivariateTests")); include(joinpath("docs", "make.jl"))'

README.md

@@ -2,6 +2,7 @@
 
 [![Travis](https://travis-ci.org/ararslan/MultivariateTests.jl.svg?branch=master)](https://travis-ci.org/ararslan/MultivariateTests.jl)
 [![Coveralls](https://coveralls.io/repos/github/ararslan/MultivariateTests.jl/badge.svg?branch=master)](https://coveralls.io/github/ararslan/MultivariateTests.jl?branch=master)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://ararslan.github.io/MultivariateTests.jl/latest)
 
 This package provides utilities for multivariate statistical hypothesis testing in Julia.
 It extends the framework provided by

docs/make.jl

@@ -0,0 +1,19 @@
+using Documenter
+using MultivariateTests
+
+makedocs(modules=[MultivariateTests],
+         clean=false,
+         format=:html,
+         sitename="MultivariateTests.jl",
+         authors="Alex Arslan and other contributors",
+         pages=Any["Home" => "index.md",
+                   "Measures of Dispersion" => "dispersion.md",
+                   "Partial Correlation" => "partialcor.md",
+                   "Equality of Mean Vectors" => "hotelling.md",
+                   "Equality of Covariance Matrices" => "covariance.md"])
+
+deploydocs(repo="github.com/ararslan/MultivariateTests.jl.git",
+           target="build",
+           deps=nothing,
+           make=nothing,
+           julia="0.6")

docs/src/covariance.md

@@ -0,0 +1,10 @@
+# Bartlett's test
+
+Bartlett's test for equality of two variance-covariance matrices is provided.
+This is equivalent to Box's ``M``-test for two groups.
+
+## API
+
+```@docs
+MultivariateTests.BartlettsTest
+```

docs/src/dispersion.md

@@ -0,0 +1,32 @@
+# Measures of dispersion
+
+Two summary statistics are provided, both of which are generalizations of the sample
+variance to multivariate data.
+
+The first is the *generalized variance* of Wilks (1960), which provides a scalar
+measure of multidimensional scatter.
+For a random vector ``X``, the generalized variance is defined as the determinant of the
+sample variance-covariance matrix of ``X``, i.e. ``|\text{Cov}(X)|``.
+Note that this can be 0 if there is linear dependence among the columns of ``X``.
+
+The second is the *total variance*.
+For a random vector ``X``, the total variance is the matrix trace of the sample
+variance-covariance matrix of ``X``, i.e. the sum of the sample variances of the columns
+of ``X``.
+This can only be 0 if there is only a single observation.
+
+When ``X`` has only one column, both of these measures are equivalent to the sample
+variance of the column.
+
+## API
+
+```@docs
+MultivariateTests.genvar
+MultivariateTests.totalvar
+```
+
+## References
+
+Wilks, S.S. (1960). "Multidimensional Statistical Scatter." In *Contributions to
+Probability and Statistics*, I. Olkin et al., ed. Stanford University Press, Stanford,
+CA, pp. 486-503.

docs/src/hotelling.md

@@ -0,0 +1,12 @@
+# Hotelling's ``T^2`` test
+
+The HypothesisTests framework is extended here to include Hotelling's ``T^2`` test for
+one and two samples.
+
+## API
+
+```@docs
+MultivariateTests.OneSampleHotellingT2
+MultivariateTests.EqualCovHotellingT2
+MultivariateTests.UnequalCovHotellingT2
+```

docs/src/index.md

@@ -0,0 +1,24 @@
+# MultivariateTests.jl
+
+MultivariateTests is a Julia package that extends the framework provided by the
+[HypothesisTests](https://github.com/JuliaStats/HypothesisTests.jl) to include
+functionality for multivariate statistics.
+
+## Functionality
+
+```@contents
+Pages = [
+    "dispersion.md",
+    "partialcor.md",
+    "hotelling.md",
+    "covariance.md",
+]
+Depth = 1
+```
+
+## Acknowledgements
+
+Initial work on this package by Alex Arslan was part of a research project for
+the master's program in applied statistics at Penn State University.
+Alex thanks Andreas Noack, Jiahao Chen, Moritz Schauer, and Simon Byrne for
+initial feedback and discussion in the early stages of development.

docs/src/partialcor.md

@@ -0,0 +1,18 @@
+# Partial correlation
+
+This package provides a function for computing the partial correlation directly and
+another for testing the hypothesis of zero partial correlation using the HypothesisTests
+framework.
+
+Partial correlation is a generalization of correlation to conditional distributions;
+it's akin to Pearson's correlation, substituting conditional variances and covariances in
+the computation.
+It can be thought of as the correlation between two random variables for the subpopulation
+defined by the conditional variable(s).
+
+## API
+
+```@docs
+MultivariateTests.partialcor
+MultivariateTests.PartialCorTest
+```

src/covariance.jl

@@ -18,6 +18,15 @@ struct BartlettsTest <: CovarianceEqualityTest
     ny::Int
 end
 
+"""
+    BartlettsTest(X::AbstractMatrix, Y::AbstractMatrix)
+
+Perform Bartlett's test of the hypothesis that the covariance matrices of `X` and `Y`
+are equal.
+
+!!! note
+    Bartlett's test is sensitive to departures from multivariate normality.
+"""
 function BartlettsTest(X::AbstractMatrix, Y::AbstractMatrix)
     nx, p = size(X)
     ny, q = size(Y)

src/hotelling.jl

@@ -31,6 +31,12 @@ end
 StatsBase.nobs(T::OneSampleHotellingT2) = T.n
 StatsBase.dof(T::OneSampleHotellingT2) = (T.p, T.n - T.p)
 
+"""
+    OneSampleHotellingT2(X::AbstractMatrix, μ₀=<zero vector>)
+
+Perform a one sample Hotelling's ``T^2`` test of the hypothesis that the vector of
+column means of `X` is equal to `μ₀`.
+"""
 function OneSampleHotellingT2(X::AbstractMatrix{T},
                               μ₀::AbstractVector=fill(middle(zero(T)), size(X, 2))) where T
     n, p = size(X)
@@ -44,7 +50,12 @@ function OneSampleHotellingT2(X::AbstractMatrix{T},
     return OneSampleHotellingT2(T², F, n, p, μ₀, x̄, S)
 end
 
-# paired
+"""
+    OneSampleHotellingT2(X::AbstractMatrix, Y::AbstractMatrix, μ₀=<zero vector>)
+
+Perform a paired Hotelling's ``T^2`` test of the hypothesis that the vector of mean
+column differences between `X` and `Y` is equal to `μ₀`.
+"""
 function OneSampleHotellingT2(X::AbstractMatrix{T}, Y::AbstractMatrix{S},
                               μ₀::AbstractVector=fill(middle(zero(T), zero(S)), size(X, 2))) where {T,S}
     p, nx, ny = checkdims(X, Y)
@@ -72,6 +83,13 @@ struct EqualCovHotellingT2 <: HotellingT2Test
     S::Matrix
 end
 
+"""
+    EqualCovHotellingT2(X::AbstractMatrix, Y::AbstractMatrix)
+
+Perform a two sample Hotelling's ``T^2`` test of the hypothesis that the difference in
+the mean vectors of `X` and `Y` is zero, assuming that `X` and `Y` have equal covariance
+matrices.
+"""
 function EqualCovHotellingT2(X::AbstractMatrix, Y::AbstractMatrix)
     p, nx, ny = checkdims(X, Y)
     Δ = vec(mean(X, 1) .- mean(Y, 1))
@@ -104,6 +122,13 @@ struct UnequalCovHotellingT2 <: HotellingT2Test
     S::Matrix
 end
 
+"""
+    UnequalCovHotellingT2(X::AbstractMatrix, Y::AbstractMatrix)
+
+Perform a two sample Hotelling's ``T^2`` test of the hypothesis that the difference in
+the mean vectors of `X` and `Y` is zero, without assuming that `X` and `Y` have equal
+covariance matrices.
+"""
 function UnequalCovHotellingT2(X::AbstractMatrix, Y::AbstractMatrix)
     p, nx, ny = checkdims(X, Y)
     Δ = vec(mean(X, 1) .- mean(Y, 1))

src/partialcor.jl

@@ -1,9 +1,9 @@
 # Partial correlation
 
 """
-    partialcor(X, Y, Z)
+    partialcor(x, y, Z)
 
-Compute the partial correlation of the vectors `X` and `Y` given `Z`, which can be
+Compute the partial correlation of the vectors `x` and `y` given `Z`, which can be
 a vector or matrix.
 """
 function partialcor(x::AbstractVector, y::AbstractVector, Z::AbstractVecOrMat)
@@ -62,10 +62,10 @@ function _partialcor(x::AbstractVector, μx, y::AbstractVector, μy, z::Abstract
 end
 
 """
-    PartialCorTest(X, Y, Z)
+    PartialCorTest(x, y, Z)
 
-Perform a t-test for the hypothesis that the partial correlation of `X` and `Y` given
-`Z` is zero against the alternative that it's nonzero.
+Perform a t-test for the hypothesis that ``\\text{Cor}(x,y|Z=z) = 0``, i.e. the partial
+correlation of vectors `x` and `y` given the matrix `Z` is zero.
 
 Implements `pvalue` and `confint`. See also [`partialcor`](@ref).
 """