Skip to content

Commit

Permalink
Compatibility updates and online documentation (#9)
Browse files Browse the repository at this point in the history
* add documentation + GH workflows

* MixedModels 3.x compat

* online documentation  and examples

* remove shrinkage2d from docs

* sample plot tweaks

* run CI on main

* the null test

* compat bounds

* workflow lint

* update readme
  • Loading branch information
palday authored May 13, 2021
1 parent 44d2b43 commit 919087d
Show file tree
Hide file tree
Showing 13 changed files with 237 additions and 10 deletions.
59 changes: 59 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
name: continuous-integration
on:
push:
branches:
- master
- main
paths-ignore:
- 'LICENSE.md'
- 'README.md'
- 'examples/**'
pull_request:
branches:
- master
- main
paths-ignore:
- 'LICENSE.md'
- 'README.md'
- 'examples/**'
jobs:
ci:
runs-on: ${{ matrix.os }}
strategy:
matrix:
version: [1.5, 1]
arch: [x64]
os: [ubuntu-18.04] # macos-10.15, windows-2019
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Julia Setup
uses: julia-actions/setup-julia@v1
with:
version: ${{ matrix.version }}
arch: ${{ matrix.arch }}
- name: Cache
uses: actions/cache@v1
env:
cache-name: cache-artifacts
with:
path: ~/.julia/artifacts
key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
restore-keys: |
${{ runner.os }}-test-${{ env.cache-name }}-
${{ runner.os }}-test-
${{ runner.os }}-
- name: Build
uses: julia-actions/julia-buildpkg@v1
- name: Test
uses: julia-actions/julia-runtest@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Coverage Process
uses: julia-actions/julia-processcoverage@v1
if: ${{ startsWith(matrix.os, 'ubuntu') && (matrix.version == '1') }}
- name: Coverage Upload
uses: codecov/codecov-action@v1
if: ${{ startsWith(matrix.os, 'ubuntu') && (matrix.version == '1') }}
with:
file: lcov.info
22 changes: 22 additions & 0 deletions .github/workflows/documenter.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: Documenter
on:
push:
branches:
- master
- main
tags: [v*]
pull_request:
branches:
- master
- main
jobs:
Documenter:
name: Documentation
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: julia-actions/julia-buildpkg@latest
- uses: julia-actions/julia-docdeploy@latest
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
4 changes: 2 additions & 2 deletions Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ MixedModels = "ff71e718-51f3-5ec2-a782-8ffcbfa3c316"

[compat]
AbstractPlotting = "0.18"
DataFrames = "1.1"
MixedModels = "3.6,4"
DataFrames = "1"
MixedModels = "3.6, 4"
julia = "1.5"

[extras]
Expand Down
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1 +1,20 @@
# MixedModelsMakie

[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![Stable Docs][docs-stable-img]][docs-stable-url]
[![Dev Docs][docs-dev-img]][docs-dev-url]
[![Codecov](https://codecov.io/gh/palday/MixedModelsMakie.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/palday/MixedModelsMakie.jl)

[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
[docs-dev-url]: https://palday.github.io/MixedModelsMakie.jl/dev

[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
[docs-stable-url]: https://palday.github.io/MixedModelsMakie.jl/stable

`MixedModelsMakie.jl` is a Julia package providing plotting capabilities for models fit with [MixedModels.jl](https://juliastats.org/MixedModels.jl/stable/).
Plotting is performed using the [Makie ecoysystem](https://makie.juliaplots.org/stable/), with the interface defined using `AbstractPlotting.jl` for compatibility across all Makie backends.

Note that the functionality here is currently early alpha development and so breaking changes are expected as we refine the interface.
Following [SemVer](https://semver.org/), these minor releases before 1.0 can introduce these breaking changes.
The release of 1.0 will be indication that we believe the interface is reasonably stable.
Minor refinements of graphical displays without changing the API are considered non-breaking.
9 changes: 9 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[deps]
CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
MixedModels = "ff71e718-51f3-5ec2-a782-8ffcbfa3c316"
MixedModelsMakie = "b12ae82c-6730-437f-aff9-d2c38332a376"

[compat]
CairoMakie = "0.4.7"
Documenter = "0.26"
15 changes: 15 additions & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
using Documenter
using MixedModelsMakie

makedocs(;
root = joinpath(dirname(pathof(MixedModelsMakie)), "..", "docs"),
sitename = "MixedModelsMakie",
doctest = true,
checkdocs = :exports,
pages = [
"index.md",
"api.md",
],
)

deploydocs(repo = "github.com/palday/MixedModelsMakie.jl.git", push_preview = true)
74 changes: 74 additions & 0 deletions docs/src/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
```@meta
CurrentModule = MixedModelsMakie
DocTestSetup = quote
using MixedModelsMakie
end
DocTestFilters = [r"([a-z]*) => \1", r"getfield\(.*##[0-9]+#[0-9]+"]
```

# MixedModelsMakie.jl API

## Caterpillar Plots

```@docs
RanefInfo
```

```@docs
ranefinfo
```

```@docs
caterpillar
```

```@docs
caterpillar!
```

```@example Caterpillar
using CairoMakie
CairoMakie.activate!(type = "svg")
using MixedModels
using MixedModelsMakie
sleepstudy = MixedModels.dataset(:sleepstudy)
fm1 = fit(MixedModel, @formula(reaction ~ 1 + days + (1 + days|subj)), sleepstudy)
subjre = ranefinfo(fm1)[:subj]
caterpillar!(Figure(; resolution=(800,600)), subjre)
```

```@example Caterpillar
caterpillar!(Figure(; resolution=(800,600)), subjre; orderby=2)
```

## Shrinkage Plots

```@docs
CoefByGroup
```

```@docs
shrinkage
```

```@docs
shrinkageplot
```

```@docs
shrinkageplot!
```

```@example Shrinkage
using CairoMakie
using MixedModels
using MixedModelsMakie
sleepstudy = MixedModels.dataset(:sleepstudy)
fm1 = fit(MixedModel, @formula(reaction ~ 1 + days + (1 + days|subj)), sleepstudy)
shrink = shrinkage(fm1)[:subj]
shrinkageplot!(Figure(; resolution=(800,600)), shrink)
```
Empty file added docs/src/examples.md
Empty file.
18 changes: 18 additions & 0 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# MixedModelsMakie.jl Documentation

```@meta
CurrentModule = MixedModelsMakie
```

*MixedModelsMakie.jl* is a Julia package providing plotting capabilities for models fit with [MixedModels.jl](https://juliastats.org/MixedModels.jl/stable/).

Note that the functionality here is currently early alpha development and so breaking changes are expected as we refine the interface.
Following [SemVer](https://semver.org/), these minor releases before 1.0 can introduce these breaking changes.
The release of 1.0 will be indication that we believe the interface is reasonably stable.

```@contents
Pages = [
"api.md",
]
Depth = 1
```
1 change: 1 addition & 0 deletions src/MixedModelsMakie.jl
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ module MixedModelsMakie
ranefinfo,
shrinkage,
shrinkageplot,
shrinkageplot!,
simplelinreg

include("shrinkage.jl")
Expand Down
9 changes: 6 additions & 3 deletions src/caterpillar.jl
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,10 @@
Information on random effects conditional modes/means, variances, etc.
Used for creating caterpillar plots
Used for creating caterpillar plots.
!!! note
This functionality may be moved upstream into MixedModels.jl in the near future.
"""
struct RanefInfo{T<:AbstractFloat}
cnames::Vector{String}
Expand All @@ -22,7 +25,7 @@ function ranefinfo(m::LinearMixedModel{T}) where {T}
val = sizehint!(RanefInfo[], length(fn))
for (re, eff, cv) in zip(m.reterms, ranef(m), condVar(m))
push!(
val,
val,
RanefInfo(
re.cnames,
re.levels,
Expand Down Expand Up @@ -72,4 +75,4 @@ of the random effects.
"""
function caterpillar(m::LinearMixedModel, gf::Symbol=first(fnames(m)))
caterpillar!(Figure(resolution=(1000,800)), ranefinfo(m)[gf])
end
end
13 changes: 10 additions & 3 deletions src/shrinkage.jl
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ Fields include:
- `fixed`: `AbstractVector{T}` of the global OLS estimates for the coefficients in `cnames` only.
- `condmodes`: `AbstractMatrix{T}` of size `length(levels) x length(cnames)` of the conditional means/modes for the random effects
- `grpest`: similar to `condmodes` but allowing for `Missing` values, giving the within group OLS estimates of the coefficients.
!!! note
This functionality may be moved upstream into MixedModels.jl in the near future.
"""
struct CoefByGroup{T<:AbstractFloat}
cnames::Vector{String}
Expand All @@ -24,14 +27,18 @@ end
Return a `NamedTuple{fnames(m), NTuple(k, CoefByGroup)}` of the coefficients by group for the grouping factors
"""
function shrinkage(m::LinearMixedModel{T}) where {T}
fenms = m.feterm.cnames
yvec = view(m.Xymat, :, size(m.Xymat, 2))
# should this be fixefnames or coefnames?
# need to think about when pivoting is occuring
fenms = fixefnames(m)
# returns a view from Xymat in MM4, or just the response vec in MM3.x
yvec = response(m)
ranefs = ranef(m)
cvec = sizehint!(CoefByGroup[], length(ranefs))
for (j, re) in enumerate(m.reterms)
cnms = re.cnames
cnms fenms || throw(ArgumentError("No corresponding fixed effect for random effects $(setdiff(cnms, fenms)): there is no estimated grand mean to measure shrinkage towards"))
Xmat = view(m.Xymat, :, [findfirst(==(nm), fenms) for nm in cnms])
# XXX Should m.X return a view into m.Xymat?
Xmat = view(m.X, :, [findfirst(==(nm), fenms) for nm in cnms])
levs = re.levels
refs = re.refs
grpest = Matrix{Union{Missing,T}}(missing, (length(levs), length(cnms)))
Expand Down
4 changes: 2 additions & 2 deletions test/runtests.jl
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
using MixedModelsMakie
using Test

@testset "MixedModelsMakie.jl" begin
# Write your tests here.
@testset "There are no tests" begin
@test true
end

2 comments on commit 919087d

@palday
Copy link
Owner Author

@palday palday commented on 919087d May 13, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/36698

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.1.0 -m "<description of version>" 919087d468f4b22629449620864e4369b7751fb2
git push origin v0.1.0

Please sign in to comment.