README.Rmd

---
output: github_document
bibliography: vignettes/bibliography.bib
nocite: '@*'
---

<!-- 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 = NULL
)
Sys.setenv(LANGUAGE = "en") # Force locale
```

# tabula <img width=120px src="man/figures/logo.png" align="right" />

<!-- badges: start -->
[![status-badge](https://ci.codeberg.org/api/badges/14696/status.svg)](https://ci.codeberg.org/repos/14696){.pkgdown-devel}
[![Code coverage](https://packages.tesselle.org/tabula/coverage/badge.svg)](https://packages.tesselle.org/tabula/coverage/){.pkgdown-devel}
[![Dependencies](https://tinyverse.netlify.app/badge/tabula)](https://cran.r-project.org/package=tabula){.pkgdown-devel}

[![r-universe](https://tesselle.r-universe.dev/badges/tabula)](https://tesselle.r-universe.dev/tabula){.pkgdown-devel}
[![CRAN Version](https://www.r-pkg.org/badges/version/tabula)](https://cran.r-project.org/package=tabula){.pkgdown-release}
[![CRAN checks](https://badges.cranchecks.info/worst/tabula.svg)](https://cran.r-project.org/web/checks/check_results_tabula.html){.pkgdown-release}
[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/tabula)](https://cran.r-project.org/package=tabula){.pkgdown-release}

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

[![DOI Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.1489944.svg)](https://doi.org/10.5281/zenodo.1489944)
[![DOI JOSS](https://joss.theoj.org/papers/10.21105/joss.01821/status.svg)](https://doi.org/10.21105/joss.01821)
[![SWH](https://archive.softwareheritage.org/badge/origin/https://codeberg.org/tesselle/tabula/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://codeberg.org/tesselle/tabula)
<!-- badges: end -->

## Overview

An easy way to examine archaeological count data. This package provides several tests and measures of diversity: heterogeneity and evenness (Brillouin, Shannon, Simpson, etc.), richness and rarefaction (Chao1, Chao2, ACE, ICE, etc.), turnover and similarity (Brainerd-Robinson, etc.). It allows to easily visualize count data and statistical thresholds: rank vs. abundance plots, heatmaps, @ford1962 and @bertin1977 diagrams, etc. **tabula** provides methods for:

* Diversity measurement: `diversity()`, `heterogeneity()`, `evenness()`, `richness()`, `rarefaction()`, `turnover()`.
* Similarity measurement and co-occurrence: `similarity()`, `occurrence()`.
* Assessing sample size and significance: `bootstrap()`, `jackknife()`, `simulate()`.
* @bertin1977 or @ford1962 (battleship curve) diagrams: `plot_bertin()`, `plot_ford()`.
* Seriograph [@desachy2004]: `seriograph()`, `matrigraph()`.
* Heatmaps: `plot_heatmap()`, `plot_spot()`.

[**kairos**](https://packages.tesselle.org/kairos/) is a companion package to **tabula** that provides functions for chronological modeling and dating of archaeological assemblages from count data.

---

```{r citation, echo=FALSE, comment='', results='asis'}
cite <- utils::citation("tabula")
print(cite, bibtex = FALSE)
```

## Installation

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

```{r cran-installation, eval=FALSE}
install.packages("tabula")
```

And the development version from [Codeberg](https://codeberg.org/) with:

```{r gh-installation, eval=FALSE}
# install.packages("remotes")
remotes::install_git("https://codeberg.org/tesselle/tabula")
```

## Usage

```{r packages-load, message=FALSE}
## Install extra packages (if needed)
# install.packages("folio")

## Load the package
library(tabula)
```

*It assumes that you keep your data tidy*: each variable (type/taxa) must be saved in its own column and each observation (sample/case) must be saved in its own row.

```{r ford, fig.width=8, fig.height=7, fig.align="center"}
## Data from Lipo et al. 2015
data("mississippi", package = "folio")

## Ford diagram
plot_ford(mississippi)
```

```{r occurrence, fig.width=7, fig.height=7, fig.align="center"}
## Co-occurrence of ceramic types
mississippi |> 
  occurrence() |> 
  plot_spot()
```

```{r sample-size, fig.width=5, fig.height=5, fig.show="hold", out.width='50%'}
## Data from Conkey 1980, Kintigh 1989, p. 28
data("chevelon", package = "folio")

## Measure diversity by comparing to simulated assemblages
chevelon |>
  heterogeneity(method = "shannon") |>
  simulate(seed = 12345) |>
  plot()

chevelon |>
  richness(method = "count") |>
  simulate(seed = 12345) |>
  plot()
```

## Translation

This package provides translations of user-facing communications, like messages, warnings and errors, and graphical elements (axis labels). The preferred language is by default taken from the locale. This can be overridden by setting of the environment variable `LANGUAGE` (you only need to do this once per session):

``` r
Sys.setenv(LANGUAGE = "<language code>")
```

Languages currently available are English (`en`) and French (`fr`).

## Contributing

Please note that the **tabula** project is released with a [Contributor Code of Conduct](https://www.tesselle.org/conduct.html). By contributing to this project, you agree to abide by its terms.

## References

```{r metadata, include=FALSE}
## Update codemeta.json
codemetar::write_codemeta(verbose = FALSE)

## Update CITATION.cff
cff_keys <- list(
  identifiers = list(
    list(description = "The concept DOI.",
         type = "doi",
         value = "10.5281/zenodo.1489944"),
    list(description = "The versioned DOI for version 0.9.0.",
         type = "doi",
         value = "10.5281/zenodo.1489945"),
    list(description = "The versioned DOI for version 1.0.0.",
         type = "doi",
         value = "10.5281/zenodo.1881131"),
    list(description = "The versioned DOI for version 1.1.0.",
         type = "doi",
         value = "10.5281/zenodo.2529084"),
    list(description = "The versioned DOI for version 1.2.0.",
         type = "doi",
         value = "10.5281/zenodo.2600844"),
    list(description = "The versioned DOI for version 1.3.0.",
         type = "doi",
         value = "10.5281/zenodo.3455385"),
    list(description = "The versioned DOI for version 1.4.0.",
         type = "doi",
         value = "10.5281/zenodo.3552904"),
    list(description = "The versioned DOI for version 1.5.0.",
         type = "doi",
         value = "10.5281/zenodo.3612110"),
    list(description = "The versioned DOI for version 1.5.1.",
         type = "doi",
         value = "10.5281/zenodo.3716163"),
    list(description = "The versioned DOI for version 1.6.0.",
         type = "doi",
         value = "10.5281/zenodo.4748807"),
    list(description = "The versioned DOI for version 1.6.1.",
         type = "doi",
         value = "10.5281/zenodo.4793496"),
    list(description = "The versioned DOI for version 1.7.0.",
         type = "doi",
         value = "10.5281/zenodo.6703727"),
    list(description = "The versioned DOI for version 1.8.0.",
         type = "doi",
         value = "10.5281/zenodo.7060361"),
    list(description = "The versioned DOI for version 2.0.0.",
         type = "doi",
         value = "10.5281/zenodo.7296619"),
    list(description = "The versioned DOI for version 3.0.0.",
         type = "doi",
         value = "10.5281/zenodo.8274042"),
    list(description = "The versioned DOI for version 3.0.1.",
         type = "doi",
         value = "10.5281/zenodo.10214364"),
    list(description = "The versioned DOI for version 3.1.0.",
         type = "doi",
         value = "10.5281/zenodo.11205411"),
    list(description = "The versioned DOI for version 3.1.1.",
         type = "doi",
         value = "10.5281/zenodo.13711170"),
    list(description = "The versioned DOI for version 3.2.0.",
         type = "doi",
         value = "10.5281/zenodo.14632153"),
    list(description = "The versioned DOI for version 3.2.1.",
         type = "doi",
         value = "10.5281/zenodo.15124670"),
    list(description = "The versioned DOI for version 3.3.0.",
         type = "doi",
         value = "10.5281/zenodo.15397990"),
    list(description = "The versioned DOI for version 3.3.1.",
         type = "doi",
         value = "10.5281/zenodo.15425370"),
    list(description = "The versioned DOI for version 3.3.2.",
         type = "doi",
         value = "10.5281/zenodo.17055704"),
    list(description = "The CRAN DOI",
         type = "doi",
         value = "10.32614/cran.package.tabula")
  )
)
cff <- cffr::cff_create("DESCRIPTION", keys = cff_keys)
if (cffr::cff_validate(cff)) cffr::cff_write(cff, outfile = "CITATION.cff")
```