Skip to content

docs: update README and vignette with get_rap_table() info and examples #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brownag merged 2 commits into from
Feb 12, 2026
Merged

docs: update README and vignette with get_rap_table() info and examples #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87dcfef
Updated README.Rmd and demo.Rmd to include information about and exam…
s-appleby Feb 12, 2026
7ea75a4
fixed typos in readme and demo
s-appleby Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ remotes::install_github("brownag/rapr")

## Sources, Products, and Band Information

Two sets of gridded RAP products are available (see `get_rap()` `source` argument). Also, you can access the API endpoint for the 16-day production tabular data (see `get_rap_production16day_table()`).
Two sets of gridded RAP products are available (see `get_rap()` `source` argument). You can also access four time series API endpoints providing tabular data (see `get_rap_table()` `product` argument).

- `"rap-30m"` is Landsat-derived and has approximately 30 meter resolution in WGS84 decimal degrees (`"EPSG:4326"`). This is the data source that has been used in the 'rapr' package since 2022.

Expand Down Expand Up @@ -94,6 +94,34 @@ resolution from 2018 to present:
- `product = "pj"` returns fractional cover estimates of Juniperus monosperma, J. occidentalis, J. osteosperma, J. scopulorum, Pinus edulis, and P. monophylla.

- 1 Band: `"pinyon-juniper"` (**% cover**)

The four time series API endpoints accessed through `get_rap_table()` return mean values for each period and area of interest for a number of vegetation metrics:

- `product = "cover"` returns yearly fractional cover, including:
- `"AFG"` (Annual Forb and Grass cover)
- `"PFG"` (Perennial Forb and Grass cover)
- `"SHR"` (Shrub cover)
- `"TRE"` (Tree cover)
- `"LTR"` (Litter cover)
- `"BGR"` (Bare Ground cover)

- `product = "coverMeteorology"` returns the same data provided by `"cover"` above, plus:
- `"annualTemp"` (Annual average temperature in degrees Fahrenheit)
- `"annualPrecip"` (Annual total precipitation in inches)

- `product = "production"` returns annual production, including:
- `"AFG"` (Annual Forb and Grass production)
- `"PFG"` (Perennial Forb and Grass production)
- `"HER"` (Herbaceous production)

- `product = "production16day"` returns 16-day production, including:
- `"date"` (production estimate date)
- `"doy"` (production estimate Julian day of year)
- `"AFG"` (Annual Forb and Grass production)
- `"PFG"` (Perennial Forb and Grass production)
- `"HER"` (Herbaceous production)

Each of these time series is returned as a _data.frame_ with requested time-series data by year or 16-day production period. In addition to the columns described above, all tables include columns for `"year"` (production or cover estimate year) and `"feature"` (feature ID, row number from `aoi`). Units are **% cover** for fractional cover and **lbs / acre** for production.

## Temporary Files

Expand Down Expand Up @@ -135,7 +163,7 @@ resolution from 2018 to present:

This example shows how to use a {[terra](https://github.com/rspatial/terra)}
SpatVector containing a rectangular polygon with `rapr::get_rap()` to obtain RAP
grids for the corresponding extent.
grids and a mean annual vegetation cover table for the corresponding extent.
{[terra](https://cran.r-project.org/package=terra)},
{[raster](https://cran.r-project.org/package=raster)},
{[sf](https://cran.r-project.org/package=sf)} and
Expand All @@ -160,6 +188,16 @@ res <- get_rap(
res

plot(res)

# Mean fractional vegetation cover estimates
res_tab <- get_rap_table(
vect("POLYGON ((-120 36.99,-119.99 37,-120 37,-120 36.99))",
crs = "EPSG:4326"),
product = "cover",
years = c(1989, 1999, 2009, 2019)
)

res_tab
```

In lieu of a spatial object from {terra}, {raster}, {sf} or {sp} packages you
Expand Down
68 changes: 59 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ remotes::install_github("brownag/rapr")
## Sources, Products, and Band Information

Two sets of gridded RAP products are available (see `get_rap()` `source`
argument). Also, you can access the API endpoint for the 16-day
production tabular data (see `get_rap_production16day_table()`).
argument). You can also access four time series API endpoints providing
tabular data (see `get_rap_table()` `product` argument).

- `"rap-30m"` is Landsat-derived and has approximately 30 meter
resolution in WGS84 decimal degrees (`"EPSG:4326"`). This is the data
Expand Down Expand Up @@ -109,6 +109,39 @@ meter resolution from 2018 to present:

- 1 Band: `"pinyon-juniper"` (**% cover**)

The four time series API endpoints accessed through `get_rap_table()`
return mean values for each period (annual or 16 days production) and
area of interest for a number of vegetation metrics:

- `product = "cover"` returns yearly fractional cover, including:
- `"AFG"` (Annual Forb and Grass cover)
- `"PFG"` (Perennial Forb and Grass cover)
- `"SHR"` (Shrub cover)
- `"TRE"` (Tree cover)
- `"LTR"` (Litter cover)
- `"BGR"` (Bare Ground cover)
- `product = "coverMeteorology"` returns the same data provided by
`"cover"` above, plus:
- `"annualTemp"` (Annual average temperature in degrees Fahrenheit)
- `"annualPrecip"` (Annual total precipitation in inches)
- `product = "production"` returns annual production, including:
- `"AFG"` (Annual Forb and Grass production)
- `"PFG"` (Perennial Forb and Grass production)
- `"HER"` (Herbaceous production)
- `product = "production16day"` returns 16-day production, including:
- `"date"` (production estimate date)
- `"doy"` (production estimate Julian day of year)
- `"AFG"` (Annual Forb and Grass production)
- `"PFG"` (Perennial Forb and Grass production)
- `"HER"` (Herbaceous production)

Each of these time series is returened as a *data.frame* with requested
time-series data by year or 16-day production period. In addition to the
columns described above, all tables include columns for `"year"`
(production estimate year) and `"feature"` (feature ID, row number from
`aoi`). Units are **% cover** for fractional cover and **lbs / acre**
for production.

## Temporary Files

Large requests may generate intermediate objects that will be stored as
Expand Down Expand Up @@ -148,8 +181,8 @@ be used. See `rap_projection()` for options and details.

This example shows how to use a
{[terra](https://github.com/rspatial/terra)} SpatVector containing a
rectangular polygon with `rapr::get_rap()` to obtain RAP grids for the
corresponding extent.
rectangular polygon with `rapr::get_rap()` to obtain RAP grids and a
mean annual vegetation cover table for the corresponding extent.
{[terra](https://cran.r-project.org/package=terra)},
{[raster](https://cran.r-project.org/package=raster)},
{[sf](https://cran.r-project.org/package=sf)} and
Expand All @@ -160,8 +193,7 @@ the source data grid system.

``` r
library(terra)
#> Warning: package 'terra' was built under R version 4.5.1
#> terra 1.8.56
#> terra 1.8.93
library(rapr)

res <- get_rap(
Expand Down Expand Up @@ -194,7 +226,25 @@ res
plot(res)
```

<img src="man/figures/README-example-1.png" width="100%" />
<img src="man/figures/README-example-1.png" alt="" width="100%" />

``` r

res_tab <- get_rap_table(
vect("POLYGON ((-120 36.99,-119.99 37,-120 37,-120 36.99))",
crs = "EPSG:4326"),
product = "cover",
years = c(1989, 1999, 2009, 2019)
)
#> Loading required namespace: jsonlite

res_tab
#> year AFG PFG SHR TRE LTR BGR feature
#> 1 1989 36.01616 17.454813 5.338883 2.108970 14.982701 9.831511 1
#> 2 1999 28.42868 17.714419 3.857973 3.043423 15.814780 8.038963 1
#> 3 2009 27.65144 6.040328 1.537997 1.619856 13.777344 7.940900 1
#> 4 2019 21.38089 4.805698 1.665103 1.265552 4.814131 2.878002 1
```

In lieu of a spatial object from {terra}, {raster}, {sf} or {sp}
packages you may specify a bounding box using a numeric vector
Expand All @@ -214,8 +264,8 @@ e.g. `get_rap(x = c(-120, 37, -119.99, 36.99), ...)`.

#> To cite rapr in publications use:
#>
#> Brown A (2025). _rapr: Interface to Rangeland Analysis Platform (RAP)
#> Vegetation Biomass and Cover Products_. R package version 1.1.0,
#> Brown A (2026). _rapr: Interface to Rangeland Analysis Platform (RAP)
#> Vegetation Biomass and Cover Products_. R package version 1.1.2,
#> <https://CRAN.R-project.org/package=rapr>.
#>
#> Allred, B.W., S.E. McCord, T.J. Assal, B.T. Bestelmeyer, C.S. Boyd,
Expand Down
29 changes: 29 additions & 0 deletions vignettes/demo.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,3 +109,32 @@ if (file.exists("annual_forb_and_grass_biomass.gif")) {
cat("![](annual_forb_and_grass_biomass.gif)")
}
```

## Tabular data

Finally, we will use {rapr} to download mean fractional vegetation cover values
(% cover) from 1995 to 2025, again using the polygon `p` to define the area of interest.

```{r}
rap_tab <- get_rap_table(
p,
product = "cover",
years = 1995:2025
)
```

Once the vegetation cover data has finished downloading, let's look at the table:

```{r}
print(rap_tab)
```

and plot mean `"PFG"` (Perennial Forb and Grass cover) over those 20 years:

```{r}
plot(rap_tab$year,
rap_tab$PFG,
xlab="Year",
ylab="Perennial Forb and Grass cover (%)",
type="l")
```