Version: 0.1-0
Date: 2015-10-08
Title: Subsample Temporal Data to Synchronal Events and Compute the MCI
Maintainer: Martin Rimmler <martin.rimmler@gmail.com>
Depends: R (≥ 3.1.0)
Description: The function 'syncSubsample' subsamples temporal data of different entities so that the result only contains synchronal events. The function 'mci' calculates the Movement Coordination Index (MCI, see reference on help page for function 'mci') of a data set created with the function 'syncSubsample'.
License: GPL-2
LazyData: true
Imports: utils
NeedsCompilation: no
Packaged: 2015-10-13 13:44:11 UTC; martin
Author: Martin Rimmler [aut, cre], Thomas Mueller [aut]
Repository: CRAN
Date/Publication: 2015-10-13 16:22:19

Subsample Temporal Data to Synchronal Events and Compute the MCI

Description

The function syncSubsample subsamples temporal data of different entities so that the result only contains synchronal events. The function mci calculates the Movement Coordination Index (MCI, see reference on help page for function mci) e.g. of a data set created with the function syncSubsample.

Details

Package: SyncMove
Type: Package
Version: 0.1-0
Date: 2015-10-08
License: GLP-2

Author(s)

Martin Rimmler (maintainer, martin.rimmler[AT]gmail.com), Thomas Mueller

References

Mueller, T., et al. (2011) How landscape dynamics link individual- to population-level movement patterns: a multispecies comparison of ungulate relocation data, Global Ecology and Biogeography, 20, pages 683–694.

Relocations of Mongolian Gazelles

Description

Data set of GPS tracked relocations of gazelles in the Mongolian steppe. For more information contact Thomas Mueller (e-mail address see below).

Usage

gazelleRelocations

Format

Data frame with columns id, sex, time, x and y.

Source

Mueller, T. (2015), muellert[AT]gmail.com

Movement Coordination Index (MCI)

Description

Computes the Movement Coordination Index as described in Mueller, T., et al. (2011).

Usage

mci(x)

Arguments

x

data frame of synchronized relocations of a set of individuals. The data frame must containing the following columns:

syncID: numeric (integer), ID marking the synchronization event. For each synchronization event every individual must have a record. Therefore each ID must appear as often as every other ID (e.g. not c(1,1,1,2,2,3,3,3) but c(1,1,1,2,2,2,3,3,3)).

utm.easting: numeric, planar x coordinate. Although the name indicates UTM coordinates other planar coordinate systems are also allowed.

utm.northing: analogue to utm.easting

(Further columns are allowed, but will be ignored. Usually a column naming the individual is present in the data frame.)

Such a data frame is returned by the function syncSubsample in package SyncMove (<output>$data[[i]]) with the argument ‘completeSyncsOnly’ set to TRUE.

Value

Returns a numeric vector of MCI values, one for each pair of subsequent synchronization events.

Author(s)

Martin Rimmler (maintainer, martin.rimmler[AT]gmail.com), Thomas Mueller

References

Mueller, T., et al. (2011) How landscape dynamics link individual- to population-level movement patterns: a multispecies comparison of ungulate relocation data, Global Ecology and Biogeography, 20, pages 683–694.

Examples

    # load example data
    data(gazelleRelocations) 

    # create input data frame
    syncRelocs <- syncSubsample(x = gazelleRelocations,
                                startSearch = "2007-09-05 00:00:00",
                                syncIntervalSecs = 3600*24*16,
                                syncAccuracySecs = 3600*24) 

    # calculate MCI
    mci(syncRelocs$data[[1]])

Subsamples Temporal Data to Synchronal Events

Description

Subsamples temporal records of different entities to a data set which only includes records that occur at predefined and equally spaced synchronization events. A subsample is created for each possible combination of entities (unless restricted by argument minEntities, maxEntities or mustEntities).

Usage

    syncSubsample(
        x,
        startSearch = min(as.character(x$study.local.timestamp)),
        endSearch = max(as.character(x$study.local.timestamp)),
        syncIntervalSecs = 3600,
        syncAccuracySecs = 60,
        minEntities = 2,
        maxEntities = length(unique(x$individual.local.identifier)),
        mustEntities = NULL,
        completeSyncsOnly = TRUE,
        fast = TRUE
    )

Arguments

x

a data frame with the following columns (further columns are allowed, but will be ignored):

individual.local.identifier: character, entity ID

study.local.timestamp: character, time of format "YYYY-MM-DD HH:MM:SS"

Such a data frame can be created by importing data from www.movebank.org.

If the output is to be processed with function mci the data frame must also contain the following columns:

utm.easting: numeric, planar x coordinate. Although the name indicates UTM coordinates other planar coordinate systems are also allowed.

utm.northing: analogue to utm.easting

startSearch

character, time of format "YYYY-MM-DD HH:MM:SS" as the start time for the creation of synchronization events. Default is the minimum timestamp in the data.

endSearch

analogue to startSearch.

syncIntervalSecs

numeric, interval between synchronization events in seconds. (e.g., 60*60*24*3 defines a three day interval)

syncAccuracySecs

numeric, accuracy for synchronization events in seconds. (e.g., 60*60*2 defines a two hour accuracy)

minEntities

numeric, minimum number of entities to be included in the synchronization events.

maxEntities

analogue to minEntities

mustEntities

character, vector of IDs of entities which have to be included in the synchronization events.

completeSyncsOnly

boolean, if TRUE (default) only events will appear in the output where each entity of a given combination of entities has a record. If FALSE also events with no records for some entities will appear in the output.

fast

boolean, if TRUE (default) synchronized subsamples are created only for those combinations of entities that seem to be the most prominent in the input data. If FALSE synchronized subsamples are created for all combinations of entities in the input data. See details.

Details

The synchronization events are created with a start time as the first synchronization event (argument startSearch) and an interval between following synchronization events. Each synchronization event has an accuracy. All records of a given combination of entities which fall into synchronization events + - accuracy are selected for the subsample. If there is more than one record for an entity in a synchronization event + - accuracy the record that is closest to the synchronization event is selected. The arguments startSearch, syncIntervalSecs and syncAccuracySecs must be chosen with respect to the input data in order to get good synchronization results.

Running the function with fast = FALSE one can find the combination of entities with the maximum number of synchronization events. However, an input data set with more then 8 to 10 entities should be processed with fast = TRUE. Otherwise the calculations can take a long time. (For input data with 10 entities there are more than 1000 possible combinations of entities.)

The synchronization events are numbered from 1 to n. These numbers are referred to as sync IDs. If no records are present at a given synchronization event the ID for this event will not appear in the output subsample. Thus the sync IDs in the subsample show if subsequent pairs of synchronized events exist (e.g., sync ID 1 and 2, sync ID 2 and 3, ...). Such pairs can be used to calculate the Movement Coordination Index, see function mci.

Value

List, returns a list with 3 elements named overview, data, and entities.

overview

An overview of the synchronized subsamples for all possible combinations of entities. Each row refers to the respective element in the data and entities lists (see below). E.g., for the data described in row 1 see <output>$data[[1]] and <output>$entities[[1]]. The overview table contains the following columns:

numberOfEntities: the number of entities used for creating the subsample

numberOfSyncs: number of synchronized events in the subsample

numberOfSubsequentSyncs: number subsequent synchronized events (see details)

firstEvent: time of first synchronization event

lastEvent: analogue to lastEvent

syncIntervalSecs: interval used for creating the synchronization events

syncAccuracySecs: accuracy of the synchronization events

data

A list containing the subsampled data described in the overview. The subsamples have the same columns as the input data set plus the additional columns syncTime and syncID for the time and ID of the synchronization events respectively.

entities

A list containing the entity combinations used for creating the synchronized subsamples.

Author(s)

Martin Rimmler (maintainer, martin.rimmler[AT]gmail.com), Thomas Mueller

Examples

    # load example data
    data(gazelleRelocations)

    # subsample sychronal events
    syncRelocs <- syncSubsample(x = gazelleRelocations,
                                startSearch = "2007-09-05 00:00:00",
                                syncIntervalSecs = 3600*24*16,
                                syncAccuracySecs = 3600*24)

    # show results overview
    syncRelocs$overview

    # show first subsample
    syncRelocs$data[[1]]

    # show entities of first subsample
    syncRelocs$entities[[1]]