# animetric

*An R package for calculating movement-based metrics*

The primary aim of the *animetric* package is to provide methods for
calculating movement-based metrics, including kinematics, navigational
statistics, and social interaction measures.

## Installation

You can install the development version of *animetric* with:

``` r

install.packages('animetric', repos = c('https://animovement.r-universe.dev', 'https://cloud.r-project.org'))
```

Once you have installed the package, you can load it with:

``` r

library("animetric")
```

## Citation

If you enjoy the package, please make sure to cite it. If you find a
bug, feel free to open an issue.

To cite *animetric* in publications use:

``` r

citation("animetric")
#> To cite animetric in publications, please cite the animovement toolbox
#> as a whole (the first entry below). If your work used only animetric,
#> you may cite the package directly instead (the second entry).
#> 
#>   Roald-Arbøl M (2026). "animovement: An R toolbox for analysing
#>   movement across space and time." doi:10.5281/zenodo.13235277
#>   <https://doi.org/10.5281/zenodo.13235277>.
#>   <https://animovement.dev/animovement/>.
#> 
#>   Roald-Arbøl M (2026). "animetric: An R package for calculating
#>   movement-based metrics." doi:10.5281/zenodo.17818613
#>   <https://doi.org/10.5281/zenodo.17818613>.
#>   <https://animovement.dev/animetric/>.
#> 
#> To see these entries in BibTeX format, use 'print(<citation>,
#> bibtex=TRUE)', 'toBibtex(.)', or set
#> 'options(citation.bibtex.max=999)'.
```

# Package index

## Add

These return your aniframe with something added: columns of per-row
measures, a declared orientation, or a derived point.

- [`add_kinematics()`](https://animovement.dev/animetric/reference/add_kinematics.md)
  : Add kinematic measures to trajectory data
- [`add_tortuosity()`](https://animovement.dev/animetric/reference/add_tortuosity.md)
  : Add tortuosity measures over sliding windows
- [`add_nnd()`](https://animovement.dev/animetric/reference/add_nnd.md)
  : Add the distance to the n-th nearest neighbour
- [`add_orientation()`](https://animovement.dev/animetric/reference/add_orientation.md)
  **\[experimental\]** : Declare orientation from the positions of
  points
- [`add_point()`](https://animovement.dev/animetric/reference/add_point.md)
  : Add a derived point to an anipoint

## Summarise

One row per group: the distribution of per-row measures with
[`summarise_aniframe()`](https://animovement.dev/animetric/reference/summarise_aniframe.md),
or the geometry of each whole trajectory with
[`summarise_path()`](https://animovement.dev/animetric/reference/summarise_path.md).

- [`summarise_aniframe()`](https://animovement.dev/animetric/reference/summarise_aniframe.md)
  [`summarize_aniframe()`](https://animovement.dev/animetric/reference/summarise_aniframe.md)
  **\[experimental\]** : Summarise the time series of an aniframe
- [`summarise_path()`](https://animovement.dev/animetric/reference/summarise_path.md)
  [`summarize_path()`](https://animovement.dev/animetric/reference/summarise_path.md)
  : Summarise each trajectory as a whole

## Compute

These functions are cogs used in the `add_` and `summarise_` functions.

- [`compute_gradient()`](https://animovement.dev/animetric/reference/compute_gradient.md)
  : Compute numerical derivatives on possibly uneven grids

- [`differentiate()`](https://animovement.dev/animetric/reference/differentiate.md)
  : Differentiate a numeric series (optionally repeatedly)

- [`compute_straightness()`](https://animovement.dev/animetric/reference/compute_straightness.md)
  : Compute straightness index from precomputed vectors

- [`compute_sinuosity()`](https://animovement.dev/animetric/reference/compute_sinuosity.md)
  : Compute sinuosity index from precomputed vectors

- [`compute_emax()`](https://animovement.dev/animetric/reference/compute_emax.md)
  : Compute E_max (maximum expected displacement) from pre‑computed
  vectors

- [`compute_min_step()`](https://animovement.dev/animetric/reference/compute_min_step.md)
  **\[experimental\]** :

  The minimum step `"auto"` chooses for each trajectory

- [`compute_point()`](https://animovement.dev/animetric/reference/compute_point.md)
  : Compute a derived point of an identity level

- [`compute_nnd()`](https://animovement.dev/animetric/reference/compute_nnd.md)
  : Compute nearest neighbour distances within one group

## Deprecated

Kept for one release; see each page for its replacement.

- [`calculate_kinematics()`](https://animovement.dev/animetric/reference/calculate_kinematics.md)
  **\[deprecated\]** : Calculate kinematic measures from trajectory data
- [`calculate_tortuosity()`](https://animovement.dev/animetric/reference/calculate_tortuosity.md)
  **\[deprecated\]** : Calculate tortuosity metrics over sliding windows
- [`calculate_nnd()`](https://animovement.dev/animetric/reference/calculate_nnd.md)
  **\[deprecated\]** : Calculate distance to the n-th nearest neighbour
- [`summarise_kinematics()`](https://animovement.dev/animetric/reference/summarise_kinematics.md)
  [`summarize_kinematics()`](https://animovement.dev/animetric/reference/summarise_kinematics.md)
  **\[deprecated\]** : Calculate kinematic summary statistics
- [`summarise_tortuosity()`](https://animovement.dev/animetric/reference/summarise_tortuosity.md)
  [`summarize_tortuosity()`](https://animovement.dev/animetric/reference/summarise_tortuosity.md)
  **\[deprecated\]** : Calculate tortuosity summary statistics
- [`add_centroid()`](https://animovement.dev/animetric/reference/add_centroid.md)
  **\[deprecated\]** : Add a centroid to an anipoint
- [`compute_centroid()`](https://animovement.dev/animetric/reference/compute_centroid.md)
  **\[deprecated\]** : Compute the centroid of an identity level
- [`is_aniframe_kin()`](https://animovement.dev/animetric/reference/is_aniframe_kin.md)
  **\[deprecated\]** : Test whether a frame holds kinematics