README.Rmd

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

<!--[![Build Status](https://scientiafelis/sebmsr.svg?branch=master)](https://scientiafelis/sebmsr)-->  

<!-- README.md is generated from README.Rmd. Please edit that file -->

![](https://img.shields.io/github/r-package/v/scientiafelis/sebmsr?style=plastic&logo=R&logoColor=%23276DC3&logoSize=auto&label=sebmsR&labelColor=green) ![](https://img.shields.io/github/issues/scientiafelis/sebmsr?style=plastic&logo=github)
![](https://img.shields.io/github/license/scientiafelis/sebmsr?style=plastic&label=License&labelColor=blue)

<!--![](https://img.shields.io/github/commits-since/scientiafelis/sebmsr/latest?style=plastic&sort=date&logo=git&logoColor=%F05032) -->
![](https://img.shields.io/github/repo-size/scientiafelis/sebmsr?style=plastic&logo=github)


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

```{r include=FALSE}
knitr::opts_chunk$set(warning=FALSE, comment=NA)
```

`sebmsR` is an R package for SeBMS - the Swedish Butterfly Monitoring Scheme - offering tools for accessing data, making plots and a Shiny app.

## Under construction

The package is currently under re-development and a few functions do not work well, e.g. the Shiny app.
The functions related to weather data, as well as the functions that create species abundance plots and the trim functions and their plot as well as the distributions maps work well and produce pngs ready to use in reports.


## Installing from github

If you want to install the latest version:

```{r message=FALSE, warning=FALSE, results="hide", eval=FALSE}
# First make sure you have the devtools package
# which simplifies installations from github
# Note: Windows users have to first install Rtools to use devtools

install.packages("devtools") 
library(devtools)
install_github("scientiafelis/sebmsr")

# A specific versioned release can be installed like this:
install_github("scientiafelis/sebmsr@1.5.0")

```

## Dependencies

This package depends on a number of packages some of which is not found on CRAN.
For instance BRCindicators have to be installed from GitHub.

```{r message=FALSE, warning=FALSE, results="hide", eval=FALSE}

library(devtools)
install_github(repo = 'biologicalrecordscentre/BRCindicators')

```

#### List of all packages

- BRCindicators,
- config,
- DBI,
- plyr,
- dplyr,
- forcats,
- geonames,
- ggnewscale,
- ggplot2 (>= 3.4.0),
- glue,
- httr,
- jsonlite,
- leaflet,
- lubridate,
- mapview,
- polite,
- pool,
- purrr,
- rappdirs,
- readr,
- RPostgres,
- rstudioapi,
- rtrim,
- scales,
- sf,
- stringr,
- terra,
- tibble,
- tidyr,
- webshot2
    
**Suggested packages** 
    
- cowplot,
- DT,
- ggthemes,
- grid,
- knitr,
- magick,
- raster,
- rasterVis,
- RColorBrewer,
- rmarkdown,
- shiny,
- shinydashboard,
- shinyjs,
- sp,
- testthat

## Quick start

Since the package can read data from a Postgres db with live data from SeBMS, some initial system configuration may first be needed, to set up the connection.

### Secure shell connection to the database server

If the database connection requires an ssh tunnel to be established.
If you are using a **nix** system (Linux, mac etc), this configuration can be achieved by editing `~/.ssh/config`, adding a section such as:

```bash
Host sebms
    User my_ssh_user
    HostName my_server_ip_for_the_postgres_db_server
    LocalForward 5432 127.0.0.1:5432
    ServerAliveInterval 30

```
After this, the tunnel can be established with the command `ssh -N sebms`. Upon success, the database can then be reached locally at the postgres db standard port.

Similar results can be achieved using `putty` on **Windows** platforms.

### Config for db connection

Once the database server is available, the R package needs to be configured to use the database connection. To achieve this, load the package in your R environment and create a `config.yml` with the db connection details.
You can also use a `.Renviron` file, that export the data base details to the environment and let the `config.yml` references these variables in R:

```{r message=FALSE, warning=FALSE, eval=FALSE}

library(sebmsR)
library(rappdirs)

# this is the location for config.yml holding db connection details
app_dir("sebms")$config() 
# the location may vary depending on OS
# on a Linux OS a valid path for the file is $HOME/.config/sebms/config.yml
# on a Windows 8 OS a valid path for the file is C:\Users\IEUser\AppData\Local\sebms\sebms\config.yml

# this is the location for .Renviron
Sys.getenv("R_USER")
# on a Linux OS a valid path for the .Renviron file is $HOME ie ~/.Renviron
# on a Windows 8 OS a valid path for the .Renviron file is C:\Users\IEUser\.Renviron
# on a Windows 10 OS a valid path for the .Renviron file is C:\Users\IEUser\Documents\.Renviron

```

Example content that can be used in the `config.yml`:

```bash
default:
  sebms:
    driver: !expr RPostgres::Postgres() 
    server: 'localhost'
    uid: 'my_db_username'
    pwd: 'my_db_password'
    port: 5432
    database: 'test77'
```
If you prefer to use environment variables for the credentials and reference those in the `config.yml`, the file can look like this:

```{r message=FALSE, warning=FALSE, echo=FALSE}

# example content in config.yml
content <- readLines(system.file("extdata", "config.yml", 
  package = "sebmsR"))

cat(paste(content, collapse = "\n"))
```

For the above connection to be initiated, you also need to set up your `.Renviron` with the environment variables containing the credentials.
For that run the function `editcred(homepath = 'user home dir')`:

```console
DBUSER = my_db_username
DBPASS = my_db_password
DBNAME = PostgreSQL_database_name
DBPORT = PostgreSQL_database_port_number

```

## Usage

After getting connected to the database, look at usage examples to get you started. 

To get a list of functions and what they do, use `?sebmsR`

### Species Figures

To make a plot and generate the **pngs for the weather data and sunhour** figures for the Butterfly yearly report of **2022** use:

- **`sebms_weather_png(2022)`** creates png files with the precipitation, temperaure figures.
- **`sebms_sunhour_plot(2022)`** creates the sun hour figure
- **`sebms_sundiff_plot(2022)`** shows differences in sun hours between the given year and a 5-year mean.

To make figures with **butterfly data** use:

- **`sebms_abundance_per_species_plot(2022)`** to make bar plots with individual numbers for each species, divided on two png figures.
- **`sebms_abundance_year_compare_plot(2021:2022)`** to make bar plots comparing individuals per week compared between two years.
- **`sebms_species_abundance_plot(2021, Art = 118)`** to make bar plots for individual species with numbers per week.
- **`sebms_species_per_sitetype_plot(2022)`** to make bar plots to show how many species sites have and the number distribution of these, compared between site type. Also the mean number of species per site type.


### Trim index

To get the figures for **species index and indicator index** run:


- **`get_trimPlot()`** to get indices for each given species during the time period given.
- **`get_indicatorPlots()`** to get indicator indices for the default groups *20 most common*, *Frassland*, *Forest*, and *Agricultural* species. Alsu during the time period given.
- **`get_trimComparedPlots()`** creats a figure that compares the Sweden index of a species with the index for a set *Län*, *Landskap*, or *Kommun*.
- **`get_trendHistogram()`** creates a figure of percent change in species abundances as a histogram with five change categories.


### Maps

You can make different types of maps for species distributions

- **`sebms_sites_map()`** creates map for all visited sites on Swedish grid separating transects and point data.
- **`sebms_distribution_map()`** creates a distribution map for species on the Swedish grid.
- **`sebms_regional_site_map()`** creates a map of the County, Region, Province or Municipality with the transect and point data marked.



## Font Issues in Windows

There seems to be a problem on some Windows machines with fonts not being recognized.
There are a number of things you can try to eliminate this.

- Make sure you have the font installed
- Use `extrafont::font_import()` to register all fonts in R.
- Use the `extrafont::loadfonts(device = "all", quiet = TRUE)` to load registered font in R
- If you work in RStudio: Install the `ragg` package and set the Graphic device backend to **'AGG'**; `Tools > Global options > General > Graphics > Backend: AGG`

## Development

To further develop or change the package, please refer to instructions at <http://r-pkgs.had.co.nz/>, then fork this repo and submit a PR with the changes. 

**For a concrete example:** To make a change with regards to how the filtering on species and year dimensions works for the species data.
*First* edit the 'R/SQLqueries.R' file, for example by adjusting the query used in the `sebms_species_per_year_filtered()` function, and possibly adding a test in `test/testthat/test-sebms-various.R` that verifies expected results.
*Then* do the `Ctrl+Shift+{D,T,E}` steps.
*Then* use git to commit and push the changes.

To change functions that retrieve data from the database, please make changes primarily in the `R/SQLqueries.R` file.
Functions related to weather figures are found in `R/weatherplots.R` and `R/soltimmar.R`
Plotting species uses functions in `R/speciesplots.R`.
The trim functions are found in `R/trimfunctions.R`.
The distribution maps are found in `R/distribution_maps.R`

Vignettes need to be updated and developed. These are located in `vignettes/sebms-intro.Rmd`.

## Credits

The package is based on code and data assembled and curated by Lars Pettersson at http://dagfjarilar.lu.se

## Meta

* Please [report any issues or bugs](https://github.com/ScientiaFelis/sebmsR/issues).
* License: AGPL