rsi

Code for Retriving STAC Information, addressing Repeated Spatial Infelicities and interfacing with Rsome Spectral Indices.
https://github.com/permian-global-research/rsi

Category: Natural Resources
Sub Category: Soil and Land

Last synced: about 8 hours ago
JSON representation

Repository metadata

Code for Retrieving STAC Information, addressing Repeated Spatial Infelicities and interfacing with Rsome Spectral Indices

• Host: GitHub
• URL: https://github.com/permian-global-research/rsi
• Owner: Permian-Global-Research
• License: apache-2.0
• Created: 2023-08-23T18:32:58.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-03-27T22:14:00.000Z (about 1 month ago)
• Last Synced: 2025-03-29T22:31:46.698Z (29 days ago)
• Language: R
• Homepage: https://permian-global-research.github.io/rsi/
• Size: 37.3 MB
• Stars: 49
• Watchers: 3
• Forks: 7
• Open Issues: 5
• Releases: 9
• Metadata Files:
  • Readme: README.Rmd
  • Changelog: NEWS.md
  • Contributing: .github/CONTRIBUTING.md
  • License: LICENSE.md
  • Citation: CITATION.cff
  • Support: .github/SUPPORT.md
  • Codemeta: codemeta.json

README.Rmd

          ---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(tibble)
```

# rsi 


[![R-CMD-check](https://github.com/Permian-Global-Research/rsi/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/Permian-Global-Research/rsi/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/Permian-Global-Research/rsi/branch/main/graph/badge.svg)](https://app.codecov.io/gh/Permian-Global-Research/rsi?branch=main)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/license/apache-2-0)
[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![CRAN status](https://www.r-pkg.org/badges/version/rsi)](https://CRAN.R-project.org/package=rsi)
[![DOI](https://zenodo.org/badge/682237263.svg)](https://zenodo.org/doi/10.5281/zenodo.10926857)
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/636_status.svg)](https://github.com/ropensci/software-review/issues/636)


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.

        

Citation (CITATION.cff)

# -----------------------------------------------------------
# CITATION file created with {cffr} R package, v0.5.0
# See also: https://docs.ropensci.org/cffr/
# -----------------------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "rsi" in publications use:'
type: software
license: Apache-2.0
title: 'rsi: Efficiently Retrieve and Process Satellite Imagery'
version: 0.2.0.9000
doi: 10.5281/zenodo.10926857
abstract: Downloads spatial data from spatiotemporal asset catalogs ('STAC'), computes
  standard spectral indices from the Awesome Spectral Indices project (Montero et
  al. (2023) <doi:10.1038/s41597-023-02096-0>) against raster data, and glues the
  outputs together into predictor bricks. Methods focus on interoperability with the
  broader spatial ecosystem; function arguments and outputs use classes from 'sf'
  and 'terra', and data downloading functions support complex 'CQL2' queries using
  'rstac'.
authors:
- family-names: Mahoney
  given-names: Michael
  email: [email protected]
  orcid: https://orcid.org/0000-0003-2402-304X
preferred-citation:
  type: generic
  title: 'rsi: Efficiently Retrieve and Process Satellite Imagery'
  authors:
  - family-names: Mahoney
    given-names: Michael
    email: [email protected]
    orcid: https://orcid.org/0000-0003-2402-304X
  url: https://permian-global-research.github.io/rsi/
  doi: 10.5281/zenodo.10926857
  version: 0.2.0.9000
repository: https://CRAN.R-project.org/package=rsi
repository-code: https://github.com/Permian-Global-Research/rsi
url: https://permian-global-research.github.io/rsi/
contact:
- family-names: Mahoney
  given-names: Michael
  email: [email protected]
  orcid: https://orcid.org/0000-0003-2402-304X
references:
- type: software
  title: 'R: A Language and Environment for Statistical Computing'
  notes: Depends
  url: https://www.R-project.org/
  authors:
  - name: R Core Team
  location:
    name: Vienna, Austria
  year: '2024'
  institution:
    name: R Foundation for Statistical Computing
  version: '>= 4.0'
- type: software
  title: future.apply
  abstract: 'future.apply: Apply Function to Elements in Parallel using Futures'
  notes: Imports
  url: https://future.apply.futureverse.org
  repository: https://CRAN.R-project.org/package=future.apply
  authors:
  - family-names: Bengtsson
    given-names: Henrik
    email: [email protected]
    orcid: https://orcid.org/0000-0002-7579-5165
  year: '2024'
- type: software
  title: glue
  abstract: 'glue: Interpreted String Literals'
  notes: Imports
  url: https://glue.tidyverse.org/
  repository: https://CRAN.R-project.org/package=glue
  authors:
  - family-names: Hester
    given-names: Jim
    orcid: https://orcid.org/0000-0002-2739-7082
  - family-names: Bryan
    given-names: Jennifer
    email: [email protected]
    orcid: https://orcid.org/0000-0002-6983-2759
  year: '2024'
- type: software
  title: httr
  abstract: 'httr: Tools for Working with URLs and HTTP'
  notes: Imports
  url: https://httr.r-lib.org/
  repository: https://CRAN.R-project.org/package=httr
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  year: '2024'
- type: software
  title: jsonlite
  abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
  notes: Imports
  url: https://jeroen.r-universe.dev/jsonlite
  repository: https://CRAN.R-project.org/package=jsonlite
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: [email protected]
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2024'
- type: software
  title: lifecycle
  abstract: 'lifecycle: Manage the Life Cycle of your Package Functions'
  notes: Imports
  url: https://lifecycle.r-lib.org/
  repository: https://CRAN.R-project.org/package=lifecycle
  authors:
  - family-names: Henry
    given-names: Lionel
    email: [email protected]
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
    orcid: https://orcid.org/0000-0003-4757-117X
  year: '2024'
- type: software
  title: proceduralnames
  abstract: 'proceduralnames: Several Methods for Procedural Name Generation'
  notes: Imports
  url: https://mikemahoney218.github.io/proceduralnames/
  repository: https://CRAN.R-project.org/package=proceduralnames
  authors:
  - family-names: Mahoney
    given-names: Michael
    email: [email protected]
    orcid: https://orcid.org/0000-0003-2402-304X
  year: '2024'
- type: software
  title: rlang
  abstract: 'rlang: Functions for Base Types and Core R and ''Tidyverse'' Features'
  notes: Imports
  url: https://rlang.r-lib.org
  repository: https://CRAN.R-project.org/package=rlang
  authors:
  - family-names: Henry
    given-names: Lionel
    email: [email protected]
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  year: '2024'
- type: software
  title: rstac
  abstract: 'rstac: Client Library for SpatioTemporal Asset Catalog'
  notes: Imports
  url: https://brazil-data-cube.github.io/rstac/
  repository: https://CRAN.R-project.org/package=rstac
  authors:
  - family-names: Simoes
    given-names: Rolf
    email: [email protected]
  - family-names: Carvalho
    given-names: Felipe
    email: [email protected]
  - name: Brazil Data Cube Team
    email: [email protected]
  year: '2024'
- type: software
  title: sf
  abstract: 'sf: Simple Features for R'
  notes: Imports
  url: https://r-spatial.github.io/sf/
  repository: https://CRAN.R-project.org/package=sf
  authors:
  - family-names: Pebesma
    given-names: Edzer
    email: [email protected]
    orcid: https://orcid.org/0000-0001-8049-7069
  year: '2024'
- type: software
  title: terra
  abstract: 'terra: Spatial Data Analysis'
  notes: Imports
  url: https://rspatial.org/
  repository: https://CRAN.R-project.org/package=terra
  authors:
  - family-names: Hijmans
    given-names: Robert J.
    email: [email protected]
    orcid: https://orcid.org/0000-0001-5872-2872
  year: '2024'
- type: software
  title: tibble
  abstract: 'tibble: Simple Data Frames'
  notes: Imports
  url: https://tibble.tidyverse.org/
  repository: https://CRAN.R-project.org/package=tibble
  authors:
  - family-names: Müller
    given-names: Kirill
    email: [email protected]
    orcid: https://orcid.org/0000-0002-1416-3412
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  year: '2024'
- type: software
  title: curl
  abstract: 'curl: A Modern and Flexible Web Client for R'
  notes: Suggests
  url: https://jeroen.r-universe.dev/curl
  repository: https://CRAN.R-project.org/package=curl
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: [email protected]
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2024'
- type: software
  title: knitr
  abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
  notes: Suggests
  url: https://yihui.org/knitr/
  repository: https://CRAN.R-project.org/package=knitr
  authors:
  - family-names: Xie
    given-names: Yihui
    email: [email protected]
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2024'
- type: software
  title: progressr
  abstract: 'progressr: An Inclusive, Unifying API for Progress Updates'
  notes: Suggests
  url: https://progressr.futureverse.org
  repository: https://CRAN.R-project.org/package=progressr
  authors:
  - family-names: Bengtsson
    given-names: Henrik
    email: [email protected]
  year: '2024'
- type: software
  title: rmarkdown
  abstract: 'rmarkdown: Dynamic Documents for R'
  notes: Suggests
  url: https://pkgs.rstudio.com/rmarkdown/
  repository: https://CRAN.R-project.org/package=rmarkdown
  authors:
  - family-names: Allaire
    given-names: JJ
    email: [email protected]
  - family-names: Xie
    given-names: Yihui
    email: [email protected]
    orcid: https://orcid.org/0000-0003-0645-5666
  - family-names: Dervieux
    given-names: Christophe
    email: [email protected]
    orcid: https://orcid.org/0000-0003-4474-2498
  - family-names: McPherson
    given-names: Jonathan
    email: [email protected]
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
    email: [email protected]
  - family-names: Atkins
    given-names: Aron
    email: [email protected]
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  - family-names: Cheng
    given-names: Joe
    email: [email protected]
  - family-names: Chang
    given-names: Winston
    email: [email protected]
  - family-names: Iannone
    given-names: Richard
    email: [email protected]
    orcid: https://orcid.org/0000-0003-3925-190X
  year: '2024'
- type: software
  title: testthat
  abstract: 'testthat: Unit Testing for R'
  notes: Suggests
  url: https://testthat.r-lib.org
  repository: https://CRAN.R-project.org/package=testthat
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  year: '2024'
  version: '>= 3.0.0'
- type: software
  title: withr
  abstract: 'withr: Run Code ''With'' Temporarily Modified Global State'
  notes: Suggests
  url: https://withr.r-lib.org
  repository: https://CRAN.R-project.org/package=withr
  authors:
  - family-names: Hester
    given-names: Jim
  - family-names: Henry
    given-names: Lionel
    email: [email protected]
  - family-names: Müller
    given-names: Kirill
    email: [email protected]
  - family-names: Ushey
    given-names: Kevin
    email: [email protected]
  - family-names: Wickham
    given-names: Hadley
    email: [email protected]
  - family-names: Chang
    given-names: Winston
  year: '2024'

---

Owner metadata

• Name: Permian Global Research
• Login: Permian-Global-Research
• Email:
• Kind: organization
• Description:
• Website: https://permianglobal.com/
• Location:
• Twitter:
• Company:
• Icon url: https://avatars.githubusercontent.com/u/106586419?v=4
• Repositories: 4
• Last ynced at: 2023-08-11T18:31:28.485Z
• Profile URL: https://github.com/Permian-Global-Research

---

GitHub Events

Total

• Create event: 5
• Release event: 2
• Issues event: 12
• Watch event: 7
• Delete event: 1
• Issue comment event: 35
• Push event: 20
• Pull request review event: 5
• Pull request review comment event: 4
• Pull request event: 10
• Fork event: 2

Last Year

• Create event: 5
• Release event: 2
• Issues event: 12
• Watch event: 7
• Delete event: 1
• Issue comment event: 35
• Push event: 20
• Pull request review event: 5
• Pull request review comment event: 4
• Pull request event: 10
• Fork event: 2

---

Committers metadata

Last synced: 7 days ago

Name	Email	Commits
Mike Mahoney	m****8@g****m	140
Hugh Graham	4****m	5

Committer domains:

---

Issue and Pull Request metadata

Last synced: 1 day ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/permian-global-research/rsi

---

---

---

Package metadata

• Total packages: 1
• Total downloads:
  • cran: 446 last-month
• Total dependent packages: 0
• Total dependent repositories: 0
• Total versions: 8
• Total maintainers: 1

---

Dependencies

Score: 10.78468982173779