README.Rmd

---
title: "xyzt"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

Mediate covariate extraction using tabular location data. This package will make the transform from tabular data to standardized [sf](https://CRAN.R-project.org/package=sf) objects easier.  We use [sf](https://CRAN.R-project.org/package=sf) objects to harmonize subsequent data extractions.

![xyzt](inst/images/xyzt.png)

The extraction step is not defined in this package, although we provide a uniform interface for selection of an external application to run the extraction.  For example, suppose you have an application that accepts an `sf POINT` object and returns a table of 'sst' from 'MUR' using your own `murtools` package.  That packe must have a function that accepts any [sf](https://CRAN.R-project.org/package=sf) object (POINT, POLYGON) and will return a table of covariates append-able to you own data set.

### The extraction

What defines an extraction?

  - accepts `sf` object(s)
     + points
     + polygons
     + bounding boxes
  - returns data frame (`tibble`?) or `stars`
  - manages missing data how?

### Promoting efficiency

 - What is the granularity of the data source?  Daily? Regional?
 - Group by date/time (T) - (xyzt? extractor? user-script?)
 - Group by measure (Z)?

### How to identify an xyzt-ready extractor?

 - Simply state in the README?
 - Register with xyzt which maintains a list?



### Pseudo-example
```
dataset <- [some table of data with location and time]
x <-  dataset |>
  as_POINT() 
  
covars <- x |>
  extract(package = "murtools", var = c("analysed_sst", "mask"))
  
combined_result <- dplyr::bind_cols(dataset, covars)
```

### Requirements

+ [R v4.1+](https://www.r-project.org/)
+ [rlang](https://CRAN.R-project.org/package=rlang)
+ [assertthat](https://CRAN.R-project.org/package=httr)
+ [dplyr](https://CRAN.R-project.org/package=httr)
+ [sf](https://CRAN.R-project.org/package=sf)
+ [readr](https://CRAN.R-project.org/package=readr)

### Installation

```
remotes::install_github("BigelowLab/xyzt")
```

## Usage

All transactions hinge around tables (data frames) of data or [sf](https://CRAN.R-project.org/package=sf) objects. If a table (we suggest [tibble](https://CRAN.R-project.org/package=tibble)) then minimal metadata is required to establish a coordinate reference system.

### Input tables

We provide an example data set of points from the Gulf of Maine.

```{r}
suppressPackageStartupMessages({
  library(dplyr)
  library(xyzt)
  library(sf)
})
(x <- read_gom())
```

And a second set from the South Atlantic Bight. But perhaps you need the longitudes shifted to range [0,360] rather than [-180, 180].

```{r}
sab <- read_sab()
cat("lon range before:", paste(range(sab$lon), collapse = ", "), "\n")
sab$lon <- xyzt::to_360(sab$lon)
cat("lon range after:", paste(range(sab$lon), collapse = ", "), "\n")
```


### Convert to [sf](https://CRAN.R-project.org/package=sf)

Here we show conversion to 2d ('xy'), 3d ('xyz' or 'xyt') or 4d ('xyzt') type spatial POINT objects.  Note that time coordinates are shown as numeric (number of seconds since 1970-01-01 epoch).

```{r}
(xy <- as_POINT(x, crs = 4326, dims = "xy"))
(xyz <- as_POINT(x, crs = 4326, dims = "xyz"))
(xyt <- as_POINT(x, crs = 4326, dims = "xyt"))
(xyzt <- as_POINT(x, crs = 4326, dims = "xyzt"))
```