Predict bird distributions conditioned on known locations

predict_between() computes marginal probability distributions at each timestep conditioned on observed locations at specific times, using a Hidden Markov Model forward-backward algorithm. Use predict_between() to produce predictions of where birds were at intermediate times when you have information about their locations or distributions at two or more points in time.

Usage

predict_between(
  bf,
  x_coord = NULL,
  y_coord = NULL,
  date = NULL,
  potentials = NULL,
  ...
)

Arguments

bf

A BirdFlow object.

x_coord, y_coord

Parallel numeric vectors of observed x and y coordinates (in the model's CRS). Must be provided together with date. Converted internally to indicator (one-hot) potentials. Cannot be used together with potentials.

date

When using x_coord/y_coord: a parallel vector of dates corresponding to each observation. When using potentials: a vector of dates corresponding to the columns of potentials (alternative to column names). Accepts any format recognized by lookup_timestep(): date strings ("2023-03-29"), Date objects, numeric timestep indices, or "t1"-style strings.

potentials

An n_active(bf) x n_obs matrix of soft observation potentials. Each column is a non-negative vector representing the observation likelihood at a given timestep. Timestep association is via column names or the date argument (exactly one required). Cannot be used together with x_coord/y_coord.

...

Arguments passed on to lookup_timestep_sequence

season

a season name, season alias, or "all". See lookup_season_timesteps() for options.

start

The starting point in time specified as a timestep, character date, or date object.

end

The ending point in time as a date or timestep.

direction

Either "forward" or "backward" defaults to "forward" if not processing dates. If using date input direction is optional and is only used to verify the direction implicit in the dates.

season_buffer

Only used with season input. season_buffer is passed to lookup_season_timesteps() and defaults to 1; it is the number of timesteps to extend the season by at each end.

n_steps

Alternative to end The end will be n_steps away from start in direction; and the resulting sequence will have n_step transitions and n_steps + 1 timesteps.

Value

A matrix of dimensions n_active(bf) x n_query_timesteps of marginal probability distributions p(x_t | observations), one column per timestep. Same format as predict(). The log-likelihood of the observations is stored as attribute log_z.

See also

predict() for predictions from a single point in time, route_between() for creating routes from the same inputs as predict_between().

Examples

bf <- BirdFlowModels::amewoo
xy <- latlon_to_xy(lat = c(30.5, 45.5), lon = c(-91.5, -68.5), bf)
distr <- predict_between(bf,
                         x_coord = xy$x, y_coord = xy$y,
                         date = c("2023-02-15", "2023-05-01"))
plot_distr(distr, bf, dynamic_scale = TRUE)