state_to_trajectory {ecoregime}

Position of a state with respect to a trajectory

Description

Define the position of a state with respect to a reference trajectory based on its distance from the trajectory and the length and direction of the trajectory.

Usage

state_to_trajectory(
  d,
  trajectories,
  states,
  target_states,
  reference,
  method,
  coordStates = NULL
)

Arguments

d

Either a symmetric matrix or an object of class dist containing the dissimilarities between each pair of states.

trajectories

Vector indicating the trajectory or site to which each state in d belongs.

states

Vector of integers indicating the order of the states in d for each trajectory (assign 1 if the state does not belong to any trajectory).

target_states

Vector of integers indicating the indices in trajectories and states of the ecological states for which their relative position will be calculated.

reference

Vector of the same class of trajectories or object of class RETRA indicating the reference trajectory to calculate the relative position of the target_states

method

Method to calculate the distance and relative position of the target_states and the reference. One of "nearest_state", "projection" or "mixed" (see Details).

coordStates

Matrix containing the coordinates of each state (rows) and axis (columns) of a metric ordination space (see Details)

Details

state_to_trajectory() can calculate the distance and relative position of one or more target_states relative to a reference trajectory by three different methods:

• "nearest_state" returns the dissimilarity of the target_states to the nearest state of the reference trajectory (distance) and calculates the relative position of the nearest state within the reference.

• "projection" returns the dissimilarity of the target_states to their projection onto the reference trajectory and calculates the relative position of the projected state within the reference. This method requires d to be metric (i.e. to satisfy the triangle inequality). If d is not metric, state_to_trajectory() calculates the Euclidean distance within a transformed space generated through multidimensional scaling (Borg and Groenen, 2005). To use the state coordinates in a different metric space, use the coordStates argument. When the target_states cannot be projected onto any of the segments forming the reference trajectory, state_to_trajectory() returns NA for both distance and relative_position.

• "mixed" calculates the dissimilarity between the target_states and the reference trajectory, as well as their relative position by computing its projection onto any of the segments of the reference (analogous to method = "projection"). For the target_states that cannot be projected, state_to_trajectory() uses the nearest state in the reference to compute distance and relative_position (analogous to method = "nearest_state").

Value

The function state_to_trajectory() returns a data frame of four columns including the distance and relative_position between the target_state and the reference.

• Depending on the method, distance is calculated as the dissimilarity between the target_states and their respective nearest state in the reference or the dissimilarity to their projections onto the reference.

• The relative_position is a value that ranges between 0 (if the nearest state or projected point coincides with the first reference state) and 1 (if the nearest state or projected point coincides with the last reference state).

Author(s)

Martina Sánchez-Pinillos

Examples

# State dissimilarities
d <- vegan::vegdist(EDR_data$EDR3$abundance[, paste0("sp", 1:12)], method = "bray")
trajectories <- EDR_data$EDR3$abundance$traj
states <- EDR_data$EDR3$abundance$state

# Calculate the representative trajectories of an EDR to be used as reference
RT <- retra_edr(d,
               trajectories = trajectories,
               states = states,
               minSegs = 10)

# Define the target states
target_states <- as.integer(c(1, 16, 55))

# Calculate the position of the target states with respect to  the representative
# trajectories of an EDR
state_to_trajectory(d, trajectories = trajectories,
                    states = states,
                    target_states = target_states,
                    reference = RT,
                    method = "nearest_state")