
<!-- README.md is generated from README.Rmd. Please edit that file -->

# lacunarity

<!-- badges: start -->

<!-- badges: end -->

**lacunarity** estimates the lacunarity and the generalized lacunarity
of unidimensional binary time series. Lacunarity is a scale-dependent
measure of *translational heterogeneity*: it describes how the gaps of a
pattern are distributed, and — unlike density alone — it tells apart
series that are clustered from series that are evenly spread.

## Methodology

For a sliding box of size $s$, the box mass $m$ is the number of ones it
covers. From the distribution of box masses, the lacunarity index is

$$\Lambda(s) = \frac{\langle m^2 \rangle}{\langle m \rangle^2} = 1 + \frac{\mathrm{Var}(m)}{\langle m \rangle^2} \ge 1,$$

so $\Lambda(s) = 1$ means a perfectly homogeneous pattern and larger
values mean gappier, more heterogeneous textures. The *generalized*
lacunarity $\Lambda_q(s) = \left(Z_{2q}(s)/Z_q(s)^2\right)^{1/q}$
extends this to an arbitrary moment order $q$, yielding a spectrum of
scaling exponents $\gamma(q)$. See `vignette("lacunarity")` for the full
theory and references (Allain & Cloitre, 1991; Vernon-Carter et al.,
2009).

## Installation

You can install the released version from
[CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("lacunarity")
```

and the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("Ikarobarreto/lacunarity")
```

## Example

`lac()` returns the lacunarity scaling exponent `y`, the lacunarities
`Ds` at each scale and the box scales `s`:

``` r
library(lacunarity)

x <- rbinom(1200, size = 1, prob = 0.8)
lac(x)
#> $y
#> [1] 0.01408786
#> 
#> $Ds
#> [1] 1.129157 1.068018 1.040669 1.024022 1.013987
#> 
#> $s
#>      [,1]
#> [1,]    2
#> [2,]    4
#> [3,]    8
#> [4,]   16
#> [5,]   32
```

Lacunarity captures texture, not just density. The series `z` (blocks of
ones and zeros) and `w` (a random shuffle of `z`) have the **same**
number of ones, yet very different lacunarities:

``` r
z <- c(rep(c(rep(1, 8), rep(0, 8)), 25), rep(c(rep(1, 16), rep(0, 16)), 25))
w <- sample(z)

c(density_z = mean(z), density_w = mean(w))      # identical density
#> density_z density_w 
#>       0.5       0.5
c(lac_z = lac(z)$y, lac_w = lac(w)$y)            # different lacunarity
#>     lac_z     lac_w 
#> 0.1908516 0.1142697
```

`genlac()` returns the generalized lacunarity; its scaling spectrum `yq`
over the moment orders `q` summarises how small and large gaps scale:

``` r
g <- genlac(x)
round(g$yq, 3)
#>  [1] -0.148 -0.157 -0.166 -0.176 -0.185 -0.192 -0.191 -0.162 -0.092 -0.029
#> [11]  0.014  0.020  0.023  0.025  0.027  0.027  0.028  0.028  0.028  0.028
```

See `vignette("lacunarity")` for plots and a full walkthrough.
