Combine the predictor importance (PI) and partial dependence (PD) data to provide an estimate of the importance and directionality of the land cover classes (i.e. habitat) used as covariates in the occurrence probability model. Note: This is one of, if not the most, computationally expensive operations in the package.

ebirdst_habitat(path, ext, data = NULL, stationary_associations = FALSE)

# S3 method for ebirdst_habitat
plot(x, n_habitat_types = 15, ...)



character; directory that the Status and Trends data for a given species was downloaded to. This path is returned by ebirdst_download() or get_species_path().


ebirdst_extent object; the spatiotemporal extent over which to calculate the habitat associations. Note that temporal component of ext is ignored is this function, habitat associations are always calculated for the full year.


as an alternative to providing the path argument specifying the location of the data package, the data required to calculate habitat associations can be provided explicitly as a named list of three data frames: pis containing PI data from load_pis(), pds containing PD data from load_pds(), and stixels containing stixel weights in a weight column. All data should be provided at the stixel level, identified by the stixel_id column, and only those stixels appearing in the stixels data frame will be used. Typically stixel weights are the proportion of the focal region that the given stixel overlaps. Ignored if path is provided. In most cases, users will want to avoid using these arguments and simply provide path instead.


logical; when the habitat association should be assumed to vary throughout the year and estimates should be made for each week of the year (the default) or habitat associations should be assumed constant throughout the year and a single set of estimates made for the full year. Annual estimates should only be made when you expect the associations to be constant throughout the year, e.g. for resident species.


ebirdst_habitat object; habitat relationships as calculated by ebirdst_habitat().


number of habitat types to include in the cake plot. The most important set of predictors will be chosen based on the maximum weekly importance value across the whole year.




An ebirdst_habitat object, consisting of a data frame giving the predictor importance and directionality for each predictor for each week of the year. The columns are:

  • predictor: the name of the predictor

  • week: the date of the center of the week, expressed as "MM-DD". This column will be missing if stationary_associations = TRUE.

  • importance: the relative importance of the predictor, these values are scaled so they sum to 1 within each week.

  • prob_pos_slope: the predicted probability that the slope of the PD

  • direction: the direction of the relationship, either 1 for a positive relationship, -1 for a negative relationship, or NA when the direction of the relationship is not significant.


The Status and Trends models use both effort (e.g. number of observers, length of checklist) and habitat (e.g. elevation, percent forest cover) covariates; for the full list consult ebirdst_predictors. This function calculates habitat associations only for the following covariates that most closely represent metrics of available habitat. In all cases these are calculated within a 1.5 km radius of each checklist:

  • Land cover: percent of each landcover class

  • Water cover: percent of each watercover class

  • Intertidal: percent cover of intertidal mudflats

  • Nighttime lights: total reflectance of nighttime lights

  • Roads: road density. There are 5 covariates distinguishing between different road types; however, these are grouped together for the sake of the habitat associations.

The plot() method can be used to produce a cake plot, a stacked area chart showing habitat associations in which area indicates the importance of a given land cover class and the position above or below the x-axis indicates the direction of the relationship.


if (FALSE) {
# download example data
path <- ebirdst_download("example_data", tifs_only = FALSE)
# or get the path if you already have the data downloaded
path <- get_species_path("example_data")

# define a spatial extent to calculate ppms over
e <- ebirdst_extent(c(xmin = -90, xmax = -82, ymin = 41, ymax = 48))

# compute habitat associations
habitat <- ebirdst_habitat(path = path, ext = e)
# produce a cake plot