---
title: "create and read VPTS"
author: Birgen Haest, Baptiste Schmid
output: rmarkdown::html_vignette
description: > 
  Test functionality and interoperability for createVPTS
vignette: >
  %\VignetteIndexEntry{Guide to create VPTS csv output files in line with the ALOFT data standard, described [here](https://aloftdata.eu/vpts-csv/)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
``` {r, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```
```{r setup, include=FALSE}
hasBioRad <- requireNamespace("bioRad", quietly = TRUE)
```
***
# Summary

This vignette provides an example of the basic workflow for createVPTS:

1.    Create a VPTS using the BirdScan MR1 example data and create a CSV file,

2.    Read and convert the CSV file to VPTS,

3.    Visualise the time series.

***
# Before we get started
```{r, eval = hasBioRad}
library(birdscanR)
library(bioRad)
outDir <- tempdir()
```

Read Test BirdScanMR1 data

The package ships with a sample data extract from a Birdscan MR1 radar
(Sempach, Switzerland), already in the format returned by `extractDbData()`.
We load it directly from the package's `extdata` folder.
```{r}
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"
))
```

***
# Step 1: Create VPTS from the BirdScan MR1 example dataset

VPTS CSV files, in line with the [ALOFT data standard](https://aloftdata.eu/vpts-csv/),
can be generated directly from the echo data with `createVPTS()`. Note that
this function only works on Birdscan MR1 database versions >= 1.7.0.4, as the
variable `feature37.speed` is required for the density calculation.

```{r}
dbName = "CH_Sempach_2024_SEP24_25"
mainOutputDir = file.path(outDir)
targetTimeZone = "Etc/GMT0"
timeRangeData = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# =============================================================================
cManualBlindTimes = NULL

# Create vpts files
# =============================================================================
vptsDir = createVPTS(
  dbName = dbName,
  outputDir = mainOutputDir,
  echoes = dbData$echoData,
  altitudeRange = c(25, 1025),
  altitudeBinSize = 50,
  timeRange = timeRangeData,
  timeBinDuration_sec = 1800,
  timeZone = targetTimeZone,
  protocolData = dbData$protocolData,
  visibilityData = dbData$visibilityData,
  siteData = dbData$siteData,
  sunriseSunset = dbData$sunriseSunset,
  manualBlindTimes = cManualBlindTimes,
  saveBlindTimes = FALSE,
  blindTimesOutputDir = mainOutputDir,
  blindTimeAsMtrZero = NULL,
  propObsTimeCutoff = 0.2
)
```


***
# Step 2: Read the CSV-file and convert to VPTS with BioRad::as.vpts()

```{r, eval = hasBioRad}
vpts = read.csv(file.path(vptsDir, "200_vpts_20240924.csv"))
vpts = as.vpts(vpts) 
```

***
# Step 3: Visualise

Visualise
```{r, eval = hasBioRad}
png(file.path(outDir, "plot.png"))
plot(vpts)
dev.off()
```