workflowImportance: Computes the contribution to dissimilarity of each variable.
In BlasBenito/distantia: Assessing Dissimilarity Between Multivariate Time Series

workflowImportance

R Documentation

Computes the contribution to dissimilarity of each variable.

Description

This workflow executes the following steps:

computes psi as done by workflowPsi.
computes psi as many times as numeric variables in sequences, removing one of them each time (jacknife analysis) to compute the relative contribution of each variable to overall dissimilarity.
Delivers an output of type "list" with two slots:
- psi a dataframe with the columns "A" and "B" with the respective names of the sequences compared, a column named "All variables" with the psi values of each pair of sequences computed by considering all variables, and then one column per variable, indicating the psi value when that variable is removed.
- psi.drop a dataframe with the columns "A" and "B", and then one column per numeric variable in sequences indicating the percentage of drop in psi (as indicated by the "All variables" column in the psi dataframe) when the given variable is removed. Positive values indicate that the given variable reduces dissimilarity when removed, making the sequences more similar, while negative values indicate that the variable increases dissimilarity when removed, making the sequences more different.

Usage

workflowImportance(
  sequences = NULL,
  grouping.column = NULL,
  time.column = NULL,
  exclude.columns = NULL,
  method = "manhattan",
  diagonal = FALSE,
  paired.samples = FALSE,
  same.time = FALSE,
  ignore.blocks = FALSE,
  parallel.execution = TRUE
  )

Arguments

`sequences`	dataframe with multiple sequences identified by a grouping column generated by `prepareSequences`.
`grouping.column`	character string, name of the column in `sequences` to be used to identify separates sequences within the file.
`time.column`	character string, name of the column with time/depth/rank data.
`exclude.columns`	character string or character vector with column names in `sequences` to be excluded from the analysis.
`method`	character string naming a distance metric. Valid entries are: "manhattan", "euclidean", "chi", and "hellinger". Invalid entries will throw an error.
`diagonal`	boolean, if `TRUE`, diagonals are included in the computation of the least cost path. Defaults to `FALSE`, as the original algorithm did not include diagonals in the computation of the least cost path.
`paired.samples`	boolean, if `TRUE`, the sequences are assumed to be aligned, and distances are computed for paired-samples only (no distance matrix required). Default value is `FALSE`.
`same.time`	boolean. If `TRUE`, samples in the sequences to compare will be tested to check if they have the same time/age/depth according to `time.column`. This argument is only useful when the user needs to compare two sequences taken at different sites but same time frames.
`ignore.blocks`	boolean. If `TRUE`, the function `leastCostPathNoBlocks` analyzes the least-cost path of the best solution, and removes blocks (straight-orthogonal sections of the least-cost path), which happen in highly dissimilar sections of the sequences, and inflate output psi values.
`parallel.execution`	boolean, if `TRUE` (default), execution is parallelized, and serialized if `FALSE`.

Details

If we consider the question "what variable contributes the most to the dissimilarity between two sequences?" the answer "the one dropping dissimilarity the most when excluded from the analysis" sounds like a reasonable answer. This workflow attempts to reach that answer by computing psi while removing one variable at a time.

Value

A list with two slots named psi and psi.drop. The former contains the dissimilarity values when removing each variable, while the latter contains the drop in dissimilarity (as a percentage of psi computed on all variables) that happens when each variable is removed. Positive values indicate that dissimilarity drops when the variable is removed, while negative values indicate that similarity drops when the variable is removed.