Package 'sohungry'

Diet summaries from the SCAR Southern Ocean Diet and Energetics Database

Description

Given a diet data.frame, the prey or predators are aggregated to group level and dietary importance values reported. Note that dietary importance values are currently calculated by unweighted averaging across studies (so that e.g. a study of 100 individuals will carry the same weight as a study of one individual).

Usage

diet_summary(
  x,
  summary_type = "prey",
  minimum_importance = 0,
  treat_trace_values_as = 0
)

Arguments

x	data.frame: diet data, as returned by so_diet
summary_type	string: either "predators" (report the predators in the data) or "prey" (report the prey items)
minimum_importance	numeric: ignore records with dietary importance less than this threshold
treat_trace_values_as	numeric: what numeric value to use for a dietary item recorded as "trace"

Value

data.frame with columns:

• N_fraction_diet_by_weight - number of diet observations where fraction of diet by weight was quantified

• fraction_diet_by_weight - mean fraction of diet by weight

• N_fraction_occurrence - number of diet observations where fraction of occurrence quantified

• fraction_occurrence - mean fraction of occurrence

• N_fraction_diet_by_prey_items - number of diet observations where fraction of diet by number of prey items was quantified

• fraction_diet_by_prey_items - mean fraction of diet by number of prey items

Examples

## Not run: 
  x <- so_diet()

  ## summary of what Electrona carlsbergi eats
  x %>% filter_by_predator_name("Electrona carlsbergi") %>%
  diet_summary(summary_type = "prey")

  ## summary of what eats Electrona carlsbergi
  x %>% filter_by_prey_name("Electrona carlsbergi") %>%
  diet_summary(summary_type = "predators")

## End(Not run)

---

Filter out diet data below a given importance threshold

Description

A diet record is retained if any of the importance measures are above the threshold. Records with all-NA importance values will be removed.

Usage

filter_by_importance(x, threshold, which_measures = "any")

Arguments

x	data.frame: diet data, as returned by so_diet
threshold	numeric: remove entries below this threshold
which_measures	string: one or more of "fraction_diet_by_weight", "fraction_diet_by_prey_items", "fraction_occurrence", or "any" (shorthand for all three)

Value

data.frame

See Also

so_diet, replace_by_importance

Examples

## Not run: 
  x <- so_diet()
  x %>% filter_by_importance(0.1)

## End(Not run)

---

Filter data by predator, prey, or taxon name

Description

A convenience function that matches on the species and/or group names. filter_by_predator_name is a convenience shorthand for filter_by_name(...,name_type="predator") filter_by_prey_name is a convenience shorthand for filter_by_name(...,name_type="prey")

Usage

filter_by_name(x, name, name_type)

filter_by_predator_name(x, name)

filter_by_prey_name(x, name)

Arguments

x	data.frame: diet data as returned by e.g. so_diet or so_isotopes
name	character: vector of one or more names to match on
name_type	string: one of "predator", "prey", "predatorprey" (to match on either predator names or prey names), or "taxon". If missing will default to predator names for diet data, and taxon names for isotope data

Value

data.frame

See Also

so_diet, so_isotopes

Examples

## Not run: 
  x <- so_isotopes()
  x %>% filter_by_name(c("Electrona", "Gymnoscopelus"), "taxon")

  x <- so_diet()
  x %>% filter_by_name("Electrona carlsbergi", name_type = "predator")
  ## equivalent to
  x %>% filter_by_predator_name("Electrona carlsbergi")

## End(Not run)

---

Replace diet data entries below a given importance threshold

Description

Replace diet data entries below a given importance threshold

Usage

replace_by_importance(x, threshold, replace_with = NA, which_measures = "all")

Arguments

x	data.frame: diet data, as returned by so_diet
threshold	numeric: replace entries below this threshold
replace_with	numeric: value to replace with
which_measures	string: one or more of "fraction_diet_by_weight", "fraction_diet_by_prey_items", "fraction_occurrence", or "all" (shorthand for all three)

Value

data.frame

See Also

so_diet filter_by_importance

Examples

## Not run: 
  x <- so_diet()
  ## discard entries representing less than 10% of diet
  x <- x %>% replace_by_importance(0.1)

## End(Not run)

---

Replace "trace" values in diet data

Description

Some diet studies record small amounts of a prey item as "trace". These are encoded in the diet database using the value -999. This function replaces those entries with the nominated numeric value.

Usage

replace_trace_values(x, replace_with = 0)

Arguments

x	data.frame: diet data, as returned by so_diet
replace_with	numeric: value to use as a replacement for "trace" values

Value

data.frame

See Also

so_diet

Examples

## Not run: 
  x <- so_diet() %>% replace_trace_values()

## End(Not run)

---

Load data from the SCAR Southern Ocean Diet and Energetics database

Description

Load data from the SCAR Southern Ocean Diet and Energetics database. Data will be fetched from the remote server and optionally cached locally, or fetched from the local cache, depending on the arguments passed.

Usage

so_diet(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE
)

so_dna_diet(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE
)

so_isotopes(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE,
  format = "mv"
)

so_energetics(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE
)

so_lipids(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE
)

so_sources(
  method = "get",
  cache_directory = "session",
  refresh_cache = FALSE,
  public_only = TRUE,
  verbose = FALSE
)

Arguments

method	string: "get" (fetch the data via a web GET call)
cache_directory	string: (optional) cache the data locally in this directory, so that they can be used offline later. Values can be "session" (a per-session temporary directory will be used, default), "persistent" (the directory returned by rappdirs::user_cache_dir() will be used), or a string giving the path to the directory to use. Use NULL for no caching. An attempt will be made to create the cache directory if it does not exist. A warning will be given if a cached copy of the data file exists and is more than 30 days old. Use refresh_cache = TRUE to refresh the cached data if necessary
refresh_cache	logical: if TRUE, and data already exist in the cache_directory, they will be refreshed. If FALSE, the cached data will be used
public_only	logical: ignored, here for historical reasons
verbose	logical: show progress messages?
format	string: ignored, kept for historical purposes only

Details

The format parameter was introduced to the so_isotopes function in package version 0.4.0. The previous default format was "wide" (the data were formatted with one row per record and multiple measurements (of different isotopes) per row). With format "mv", the data were in measurement-value (long) format with multiple rows per original record, split so that each different isotope measurement appeared in its own row. As of package version 0.9.0, "wide" has been hard-deprecated and "mv" is the only option.

Value

data.frame

Examples

## Not run: 
  ## conventional diet data
  x <- so_diet()
  subset(x, predator_name == "Electrona antarctica")

  ## DNA diet data
  x <- so_dna_diet()
  subset(x, predator_name == "Thalassarche melanophris")

  ## stable isotopes
  x <- so_isotopes()

  ## energetics data
  x <- so_energetics()

  ## lipids data
  x <- so_lipids()

## End(Not run)

---

Return the DOI of the SCAR Diet and Energetics Database being used

Description

Return the DOI of the SCAR Diet and Energetics Database being used

Usage

so_doi(cache_directory, ...)

Arguments

cache_directory	string: (optional) the local cache directory containing the data. If no valid DOI is found in that directory, the return value will be NA_character_. If cache_directory is not supplied, the DOI of the data last accessed in this session will be returned (and if no data has yet been accessed, the most recent known DOI will be returned)
...	: additional parameters passed to so_diet etc

Value

string

See Also

so_diet, so_dna_diet, so_isotopes, so_energetics, so_lipids

Examples

## Not run: 
  xd <- so_diet(cache_directory = "session")
  ## the DOI of the data just read
  so_doi()

  ## the DOI of the data in a particular cache directory
  so_doi(cache_directory = "c:/my/cache/dir")

## End(Not run)

---

Stable isotope corrections

Description

Apply stable isotope corrections following various published methods.

Usage

so_isotope_adjust(
  d13c = NULL,
  d15n = NULL,
  cn_ratio = NULL,
  method,
  cn_ratio_type = "mass"
)

Arguments

d13c	numeric: d13C values
d15n	numeric: d15n values
cn_ratio	numeric: C:N ratio values
method	string: one of "Weldrick 2019", "Kiljunen 2006", "Kiljunen 2006 atomic" "Post 2007" "Smyntek 2007" "Smyntek 2007 atomic" "Logan 2008" "Syvaranta 2010" (see Details)
cn_ratio_type	string: the basis of the C:N ratio (either "mass" or "atomic")

Details

Methods:

• "Weldrick 2019": lipid normalization of d13C values following Weldrick CK et al. (2019) Can lipid removal affect interpretation of resource partitioning from stable isotopes in Southern Ocean pteropods? Rapid Communications in Mass Spectrometry. https://doi.org/10.1002/rcm.8384

• "Kiljunen 2006": lipid normalization of d13C values following Kiljunen M et al. (2006) A revised model for lipid-normalizing d13C values from aquatic organisms, with implications for isotope mixing models. Journal of Applied Ecology. https://doi.org/10.1111/j.1365-2664.2006.01224.x

• "Kiljunen 2006 atomic": as for Kiljunen 2006 but using atomic C:N ratio

• "Post 2007": lipid normalization of d13C values followingPost DM et al. (2007) Getting to the fat of the matter: Models, methods and assumptions for dealing with lipids in stable isotope analyses. Oecologia. https://doi.org/10.1007/s00442-006-0630-x

• "Smyntek 2007": lipid normalization of d13C values following Smyntek PM et al. (2007) A standard protocol for stable isotope analysis of zooplankton in aquatic food web research using mass balance correction models. Limnol. Oceanogr. https://doi.org/10.4319/lo.2007.52.5.2135

• "Smyntek 2007 atomic": as for Smyntek 2007 but using atomic C:N ratio

• "Logan 2008": lipid normalization of d13C values following Logan JM et al. (2008) Lipid corrections in carbon and nitrogen stable isotope analyses: comparison of chemical extraction and modelling methods. Journal of Animal Ecology. https://doi.org/10.1111/j.1365-2656.2008.01394.x

• "Syvaranta 2010": lipid normalization of d13C values following Syväranta J and Rautio M (2010) Zooplankton, lipids and stable isotopes: Importance of seasonal, latitudinal, and taxonomic differences. Canadian Journal of Fisheries and Aquatic Science. https://doi.org/10.1139/F10-091

Value

A data.frame with corrected values, comprising one or more of the columns "d13c", "d15n", "cn_ratio" depending on the method.

See Also

so_isotopes

Examples

## lipid normalization of bulk d13C following Weldrick et al. 2019
so_isotope_adjust(d13c = -26.816, cn_ratio = 3.7014, cn_ratio_type = "mass",
                  method = "Weldrick 2019")

---

sohungry

Description

Provides access to data from the SCAR Southern Ocean Diet and Energetics Database.

References

https://scar.org/resources/southern-ocean-diet-energetics/

---