README.Rmd

---
output: github_document
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE
  , echo = FALSE
  , comment = "#>"
  , fig.path = "README_files/README-"
  , out.width = "100%"
)
includeFigure = function(x) {
  knitr::include_graphics(file.path("README_files", x))
}
```

```{r}
includeFigure("RdistanceTopBanner.PNG")
```

<!-- badges: start -->
<center> 

[![CRAN Version](http://www.r-pkg.org/badges/version/Rdistance)](http://www.r-pkg.org/pkg/Rdistance)
[![CRAN Downloads](http://cranlogs.r-pkg.org/badges/Rdistance)](http://cran.rstudio.com/web/packages/Rdistance/index.html)
[![CRAN Total Downloads](http://cranlogs.r-pkg.org/badges/grand-total/Rdistance)](http://www.r-pkg.org/pkg/Rdistance)
[![codecov](https://codecov.io/gh/tmcd82070/Rdistance/branch/master/graph/badge.svg)](https://codecov.io/gh/tmcd82070/Rdistance)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)

[![](https://img.shields.io/github.ghproxy.topmit-activity/m/tmcd82070/Rdistance)](https://github.com/tmcd82070/Rdistance/commits/master)
![](https://img.shields.io/github.ghproxy.topmits-since/tmcd82070/Rdistance/v3.0.0/master?color=f9930d)
![](https://img.shields.io/github/contributors/tmcd82070/Rdistance?color=656d44)
![](https://img.shields.io/github/last-commit/tmcd82070/Rdistance?color=8e755e)
![](https://img.shields.io/github/release-date/tmcd82070/Rdistance?color=c95443)

</center> 

<!-- [![Travis-CI Build Status](https://travis-ci.org/tmcd82070/Rdistance.svg?branch=master)](https://travis-ci.org/tmcd82070/Rdistance) -->
<!-- badges: end -->

# Simplified Distance-Sampling in R

**Rdistance** analyzes line- and point-transect distance-sampling data. 
If you are unfamiliar with 
distance-sampling, check out our primer, [Distance Sampling 
for the Average Joe](https://github.com/tmcd82070/Rdistance/wiki/Distance-Sampling-for-the-Average-Joe). 
For those ready to take on 
an analysis, the best place to start is one of our vignettes or in the **Examples** section (below).

**Vignettes**:

* [Beginner Line Transects](https://cran.r-project.org/web/packages/Rdistance/vignettes/Rdistance_BeginnerLineTransect.pdf)
* [Extended Beginner Line Transects Examples](https://cran.r-project.org/web/packages/Rdistance/vignettes/Extended_dfuncEstim_Examples.pdf)

```{r}
includeFigure("RdistanceSeparator.PNG")
```

## Features

* Line-transect and point-transects 
* Likelihood functions: 
  + half-normal (`halfnorm`) 
  + hazard rate (`hazrate`) 
  + negative exponential (`negexp`)
  + Gamma (`Gamma`)
  + logistic (`logistic`)
* Non-parametric smoothed distance functions (`smu`)
* Built-in key functions: `sine`, `cosine`, and `hermite`
* Expansion terms
* Standard methods: `print`, `plot`, `predict`, `AIC`, etc.
* Observation and transect-level distance function covariates
* Standard R formula model specification (e.g., `distance ~ elevation + observer`)
* Measurement unit control and automatic conversion
* Automated bootstrap confidence intervals 
* Overall (study area) abundance estimates
* Custom (user-defined) detection functions
* Help and vignettes reviewed and edited by multiple authors

    
```{r}
includeFigure("RdistanceSeparator.PNG")
```


## Current Release
The current release is [here](https://github.com/tmcd82070/Rdistance/releases).


## Installation

Install the development version from [GitHub](https://github.com/) with:
``` r
if( !require("devtools") ){
  install.packages("devtools")
}
devtools::install_github("tmcd82070/Rdistance")
```

Install the stable version directly from CRAN:

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


```{r}
includeFigure("RdistanceSeparator.PNG")
```

## Examples 


These examples show basic estimation of abundance via distance-sampling analyses, both with and without covariates. 
Additional information can be found on our [wiki](https://github.com/tmcd82070/Rdistance/wiki) and in 
our vignettes.

### Line Transects - No Covariates

```{r sparrowData, echo=TRUE}
if( !require("units") ){
  install.packages("units")
}
library(Rdistance)
library(units)

# Example data
data("sparrowDetectionData")  # access example data
data("sparrowSiteData")
head(sparrowDetectionData)  # inspect data
head(sparrowSiteData)
```

```{r lineHazrateExample, echo=TRUE}
# Set upper (right) truncation distance
whi <- set_units(150, "m")
# Fit hazard rate likelihood
dfuncFit <- dfuncEstim(dist ~ 1
                   , detectionData = sparrowDetectionData
                   , likelihood = "hazrate"
                   , w.hi = whi)
dfuncFit <- abundEstim(dfuncFit
         , detectionData = sparrowDetectionData
         , siteData = sparrowSiteData
         , area = set_units(2500, "hectares"))
summary(dfuncFit)
plot(dfuncFit)
```


### Line Transects - With Vegetation Covariate

```{r lineHazrateExampleCovars, echo=TRUE}
dfuncFit <- dfuncEstim(dist ~ bare
                   , detectionData = sparrowDetectionData
                   , siteData = sparrowSiteData
                   , likelihood = "hazrate"
                   , w.hi = whi)
dfuncFit <- abundEstim(dfuncFit
         , detectionData = sparrowDetectionData
         , siteData = sparrowSiteData
         , area = set_units(2500, "hectares")
         , ci=NULL)
summary(dfuncFit)
plot(dfuncFit, newdata = data.frame(bare = c(30, 40, 50)), lty = 1)
```

### Point Transects - No Covariates

```{r thrasherData, echo=TRUE}
# Example data
data("thrasherDetectionData")  # access example data
data("thrasherSiteData")
head(thrasherDetectionData)  # inspect example data
head(thrasherSiteData)
```

```{r pointHazrateExample, echo=TRUE}
dfuncFit <- dfuncEstim(dist ~ 1
                   , detectionData = thrasherDetectionData
                   , likelihood = "hazrate"
                   , pointSurvey = TRUE)
dfuncFit <- abundEstim(dfuncFit
         , detectionData = thrasherDetectionData
         , siteData = thrasherSiteData
         , area = set_units(100, "acres"), ci=NULL)
summary(dfuncFit)
plot(dfuncFit)
```

### Point Transects - With Vegetation Covariates

```{r pointHazrateExampleCovars, echo=TRUE}
dfuncFit <- dfuncEstim(dist ~ bare + shrub
                   , detectionData = thrasherDetectionData
                   , siteData = thrasherSiteData
                   , likelihood = "hazrate"
                   , pointSurvey = TRUE)
dfuncFit <- abundEstim(dfuncFit
         , detectionData = thrasherDetectionData
         , siteData = thrasherSiteData
         , area = set_units(100, "acres"), ci=NULL)
summary(dfuncFit)
plot(dfuncFit, newdata = data.frame(bare = c(30, 35, 40)
                                  , shrub = 20), lty = 1)
```

<!-- github CI examples for auto rendering of Rmd <https://github.com/r-lib/actions/tree/v1/examples>. -->

```{r}
includeFigure("RdistanceSeparator.PNG")
```


# RECENT CHANGES

See our [NEWS](NEWS.md) file for recent changes.