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

# sit - Analyse mark-release-recapture data from [Sterile Insect Technique (SIT)](https://www.youtube.com/watch?v=yV7WLrlzbLk&t=2s) field experiments <img src="man/figures/logo.png" align="right" height="132" />

<!-- badges: start -->
[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/sit)](https://cran.r-project.org/package=sit)
[![:name status badge](https://cirad-astre.r-universe.dev/badges/:name)](https://cirad-astre.r-universe.dev)
[![sit status badge](https://cirad-astre.r-universe.dev/badges/sit)](https://cirad-astre.r-universe.dev)
[![Build status](https://forgemia.inra.fr/umr-astre/sit/badges/main/pipeline.svg)](https://forgemia.inra.fr/umr-astre/sit/pipelines)
 [![coverage report](https://forgemia.inra.fr/umr-astre/sit/badges/main/coverage.svg)](https://umr-astre.pages.mia.inra.fr/sit/coverage.html)
<!-- [![Appveyor Build status](https://ci.appveyor.com/api/projects/status/5p751lpceeiy18kp?svg=true)](https://ci.appveyor.com/project/famuvie/mapmcda) -->
<!-- badges: end -->


## Overview

`sit` is currently on active development, after a thorough [analysis of requirements](https://umr-astre.pages.mia.inra.fr/sit-design/requirements.html#content).

Import data about _traps_, _release events_ and _field surveys_ into a `sit`
object.
Then, query the `sit` object for estimates of _competitiveness_, _dispersal_ and _survival_.


## Example

We use some fake data for demonstration purposes. See `?fake_sit`.

1. __Trap data__: set up a `sf` table of points with trap coordinates (see, [`st_as_sf()`](https://r-spatial.github.io/sf/reference/st_as_sf.html), for instance), identification code, type (see `sit_trap_types()`) and area (`sit`/`control`). Use `sit_traps()` to _import_ into a `sit_traps` object.
    
    ```{r fake-traps}
    fake_traps
    ```
    
    ```{r my-traps}
    my_traps <- sit_traps(fake_traps)
    ```

2. __Release events__: releases can be performed from a single _point_ or homogeneously over the sit area. Set up a table with release dates, colour and number of individuals. For __point releases__ include release coordinates and make it a `sf` object. Lacking geographical coordinates, `sit` will interpret it as a __areal release__.

    ```{r fake-rpoints}
    fake_rpoints
    ```
    
    ```{r fake-rareal}
    fake_rareal
    ```
    
    Use `sit_revents()` to _import_ into `sit_revents` objects and combine different release types into a single `sit_revents` object with `c()`.
    
    ```{r my-releases}
    my_releases <- c(
      sit_revents(fake_rpoints),
      sit_revents(fake_rareal)
    )
    ```
    

3. __Field survey data__: field data are collected at `adult` or `egg` _stages_ of development, depending on the trap type (see `sit_trap_types()`)

    Field data from __adult__ surveys can be imported using `sit_adult_surveys()` from a table such as:

    ```{r fake-adults}
    fake_adults
    ```


    ```{r my-asurveys}
    my_asurveys <- sit_adult_surveys(fake_adults)
    ```

    Field data from __egg__ surveys, include other information such as the _hatching rate_:
    
    ```{r fake-eggs}
    fake_eggs
    ```
    
    
    ```{r my-eggsurveys}
    my_eggsurveys <- sit_egg_surveys(fake_eggs)
    ```
        
4. __Combine__ all the information into a `sit` object using `sit()`:

    ```{r my-sit}
    my_sit <- sit(
      traps          = my_traps,
      release_events = my_releases,
      adult_surveys  = my_asurveys,
      egg_surveys    = my_eggsurveys
    )
    ```

5. __Query__ your `sit` object for estimates of _competitiveness_, _dispersal_
and _survival_.

    ```{r queries}
    sit_sterile_male_competitiveness(my_sit)
    sit_mdt(my_sit, spatial_adjustement = FALSE)
    ```

    ```{r eval = FALSE}
    ## Not yet implemented
    sit_flight_range(my_sit)
    sit_diffusion(my_sit)
    sit_survival(my_sit)
    ```


## Installation

<!-- You can install the released version of sit from [CRAN](https://CRAN.R-project.org) with: -->

<!-- ``` r -->
<!-- install.packages("sit") -->
<!-- ``` -->

```{r install-r-universe, eval = FALSE}
options(repos = c(
  ciradastre = 'https://cirad-astre.r-universe.dev',
  CRAN = 'https://cloud.r-project.org'))

install.packages("sit")
```

This installs binary packages for Windows and MacOS, unless you configured R to install source packages. In such case, see below.

### Linux and source installation

`sit` uses the geospatial libraries GDAL, GEOS and Proj.4, via the R-package [`sf`](https://r-spatial.github.io/sf/).

Dependencies for recent versions of Ubuntu (18.04 and later) are available in the official repositories; you can install them with:
```{bash deps-ubuntu, eval = FALSE}
apt-get -y update && apt-get install -y  libudunits2-dev libgdal-dev libgeos-dev libproj-dev
```

For Fedora, Arch or source installation in Windows or Mac, please refer to the [installation instructions for `sf`](https://r-spatial.github.io/sf/#installing).



## Getting help online

Bug reports and feature requests should be posted on *GitLab* using
the [*issue*](http://forgemia.inra.fr/umr-astre/sit/issues) system.

For support, reach out in the 
[sit mailing list](https://listes.cirad.fr/sympa/info/sit).
Archives are of public access.

Contributions are welcome via **pull requests**.

Please note that this project is released with a [Contributor Code of
Conduct](CONDUCT.md). By participating in this project you agree to
abide by its terms.