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%"
)
```

# ggethos <a href="https://matiasandina.github.io/ggethos/"><img src="man/figures/logo.png" align="right" height="138" /></a>

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/ggethos)](https://CRAN.R-project.org/package=ggethos)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

The goal of `ggethos` is to provide a user-frienldy way to plot ethograms using `ggplot2`.

## Installation

At this point, this is an experimental package, and you can only install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("matiasandina/ggethos")
```

Once it's on CRAN, you can install the released version of ggethos from [CRAN](https://CRAN.R-project.org) with:

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

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

``` r
# install.packages("devtools")
devtools::install_github("matiasandina/ggethos")
```
## Example

This is a basic example of plotting ethograms with `ggethos`:

```{r example, message=F, warning=F}
library(ggplot2)
library(ggethos)
library(dplyr)
wombats %>% 
  group_by(wombat) %>% 
  slice(1:2)
```
Let's plot the behavior of the wombats 

```{r}
# x axis will be in sample space
ggplot(wombats, aes(y=wombat, behaviour=behaviour)) + geom_ethogram() 
```

Let's look at them using a proper x axis and separating by trials:

```{r, warning=FALSE, message=F}
# x axis will be in seconds
ggplot(wombats, aes(x=seconds, 
                    y=wombat, 
                    behaviour=behaviour,
                    color=behaviour)) + 
  geom_ethogram() +
  facet_wrap(~trial)
```

Can we align the trials? Yes! Use `align_trials = TRUE`: 

```{r, warning=FALSE, message=F}
# x axis will be in seconds
# trials re-aligned
ggplot(wombats, aes(x=seconds, 
                    y=wombat, 
                    behaviour=behaviour,
                    color=behaviour)) + 
  geom_ethogram(align_trials = T) +
  facet_wrap(~trial)
```


## Issues

This is a preliminary release and the package is still very much experimental. Please [file issues](https://github.com/matiasandina/ggethos/issues) to improve it.