README.Rmd

---
output:
  md_document:
    variant: gfm
---

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
set.seed(0)
```

# bSims: Bird Point Count Simulator

<img src="https://raw.githubusercontent.com/psolymos/bSims/master/bsims.gif" align="right" style="padding-left:10px;background-color:white;" />

A highly scientific and utterly addictive bird point count simulator to test statistical assumptions and to aid survey design.

[![CRAN version](https://www.r-pkg.org/badges/version/bSims)](https://CRAN.R-project.org/package=bSims)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/bSims)](https://peter.solymos.org/bSims/)
[![check](https://github.com/psolymos/bSims/actions/workflows/check.yml/badge.svg)](https://github.com/psolymos/bSims/actions/workflows/check.yml)

> _"I've yet to see any problem, however complicated, which when you looked at it the right way didn't become still more complicated."_
> -- Poul Anderson, Call Me Joe 

> *“Love the simulation we're dreaming in”* - Dua Lipa, Physical

The goal of the package is to:

- test statistical assumptions,
- aid survey design,
- and have fun while doing it!

Design objectives:

- small (point count) scale implementation,
- habitat is considered homogeneous except for edge effects,
- realistic but efficient implementation of biological mechanisms and observation process,
- defaults chosen to reflect common practice and assumptions,
- extensible (PRs are welcome).

See the package in action in the [**QPAD
Book**](https://peter.solymos.org/qpad-book/).

Check out the [**QPAD workshop**](https://peter.solymos.org/qpad-workshop/).

Read/cite the paper [**Agent-based simulations improve abundance estimation**](https://rdcu.be/doDwI) (DOI 10.1007/s42977-023-00183-2).

## Install

CRAN version:

```{r eval=FALSE}
install.packages("bSims")
```

Development version:

```{r eval=FALSE}
remotes::install_github("psolymos/bSims")
```

See what is new in the [NEWS](NEWS.md) file.

## License

[GPL-2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)

Please cite (see `citation("bSims")`) the paper:

Solymos, P. 2023. Agent-based simulations improve abundance estimation. _Biologia Futura_ 74, 377--392 [DOI 10.1007/s42977-023-00183-2](https://doi.org/10.1007/s42977-023-00183-2), [link to PDF](https://rdcu.be/doDwI).

## Contributing

Feedback and contributions are welcome:

- submit feature request or report issues [here](https://github.com/psolymos/bSims/issues),
- fork the project and submit pull request, see [CoC](CODE_OF_CONDUCT.md).

## Examples

### Command line

```{r message=FALSE,warning=FALSE}
library(bSims)

phi <- 0.5
tau <- 1:3
dur <- 10
rbr <- c(0.5, 1, 1.5, Inf)
tbr <- c(3, 5, 10)

l <- bsims_init(10, 0.5, 1)
p <- bsims_populate(l, 1)
a <- bsims_animate(p, vocal_rate=phi, duration=dur)
o <- bsims_detect(a, tau=tau)

x <- bsims_transcribe(o, tint=tbr, rint=rbr)

get_table(x)

head(get_events(a))

head(get_detections(o))
```

### Shiny apps

A few [Shiny](https://shiny.posit.co/) apps come with the package.
These can be used to interactively explore the effects of different settings.

Compare distance functions:

```{r eval=FALSE}
run_app("distfunH")
run_app("distfunHER")
```

Compare simulation settings for single landscape:

```{r eval=FALSE}
run_app("bsimsH")
run_app("bsimsHER")
```

### Replicating simulations

Interactive sessions can be used to explore different settings.
Settings can be copied from the Shiny apps and replicated using the
`bsims_all` function: 

```{r}
b <- bsims_all(extent=5, road=1, density=c(1,1,0))
b
```

The object has handy methods:

```{r eval=FALSE}
b$settings()      # retrieve settings
b$new()           # replicate once
b$replicate(10)   # replicate 10x
```

The `$replicate()` function also runs on multiple cores:

```{r}
library(parallel)
b <- bsims_all(density=0.5)
B <- 4  # number of runs
nc <- 2 # number of cores

## sequential
system.time(bb <- b$replicate(B, cl=NULL))

## parallel clusters
cl <- makeCluster(nc)
## note: loading the package is optional
system.time(clusterEvalQ(cl, library(bSims)))
system.time(bb <- b$replicate(B, cl=cl))
stopCluster(cl)

## parallel forking
if (.Platform$OS.type != "windows") {
  system.time(bb <- b$replicate(B, cl=nc))
}
```