-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathREADME.Rmd
170 lines (127 loc) · 8.47 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
---
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(tibble)
```
# rsi <a href="https://permian-global-research.github.io/rsi/"><img src="man/figures/logo.png" align="right" height="138" alt="rsi website" /></a>
<!-- badges: start -->
[](https://github.com/Permian-Global-Research/rsi/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/Permian-Global-Research/rsi?branch=main)
[](https://opensource.org/license/apache-2-0)
[](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[](https://www.repostatus.org/#active)
[](https://CRAN.R-project.org/package=rsi)
[](https://zenodo.org/doi/10.5281/zenodo.10926857)
[](https://github.com/ropensci/software-review/issues/636)
<!-- badges: end -->
The goal of rsi is to address several **r**epeated **s**patial **i**nfelicities, by providing utility functions that save you typing and help avoid **r**epetitive **s**tress **i**njuries. Specifically, rsi provides:
+ An interface to the **R**some -- excuse me, [_Awesome_ Spectral Indices project](https://github.com/awesome-spectral-indices/awesome-spectral-indices), providing the list of indices directly in R as a friendly tibble,
+ A method for efficiently _calculating_ those awesome spectral indices using local rasters, enabling **r**apid **s**pectral **i**nference,
+ A method for downloading STAC data -- excuse me, **r**etriving **S**TAC **i**nformation -- from any STAC server, with additional helpers for downloading Landsat, Sentinel-1, and Sentinel-2 data from free and public STAC servers providing **r**apid **s**atellite **i**magery,
+ A **r**aster **s**tack **i**ntegration method for combining multiple rasters containing distinct data sets into a single raster stack.
The functions in rsi are designed around letting you use the tools you're familiar with to process raster data using compute that you control -- whether that means grabbing imagery with your laptop to add some context to a map, or grabbing tranches of data to a virtual server hosted near your data provider for lightning fast downloads. The outputs from rsi functions are standard objects -- usually the file paths of raster files saved to your hard drive -- meaning it's easy to incorporate rsi into broader spatial data processing workflows.
## Installation
You can install rsi via:
``` r
install.packages("rsi")
```
You can install the development version of rsi from [GitHub](https://github.com/Permian-Global-Research/rsi) using [pak](https://pak.r-lib.org/):
``` r
# install.packages("pak")
pak::pak("Permian-Global-Research/rsi")
```
## Example
The `spectral_indices()` function provides a tibble with data from the [Awesome Spectral Indices project](https://github.com/awesome-spectral-indices/awesome-spectral-indices):
```{r}
library(rsi)
spectral_indices()
```
The first time `spectral_indices()` is called it will download the most up-to-date version of the spectral indices JSON file, and then write the resulting table to a cache file in `tools::R_user_dir("rsi")`. After that, `spectral_indices()` will only download a new file if the cache is older than 1 day, or if the `update_cache` argument is `TRUE`, in order to provide the most up-to-date data as quickly as possible. If offline, `spectral_indices()` will always fall back to the cache or, if no cache file exists, a (possibly out-of-date) data file included in rsi itself.
Separately, the `get_stac_data()` function provides a generic interface for downloading composite images from any accessible STAC catalog. For instance, we could download a cloud-masked composite of Landsat's visible layers using `get_stac_data()` and a few helper functions from rsi:
```{r}
aoi <- sf::st_point(c(-74.912131, 44.080410))
aoi <- sf::st_set_crs(sf::st_sfc(aoi), 4326)
aoi <- sf::st_buffer(sf::st_transform(aoi, 5070), 1000)
landsat_image <- get_stac_data(
aoi,
start_date = "2022-06-01",
end_date = "2022-06-30",
pixel_x_size = 30,
pixel_y_size = 30,
asset_names = c("red", "blue", "green"),
stac_source = "https://planetarycomputer.microsoft.com/api/stac/v1/",
collection = "landsat-c2-l2",
mask_band = "qa_pixel",
mask_function = landsat_mask_function,
output_filename = tempfile(fileext = ".tif"),
item_filter_function = landsat_platform_filter,
platforms = c("landsat-9", "landsat-8")
)
terra::plot(terra::rast(landsat_image))
```
For common data sets, rsi also provides helper functions which
provide most of these arguments for you. For instance, that `get_stac_data()`
call could be as simple as:
```{r}
landsat_image <- get_landsat_imagery(
aoi,
start_date = "2022-06-01",
end_date = "2022-08-30",
output_filename = tempfile(fileext = ".tif")
)
terra::plot(terra::rast(landsat_image))
```
Note that we've been plotting each band individually so far by calling `terra::plot()`. We could also use `terra::plotRGB()` (after `terra::stretch()`ing the band values) to see what this mosaic of images would look like to the human eye:
```{r}
landsat_image |>
terra::rast(lyrs = c("R", "G", "B")) |>
terra::stretch() |>
terra::plotRGB()
```
By default, these functions download data from Microsoft's Planetary Computer
API, using a number of configuration options set in `rsi_band_mapping` objects
provided by the package. You can see these default configuration options by
printing the band mapping objects, and can adjust them through arguments
to any `get_*` function in the package.
```{r}
landsat_band_mapping$planetary_computer_v1
```
We can put these pieces together and calculate as many spectral indices as we can based on our downloaded Landsat imagery. The `calculate_indices()` function, well, calculates indices, using subsets of our `spectral_indices()` data frame:
```{r}
available_indices <- filter_bands(
bands = names(terra::rast(landsat_image))
)
indices <- calculate_indices(
landsat_image,
available_indices,
output_filename = tempfile(fileext = ".tif")
)
# Plot the first handful of spatial indices
terra::plot(terra::rast(indices))
```
And last but not least, rsi includes a utility for efficiently combining rasters containing different data about the same location into a [VRT](https://gdal.org/en/latest/drivers/raster/vrt.html), which allows programs like GDAL to treat these separate data sources as a single file. For instance, we can combine our Landsat imagery with the derived indices:
```{r}
raster_stack <- stack_rasters(
c(landsat_image, indices),
tempfile(fileext = ".vrt")
)
# The first few panels are now Landsat measurements, not indices:
terra::plot(terra::rast(raster_stack))
```
This can be extremely useful as a way to create predictor bricks and other multi-band rasters from various data sources.
## Contributing
We love contributions! See our [contribution guide](https://github.com/Permian-Global-Research/rsi/blob/main/.github/CONTRIBUTING.md) for pointers on how to make your contribution as easy to accept as possible -- in particular, consider [opening an issue](https://github.com/Permian-Global-Research/rsi/issues/new/choose) with a [minimal reprex](https://www.tidyverse.org/help/#reprex) to make sure that we understand what your changes are meant to do.
## License
Copyright 2023 Permian Global Research, Limited.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at:
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.