Title:	Create Useful Summaries of the Portal Data
Version:	0.4.4
Description:	Download and generate summaries for the rodent, plant, ant, and weather data from the Portal Project. Portal is a long-term (and ongoing) experimental monitoring site in the Chihuahuan desert. The raw data files can be found at https://github.com/weecology/portaldata.
License:	MIT + file LICENSE
URL:	https://weecology.github.io/portalr/, https://github.com/weecology/portalr
BugReports:	https://github.com/weecology/portalr/issues
Depends:	R (≥ 3.2.3)
Imports:	cli, clipr, dplyr, forecast, httr, lubridate, lunar, magrittr, rlang, tibble, tidyr, tidyselect (≥ 1.2.1), zoo
Suggests:	cowplot, ggplot2, httptest, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Encoding:	UTF-8
RoxygenNote:	7.3.2
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-06-26 04:29:20 UTC; GlendaYenni
Author:	Glenda M. Yenni [aut, cre], Hao Ye [aut], Erica M. Christensen [aut], Juniper L. Simonis [aut], Ellen K. Bledsoe [aut], Renata M. Diaz [aut], Shawn D. Taylor [aut], Ethan P, White [aut], S.K. Morgan Ernest [aut], Weecology [cph]
Maintainer:	Glenda M. Yenni <glenda@weecology.org>
Repository:	CRAN
Date/Publication:	2025-06-30 08:50:06 UTC

Creates summaries of the Portal data

Description

This package is designed to be an interface to the Portal data, which resides online at https://github.com/weecology/portalData. Its contains a set of functions to download, clean, and summarize the data.

Author(s)

Maintainer: Glenda M. Yenni glenda@weecology.org (ORCID)

Authors:

• Hao Ye (ORCID)

• Erica M. Christensen (ORCID)

• Juniper L. Simonis (ORCID)

• Ellen K. Bledsoe (ORCID)

• Renata M. Diaz (ORCID)

• Shawn D. Taylor (ORCID)

• Ethan P, White (ORCID)

• S.K. Morgan Ernest (ORCID)

Other contributors:

• Weecology [copyright holder]

See Also

Useful links:

• https://weecology.github.io/portalr/

• https://github.com/weecology/portalr

• Report bugs at https://github.com/weecology/portalr/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Add Seasons

Description

Higher-order data summaries, by 6-month seasons, 3-month seasons, or year. Also applies specified functions to the specified summary level.

yearly generates a table of yearly means

Usage

add_seasons(
  data,
  level = "site",
  season_level = 2,
  date_column = "yearmon",
  summary_funs = NA,
  path = get_default_data_path(),
  download_if_missing = TRUE,
  clean = TRUE
)

yearly(...)

Arguments

Value

a data.frame with additional "season" and "year" column, and other columns summarized as specified. If no summary function is specified, "season" and "year" columns are added to original dataframe, as well as a "seasonyear" column which correctly assigns months to seasons for grouping (eg December 2000 in winter 2001, rather than winter 2000).

Ant Bait Presence Absence

Description

Get ant species presence/absence by year/plot/stake from bait census data

Bait census data is more consistent over time than the colony census data. This function assumes that all species present in at least one census were censused in all years.

Usage

bait_presence_absence(
  path = get_default_data_path(),
  level = "Site",
  download_if_missing = TRUE,
  quiet = FALSE
)

Arguments

Value

data frame with year, species, (plot if applicable), and presence [1, 0]

Manage the default path for downloading Portal Data into

Description

check_default_data_path checks if a default data path is set, and prompts the user to set it if it is missing.

get_default_data_path gets the value of the data path environmental variable

use_default_data_path has 3 steps. First, it checks for the presence of a pre-existing setting for the environmental variable. Then it checks if the folder exists and creates it, if needed. Then it provides instructions for setting the environmental variable.

Usage

check_default_data_path(
  ENV_VAR = "PORTALR_DATA_PATH",
  MESSAGE_FUN = message,
  DATA_NAME = "Portal data"
)

get_default_data_path(fallback = "~", ENV_VAR = "PORTALR_DATA_PATH")

use_default_data_path(path = NULL, ENV_VAR = "PORTALR_DATA_PATH")

Arguments

Value

FALSE if there is no path set, TRUE otherwise

None

Check for latest version of data files

Description

Check the latest version against the data that exists on the GitHub repo

Usage

check_for_newer_data(path = get_default_data_path())

Arguments

Value

bool TRUE if there is a newer version of the data online

Do basic cleaning of Portal plant data

Description

This function does basic quality control of the Portal plant data. It is mainly called from summarize_plant_data, with several arguments passed along.

The specific steps it does are, in order: (1) correct species names according to recent vouchers, if requested (2) restrict species to annuals or non-woody (3) remove records for unidentified species (5) exclude the plots that aren't long-term treatments

Usage

clean_plant_data(
  data_tables,
  type = "All",
  unknowns = FALSE,
  correct_sp = TRUE
)

Arguments

Do basic cleaning of Portal rodent data

Description

This function does basic quality control of the Portal rodent data. It is mainly called from summarize_rodent_data, with several arguments passed along.

The specific steps it does are, in order: (1) add in missing weight data (2) remove records with "bad" period codes or plot numbers (3) remove records for unidentified species (4) exclude non-granivores (5) exclude incomplete trapping sessions (6) exclude the plots that aren't long-term treatments

Usage

clean_rodent_data(
  rodent_data,
  species_table,
  fillweight = FALSE,
  type = "Rodents",
  unknowns = FALSE
)

Arguments

Ant Colony Presence Absence

Description

Get ant species presence/absence by year/plot/stake from colony census data

Anomalies in ant colony census protocol over the years means that it can be difficult to discern true absences of all species in all years. This function uses information from Portal_ant_species.csv and Portal_ant_dataflags.csv to predict true presence/absence of species per plot per year. If a more conservative estimate is desired, setting the argument 'rare_sp = T' will only include species we are confident were censused regularly. Setting 'rare_sp = F' may include some false absences, since it is unknown if some rare species were censused in all years. Unknowns may also be excluded from output if desired.

Usage

colony_presence_absence(
  path = get_default_data_path(),
  level = "Site",
  rare_sp = FALSE,
  unknowns = FALSE,
  download_if_missing = TRUE,
  quiet = FALSE
)

Arguments

Value

data frame with year, species, (plot if applicable), and presence [1, 0, NA]

Download the PortalData repo

Description

Downloads specified version of the Portal data.

Usage

download_observations(
  path = get_default_data_path(),
  version = "latest",
  source = "github",
  quiet = FALSE,
  verbose = FALSE,
  pause = 30,
  timeout = getOption("timeout"),
  force = FALSE
)

Arguments

Value

NULL invisibly.

Forecast ndvi using a seasonal auto ARIMA

Description

Forecast ndvi using a seasonal auto ARIMA

Usage

fcast_ndvi(hist_ndvi, level, lead, moons = NULL)

Arguments

Details

ndvi values are forecast using auto.arima with seasonality (using a Fourier transform)

Value

a data.frame with time and ndvi values

Fill in historic ndvi data to the complete timeseries being fit

Description

Fill in historic ndvi data to the complete timeseries being fit

Usage

fill_missing_ndvi(ndvi, level, last_time, moons = NULL)

Arguments

Details

missing values during the time series are replaced using na.interp, missing values at the end of the time series are forecast using auto.arima with seasonality (using Fourier transform)

Value

a data.frame with time and ndvi values

Period code for incomplete censuses

Description

Determines incomplete censuses by finding dates when some plots were trapped, but others were not.

Usage

find_incomplete_censuses(trapping_table, min_plots, min_traps)

Arguments

Value

Data.table of period codes when not all plots were trapped.

Return Citation for Portal Data

Description

Return Citation for Portal Data

Usage

get_dataset_citation()

Value

An object of class "citation". For more details, see 'citation()'

Get future newmoon dates and numbers

Description

Get next newmoon dates and assign newmoon numbers for forecasting

Usage

get_future_newmoons(newmoons, nfuture_newmoons = NULL)

Arguments

Value

expected newmoons table for requested future newmoons

read in a raw datafile from the downloaded data or the GitHub repo

Description

does checking for whether a particular datafile exists and then reads it in, using na_strings to determine what gets converted to NA. It can also download the dataset if it's missing locally.

Usage

load_datafile(
  datafile,
  na.strings = "",
  path = get_default_data_path(),
  download_if_missing = TRUE,
  quiet = TRUE,
  ...
)

Arguments

Read in the Portal data files

Description

Loads Portal data files from either a user-defined path or the online Github repository. If the user-defined path is un- available, the default option is to download to that location.

load_rodent_data loads the rodent data files

load_plant_data loads the plant data files

load_ant_data loads the ant data files

load_trapping_data loads just the rodent trapping files

Usage

load_rodent_data(
  path = get_default_data_path(),
  download_if_missing = TRUE,
  clean = TRUE,
  quiet = FALSE,
  ...
)

load_plant_data(
  path = get_default_data_path(),
  download_if_missing = TRUE,
  quiet = FALSE,
  ...
)

load_ant_data(
  path = get_default_data_path(),
  download_if_missing = TRUE,
  quiet = FALSE,
  ...
)

load_trapping_data(
  path = get_default_data_path(),
  download_if_missing = TRUE,
  clean = TRUE,
  quiet = FALSE,
  ...
)

Arguments

Value

load_rodent_data returns a list of 5 dataframes:

load_plant_data returns a list of 7 dataframes:

load_ant_data returns a list of 4 dataframes:

load_trapping_data returns a list of 2 dataframes:

Conform NA entries to "NA" entries

Description

Given the species abbreviation Neotoma albigula (NA), when data are read in, there can be an NA when it should be an "NA". This function conforms the entries to be proper character values.

Usage

na_conformer(dfv, colname = "species")

Arguments

Value

x with any NA in colname replaced with "NA".

Examples

 na_conformer(c("a", "b", NA, "c"))

NDVI by calendar month or lunar month

Description

Summarize NDVI data to monthly or lunar monthly level

Usage

ndvi(
  level = "monthly",
  sensor = "landsat",
  fill = FALSE,
  forecast = FALSE,
  path = get_default_data_path(),
  download_if_missing = TRUE
)

Arguments

Phenocam data products by day, calendar month, or lunar month

Description

Summarize phenocam data products to either daily, monthly, or lunar monthly level.

Usage

phenocam(level = "daily", path = get_default_data_path())

Arguments

Prints a portal_data_list object

Description

Prints a portal_data_list object

Usage

## S3 method for class 'portal_data_list'
print(x, ...)

Arguments

If a Value is NULL, Trigger the Parent Function's Return

Description

If the focal input is NULL, return value from the parent function. Should only be used within a function.

Usage

return_if_null(x, value = NULL)

Arguments

Value

If x is not NULL, NULL is returned. If x is NULL, the result of return with value as its input evaluated within the parent function's environment is returned.

Examples

 ff <- function(x = 1, null_return = "hello"){
   return_if_null(x, null_return)
   x
 }
 ff()
 ff(NULL)

Rodent species abbreviations

Description

Creates a simple character vector of abbreviations for the Portal Rodents.

Usage

rodent_species(
  path = get_default_data_path(),
  type = "code",
  set = "all",
  total = FALSE
)

forecasting_species(
  path = get_default_data_path(),
  total = FALSE,
  type = "abbreviation"
)

Arguments

Value

character vector of species abbreviations.

Generate percent cover from Portal plant transect data

Description

This function calculates percent cover from transect data. It handles the pre-2015 data differently from the current transects, becase they are collected differently. But it returns a single time-series with all years of transect data available. It also returns mean height beginning in 2015.

Usage

shrub_cover(
  path = get_default_data_path(),
  type = "Shrubs",
  plots = "all",
  unknowns = FALSE,
  correct_sp = TRUE,
  download_if_missing = TRUE,
  quiet = FALSE
)

Arguments

Value

a data.frame of percent cover and mean height

Return cleaned Portal rodent individual data

Description

This function cleans and subsets the data based on a number of arguments. It returns stake number and individual level data.

Usage

summarize_individual_rodents(
  path = get_default_data_path(),
  clean = TRUE,
  type = "Rodents",
  length = "all",
  unknowns = FALSE,
  time = "period",
  fillweight = FALSE,
  min_plots = 1,
  min_traps = 1,
  download_if_missing = TRUE,
  quiet = FALSE
)

summarise_individual_rodents(
  path = get_default_data_path(),
  clean = TRUE,
  type = "Rodents",
  length = "all",
  unknowns = FALSE,
  time = "period",
  fillweight = FALSE,
  min_plots = 1,
  min_traps = 1,
  download_if_missing = TRUE,
  quiet = FALSE
)

Arguments

Value

a data.frame

Generate summaries of Portal plant data

Description

This function is a generic interface into creating summaries of the Portal plant species data. It contains a number of arguments to specify both the kind of data to summarize, at what level of aggregation, various choices for dealing with data quality, and output format.

plant_abundance generates a table of plant abundance

Usage

summarize_plant_data(
  path = get_default_data_path(),
  level = "Site",
  type = "All",
  length = "all",
  plots = length,
  unknowns = FALSE,
  correct_sp = TRUE,
  shape = "flat",
  output = "abundance",
  na_drop = switch(tolower(level), quadrat = FALSE, plot = FALSE, treatment = TRUE, site
    = TRUE, TRUE),
  zero_drop = switch(tolower(level), quadrat = TRUE, plot = FALSE, treatment = TRUE, site
    = TRUE, TRUE),
  min_quads = 1,
  effort = TRUE,
  download_if_missing = TRUE,
  quiet = FALSE
)

plant_abundance(..., shape = "flat")

summarise_plant_data(
  path = get_default_data_path(),
  level = "Site",
  type = "All",
  length = "all",
  plots = length,
  unknowns = FALSE,
  correct_sp = TRUE,
  shape = "flat",
  output = "abundance",
  na_drop = switch(tolower(level), quadrat = FALSE, plot = FALSE, treatment = TRUE, site
    = TRUE, TRUE),
  zero_drop = switch(tolower(level), quadrat = TRUE, plot = FALSE, treatment = TRUE, site
    = TRUE, TRUE),
  min_quads = 1,
  effort = TRUE,
  download_if_missing = TRUE,
  quiet = FALSE
)

Arguments

Value

a data.frame in either "long" or "wide" format, depending on the value of 'shape'

Generate summaries of Portal rodent data

Description

This function is a generic interface into creating summaries of the Portal rodent species data. It contains a number of arguments to specify the kind of data to summarize (at what level of aggregation) and various choices for dealing with data quality, and output format.

abundance generates a table of rodent abundance

* biomass() generates a table of rodent biomass

* energy() generates a table of rodent energy (computed as 5.69 * (biomass ^ 0.75) after White et al 2004)

* rates() generates a table of rodent growth rates (computed as r=log(N[t+1]/N[t])

Usage

summarize_rodent_data(
  path = get_default_data_path(),
  clean = TRUE,
  level = "Site",
  type = "Rodents",
  length = "all",
  plots = length,
  unknowns = FALSE,
  shape = "crosstab",
  time = "period",
  output = "abundance",
  fillweight = (output != "abundance"),
  na_drop = TRUE,
  zero_drop = switch(tolower(level), plot = FALSE, treatment = TRUE, site = TRUE),
  min_traps = 1,
  min_plots = 24,
  effort = FALSE,
  download_if_missing = TRUE,
  quiet = FALSE,
  include_unsampled = FALSE
)

abundance(...)

biomass(...)

energy(...)

rates(...)

summarise_rodent_data(
  path = get_default_data_path(),
  clean = TRUE,
  level = "Site",
  type = "Rodents",
  length = "all",
  plots = length,
  unknowns = FALSE,
  shape = "crosstab",
  time = "period",
  output = "abundance",
  fillweight = (output != "abundance"),
  na_drop = TRUE,
  zero_drop = switch(tolower(level), plot = FALSE, treatment = TRUE, site = TRUE),
  min_traps = 1,
  min_plots = 24,
  effort = FALSE,
  download_if_missing = TRUE,
  quiet = FALSE,
  include_unsampled = FALSE
)

Arguments

Value

a data.frame in either "long" or "wide" format, depending on the value of 'shape'

Weather by day, calendar month, or lunar month

Description

Summarize hourly weather data to either daily, monthly, or lunar monthly level.

Usage

weather(
  level = "daily",
  fill = FALSE,
  horizon = 365,
  temperature_limit = 4,
  path = get_default_data_path()
)

Arguments