## m_dist

Calculate the Mahalanobis distance for a multivariate time series

## Syntax

structure = m_dist(data,fs, smoothDur, overlap, consec, cumSum, expStart, expEnd, baselineStart, baselineEnd, BL_COV) % Matlab & Octave data_frame <- m_dist(data,fs, smoothDur, overlap, consec, cumSum, expStart, expEnd, baselineStart, baselineEnd, BL_COV) #R

## Description

This function is used to calculate the Mahalanobis distance for a multivariate time series.

## Inputs

Input var | Description | Units | Default value |
---|---|---|---|

data | A data frame or matrix with one row for each time point. Note that the Mahalanobis distance calculation should be carried out on continuous data only, so if your data contain logical, factor or character data, proceed at your own risk…errors (or at least meaningless results) will probably ensue. | N/A | N/A |

fs | The sampling rate in Hz (data should be regularly sampled). If not specified it will be assumed to be 1 Hz. | Hz | 1 |

smoothDur | The length, in minutes, of the window to use for calculation of “comparison” values. If not specified or zero, there will be no smoothing (a distance will be calculated for each data observation). | minutes | N/A |

overlap | The amount of overlap, in minutes, between consecutive “comparison” windows. smooth_dur - overlap will give the time resolution of the resulting distance time series. If not specified or zero, there will be no overlap. Overlap will also be set to zero if smoothDur is unspecified or zero. | minutes | 0 |

consec | Logical. If consec=true, then the calculated distances are between consecutive windows of duration smoothDur, sliding forward over the data set by a time step of (smoothDur-overlap) minutes. If TRUE, baselineStart and baselineEnd inputs will be used to define the period used to calculate the data covariance matrix. Default is consec=false. | N/A | FALSE |

cumSum | Logical. If cum_sum=true, then output will be the cumulative sum of the calculated distances, rather than the distances themselves. Default is cum_sum=false. | N/A | FALSE |

expStart | Start times (in seconds since start of the data set) of the experimental exposure period(s). | seconds | N/A |

expEnd | End times (in seconds since start of the data set) of the experimental exposure period(s). If either or both of exp_start and exp_end are missing, the distance will be calculated over whole dataset and full dataset will be assumed to be baseline. | seconds | N/A |

baselineStart | Start time (in seconds since start of the data set) of the baseline period (the mean data values for this period will be used as the 'control' to which all “comparison” data points (or windows) will be compared. if not specified, it will be assumed to be 0 (start of record). | seconds | 0 |

baselineEnd | End time (in seconds since start of the data set) of the baseline period. If not specified, the entire data set will be used (baseline_end will be the last sampled time-point in the data set). | seconds | N/A |

## Outputs

Output var | Description | Units |
---|---|---|

t | Times, in seconds since start of dataset, at which Mahalanobis distances are reported. If a smoothDur was applied, then the reported times will be the start times of each “comparison” window. | seconds |

dist | Mahalanobis distances between the specified baseline period and the specified “comparison” periods. | N/A |

## Example

### Matlab & Octave

The example below uses data from the file testset1.nc. You can download it from the animaltags website's example data sets. If the file is saved in your current working directory, load it via:

testset1 = load_nc(‘testset1.nc’)

structure = m_dist(testset1.A.data, testset1.A.sampling_rate,[],[],[],[],[],[],[],[],[])

### R

The example below uses data from the file testset1.nc. You can download it from the animaltags website's example data sets. If the file is saved in your current working directory, load it via:

testset1 <- load_nc(‘testset1.nc’)

dframe <- m_dist(data = testset1$A$data, fs = testset1$A$sampling_rate)

## About

bugs@animaltags.org Last modified: 10 May 2017