Skip to content

Commit 26540e4

Browse files
abhroabhro
authored
Add docs and update actions (#127)
* Add dependabot.yml * Separate docs workflow into separate file * Add docs env * Ignore docs build files * Create docs folder structure * Activate docs workflow * Update codecov action version * Add compat for Documenter.jl * Allow docs push preview (for PRs)
1 parent 45b3291 commit 26540e4

File tree

7 files changed

+163
-30
lines changed

7 files changed

+163
-30
lines changed

‎.github/dependabot.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
2+
version: 2
3+
updates:
4+
- package-ecosystem: "github-actions"
5+
directory: "/" # Location of package manifests
6+
schedule:
7+
interval: "weekly"

‎.github/workflows/CI.yml‎

Lines changed: 6 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
name: CI
22
on:
33
pull_request:
4-
branches:
5-
- master
4+
branches: [master]
65
push:
7-
branches:
8-
- master
6+
branches: [master]
97
tags: '*'
108
jobs:
119
test:
@@ -23,7 +21,7 @@ jobs:
2321
arch:
2422
- x64
2523
steps:
26-
- uses: actions/checkout@v3
24+
- uses: actions/checkout@v4
2725
- uses: julia-actions/setup-julia@latest
2826
with:
2927
version: ${{ matrix.version }}
@@ -32,28 +30,7 @@ jobs:
3230
- uses: julia-actions/julia-buildpkg@latest
3331
- uses: julia-actions/julia-runtest@latest
3432
- uses: julia-actions/julia-processcoverage@latest
35-
- uses: codecov/codecov-action@v3
33+
- uses: codecov/codecov-action@v5
3634
with:
37-
file: lcov.info
38-
# docs:
39-
# name: Documentation
40-
# runs-on: ubuntu-latest
41-
# steps:
42-
# - uses: actions/checkout@v2
43-
# - uses: julia-actions/setup-julia@v1
44-
# with:
45-
# version: '1'
46-
# - run: |
47-
# julia --project=docs -e '
48-
# using Pkg
49-
# Pkg.develop(PackageSpec(path=pwd()))
50-
# Pkg.instantiate()'
51-
# - run: |
52-
# julia --project=docs -e '
53-
# using Documenter: doctest
54-
# using MYPACKAGE
55-
# doctest(MYPACKAGE)' # change MYPACKAGE to the name of your package
56-
# - run: julia --project=docs docs/make.jl
57-
# env:
58-
# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59-
# DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
35+
files: lcov.info
36+
token: ${{ secrets.CODECOV_TOKEN }}

‎.github/workflows/docs.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Documentation
2+
on:
3+
pull_request:
4+
branches: [master]
5+
push:
6+
branches: [master]
7+
tags: '*'
8+
jobs:
9+
documenter:
10+
name: Build Documentation
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: julia-actions/setup-julia@v2
15+
with:
16+
version: '1'
17+
- uses: julia-actions/cache@v2
18+
- uses: julia-actions/julia-docdeploy@v1
19+
env:
20+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
examples/.ipynb_checkpoints/*
2-
Manifest.toml
2+
Manifest.toml
3+
docs/build/

‎docs/Project.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
KernelDensity = "5ab0869b-81aa-558d-bb23-cbf5423bbe9b"
4+
5+
[compat]
6+
Documenter = "1"
7+
8+
[sources.KernelDensity]
9+
path = ".."

‎docs/make.jl‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
using Documenter
2+
using KernelDensity
3+
4+
makedocs(
5+
sitename = "KernelDensity.jl",
6+
modules = [KernelDensity],
7+
)
8+
deploydocs(
9+
repo = "github.com/JuliaStats/KernelDensity.jl.git",
10+
push_preview = true,
11+
)

‎docs/src/index.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
```@meta
2+
CurrentModule = KernelDensity
3+
```
4+
5+
# KernelDensity.jl
6+
7+
Kernel density estimators for Julia.
8+
9+
## Usage
10+
11+
### Univariate
12+
The main accessor function is `kde`:
13+
14+
```julia
15+
U = kde(data)
16+
```
17+
18+
will construct a `UnivariateKDE` object from the real vector `data`. The
19+
optional keyword arguments are
20+
* `boundary`: the lower and upper limits of the kde as a tuple. Due to the
21+
fourier transforms used internally, there should be sufficient spacing to
22+
prevent wrap-around at the boundaries.
23+
* `npoints`: the number of interpolation points to use. The function uses
24+
fast Fourier transforms (FFTs) internally, so for optimal efficiency this
25+
should be a power of 2 (default = 2048).
26+
* `kernel`: the distributional family from
27+
[Distributions.jl](https://github.com/JuliaStats/Distributions.jl) to use as
28+
the kernel (default = `Normal`). To add your own kernel, extend the internal
29+
`kernel_dist` function.
30+
* `bandwidth`: the bandwidth of the kernel. Default is to use Silverman's
31+
rule.
32+
33+
The `UnivariateKDE` object `U` contains gridded coordinates (`U.x`) and the density
34+
estimate (`U.density`). These are typically sufficient for plotting.
35+
A related function
36+
37+
``` kde_lscv(data) ```
38+
39+
will construct a `UnivariateKDE` object, with the bandwidth selected by
40+
least-squares cross validation. It accepts the above keyword arguments, except
41+
`bandwidth`.
42+
43+
44+
There are also some slightly more advanced interfaces:
45+
```julia
46+
kde(data, midpoints::R) where R<:AbstractRange
47+
```
48+
allows specifying the internal grid to use. Optional keyword arguments are
49+
`kernel` and `bandwidth`.
50+
51+
```julia
52+
kde(data, dist::Distribution)
53+
```
54+
allows specifying the exact distribution to use as the kernel. Optional
55+
keyword arguments are `boundary` and `npoints`.
56+
57+
```julia
58+
kde(data, midpoints::R, dist::Distribution) where R<:AbstractRange
59+
```
60+
allows specifying both the distribution and grid.
61+
62+
### Bivariate
63+
64+
The usage mirrors that of the univariate case, except that `data` is now
65+
either a tuple of vectors
66+
```julia
67+
B = kde((xdata, ydata))
68+
```
69+
or a matrix with two columns
70+
```julia
71+
B = kde(datamatrix)
72+
```
73+
Similarly, the optional arguments all now take tuple arguments:
74+
e.g. `boundary` now takes a tuple of tuples `((xlo,xhi),(ylo,yhi))`.
75+
76+
The `BivariateKDE` object `B` contains gridded coordinates (`B.x` and `B.y`) and the bivariate density
77+
estimate (`B.density`).
78+
79+
### Interpolation
80+
81+
The KDE objects are stored as gridded density values, with attached
82+
coordinates. These are typically sufficient for plotting (see above), but
83+
intermediate values can be interpolated using the
84+
[Interpolations.jl](https://github.com/tlycken/Interpolations.jl) package via the `pdf` method
85+
(extended from Distributions.jl).
86+
87+
```julia
88+
pdf(k::UnivariateKDE, x)
89+
pdf(k::BivariateKDE, x, y)
90+
```
91+
92+
where `x` and `y` are real numbers or arrays.
93+
94+
If you are making multiple calls to `pdf`, it will be more efficient to
95+
construct an intermediate `InterpKDE` to store the interpolation structure:
96+
97+
```julia
98+
ik = InterpKDE(k)
99+
pdf(ik, x)
100+
```
101+
102+
`InterpKDE` will pass any extra arguments to `interpolate`.
103+
104+
## API Reference
105+
106+
```@autodocs
107+
Modules = [KernelDensity]
108+
```

0 commit comments

Comments
 (0)