README.Rmd

---
output: github_document
---

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



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dev = "ragg_png",
  dpi = 300
)
```

# densityarea <a href="https://jofrhwld.github.io/densityarea/"><img src="man/figures/logo.svg" align="right" height="139" alt="densityarea website" /></a>

<!-- badges: start -->
[![R-CMD-check](https://github.com/JoFrhwld/densityarea/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/JoFrhwld/densityarea/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/densityarea)](https://CRAN.R-project.org/package=densityarea)
<!-- badges: end -->

The package `{ggdensity}`[^1] allows for plotting interpretable bivariate densities by using highest density ranges (HDRs). For example:

[^1]: Otto J, Kahle D (2023). *ggdensity: Interpretable Bivariate Density Visualization with 'ggplot2'*. <https://jamesotto852.github.io/ggdensity/> <https://github.com/jamesotto852/ggdensity/>

```{r}
#| fig-width: 4
#| fig-height: 3
#| out-width: 50%
#| fig-align: center
library(tibble)
library(ggplot2)
library(ggdensity)

set.seed(10)
df <- tibble(
  x = c(rnorm(100), rnorm(100, mean = 3)),
  y = c(rnorm(100), rnorm(100, mean = 3))
)

ggplot(df, aes(x,y))+
  stat_hdr()
```

`{densityarea}` gives direct access to these HDRs, either as data frames or as [simple features](https://r-spatial.github.io/sf/), for further analysis.

## Installation

You can install `{densityarea}` from CRAN with:
```r
install.packages("densityarea")
```

Or you can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("JoFrhwld/densityarea")
```

## Example

The use case the package was initially developed for was for estimating vowel space areas.

```{r}
#| label: setup
#| message: false
library(densityarea)
library(dplyr)
library(tidyr)
library(sf)

data(s01)

# initial data processing

s01 |> 
  mutate(lF1 = -log(F1),
         lF2 = -log(F2))->
  s01
```

To get this speaker's vowel space area we can pass the data through `dplyr::reframe()`

```{r}
s01 |> 
  reframe(
    density_area(lF2, lF1, probs = 0.8)
  )
```


Or, we could get the spatial polygon associated with the 80% probability level

```{r}
s01 |> 
  reframe(
    density_polygons(lF2, lF1, probs = 0.8, as_sf = T)
  )
```
## For more

For more details on using `{densityarea}`, see , and for
further information on using spatial polygons, see `vignette("sf-operations")`.