syncSubsample: Subsamples Temporal Data to Synchronal Events

Description Usage Arguments Details Value Author(s) Examples

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    # 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]]

Example output

  numberOfEntities numberOfSyncs numberOfSubsequentSyncs          firstEvent
1                3            20                      19 2007-09-21 00:00:00
2                2            21                      20 2007-09-05 00:00:00
            lastEvent syncIntervalSecs syncAccuracySecs
1 2008-07-21 00:00:00          1382400            86400
2 2008-07-21 00:00:00          1382400            86400
     individual.local.identifier    sex study.local.timestamp utm.easting
296                      602189A female   2007-09-21 00:01:06    868.6244
1017                     602190A female   2007-09-21 00:00:36    773.6690
1703                     602191A female   2007-09-21 00:01:05    917.1640
325                      602189A female   2007-10-07 00:01:36    990.8651
1042                     602190A female   2007-10-07 00:01:23    755.7416
1732                     602191A female   2007-10-07 00:01:23    903.9009
354                      602189A female   2007-10-23 00:01:06   1024.8414
1071                     602190A female   2007-10-23 00:00:37    752.4900
1761                     602191A female   2007-10-23 00:00:37    924.2670
382                      602189A female   2007-11-08 00:01:07   1026.5730
1100                     602190A female   2007-11-08 00:00:37    753.5425
1790                     602191A female   2007-11-08 00:00:36    899.7673
411                      602189A female   2007-11-24 00:02:55   1003.2585
1129                     602190A female   2007-11-24 00:00:37    797.3807
1819                     602191A female   2007-11-24 00:00:37    903.8494
440                      602189A female   2007-12-10 00:01:25    920.8909
1158                     602190A female   2007-12-10 00:00:37    762.9527
1848                     602191A female   2007-12-10 00:00:37    900.1156
469                      602189A female   2007-12-26 00:01:06    919.5677
1187                     602190A female   2007-12-26 00:00:36    762.9914
1877                     602191A female   2007-12-26 00:00:54    851.4206
498                      602189A female   2008-01-11 00:01:59    920.2279
1216                     602190A female   2008-01-11 00:00:36    865.5521
1906                     602191A female   2008-01-11 00:00:36    870.9232
527                      602189A female   2008-01-27 00:01:24    928.8176
1241                     602190A female   2008-01-27 00:00:54    874.1118
1934                     602191A female   2008-01-27 00:00:55    870.2210
556                      602189A female   2008-02-12 00:01:24    921.2901
1270                     602190A female   2008-02-12 00:00:37    858.0300
1963                     602191A female   2008-02-12 00:00:36    871.7373
584                      602189A female   2008-02-28 00:01:36    929.5734
1298                     602190A female   2008-02-28 00:00:36    848.4739
1991                     602191A female   2008-02-28 00:00:36    876.9959
613                      602189A female   2008-03-15 00:01:07    855.4991
1327                     602190A female   2008-03-15 00:00:37    815.5586
2020                     602191A female   2008-03-15 00:00:38    845.2368
642                      602189A female   2008-03-31 00:01:07    853.9082
1356                     602190A female   2008-03-31 00:00:36    791.4997
2049                     602191A female   2008-03-31 00:00:36    841.0786
671                      602189A female   2008-04-16 00:01:06    855.0381
1385                     602190A female   2008-04-16 00:00:37    775.0580
2078                     602191A female   2008-04-16 00:00:37    783.5925
700                      602189A female   2008-05-02 00:01:07    864.9775
1414                     602190A female   2008-05-02 00:00:37    783.6780
2107                     602191A female   2008-05-02 00:00:36    770.5648
729                      602189A female   2008-05-18 00:01:06    806.0905
1443                     602190A female   2008-05-18 00:00:55    751.4969
2136                     602191A female   2008-05-18 00:00:55    731.4883
758                      602189A female   2008-06-03 00:01:36    726.9916
1472                     602190A female   2008-06-03 00:01:06    754.8515
2165                     602191A female   2008-06-03 00:00:37    732.2616
787                      602189A female   2008-06-19 00:01:30    739.4487
1501                     602190A female   2008-06-19 00:00:36    717.0156
2193                     602191A female   2008-06-19 00:00:37    739.1495
816                      602189A female   2008-07-05 00:01:06    739.9709
1529                     602190A female   2008-07-05 00:00:36    725.1178
2222                     602191A female   2008-07-05 00:00:36    833.6769
845                      602189A female   2008-07-21 00:01:06    705.9033
1558                     602190A female   2008-07-21 00:02:54    765.6336
2249                     602191A female   2008-07-21 00:00:36    827.8880
     utm.northing            syncTime syncID
296     8.4769285 2007-09-21 00:00:00      2
1017   99.7631819 2007-09-21 00:00:00      2
1703    1.1800951 2007-09-21 00:00:00      2
325   -23.7448037 2007-10-07 00:00:00      3
1042   77.1102179 2007-10-07 00:00:00      3
1732  -21.2891750 2007-10-07 00:00:00      3
354     0.4283062 2007-10-23 00:00:00      4
1071   37.1992453 2007-10-23 00:00:00      4
1761   -2.6430089 2007-10-23 00:00:00      4
382    -5.7979426 2007-11-08 00:00:00      5
1100   65.0410094 2007-11-08 00:00:00      5
1790   54.0532827 2007-11-08 00:00:00      5
411   -29.2462839 2007-11-24 00:00:00      6
1129    7.4197984 2007-11-24 00:00:00      6
1819   -5.2550889 2007-11-24 00:00:00      6
440   -28.5854525 2007-12-10 00:00:00      7
1158   44.8249933 2007-12-10 00:00:00      7
1848   18.2143795 2007-12-10 00:00:00      7
469   -25.3032006 2007-12-26 00:00:00      8
1187   47.6699155 2007-12-26 00:00:00      8
1877   46.6907330 2007-12-26 00:00:00      8
498   -29.5446199 2008-01-11 00:00:00      9
1216   45.0077978 2008-01-11 00:00:00      9
1906   51.0186619 2008-01-11 00:00:00      9
527    75.0626745 2008-01-27 00:00:00     10
1241   40.9828750 2008-01-27 00:00:00     10
1934    8.6134759 2008-01-27 00:00:00     10
556    96.6658472 2008-02-12 00:00:00     11
1270   59.3454940 2008-02-12 00:00:00     11
1963   16.6419720 2008-02-12 00:00:00     11
584    95.0585246 2008-02-28 00:00:00     12
1298   56.8100273 2008-02-28 00:00:00     12
1991   16.7781858 2008-02-28 00:00:00     12
613   121.1242833 2008-03-15 00:00:00     13
1327   91.4343483 2008-03-15 00:00:00     13
2020   42.1241798 2008-03-15 00:00:00     13
642   120.2420628 2008-03-31 00:00:00     14
1356   96.9159246 2008-03-31 00:00:00     14
2049   29.4148220 2008-03-31 00:00:00     14
671   139.9985102 2008-04-16 00:00:00     15
1385  118.7530515 2008-04-16 00:00:00     15
2078   45.8216335 2008-04-16 00:00:00     15
700   127.7193656 2008-05-02 00:00:00     16
1414  106.8296195 2008-05-02 00:00:00     16
2107   48.4988737 2008-05-02 00:00:00     16
729   123.5455528 2008-05-18 00:00:00     17
1443   94.7381720 2008-05-18 00:00:00     17
2136   94.4009178 2008-05-18 00:00:00     17
758   121.4424120 2008-06-03 00:00:00     18
1472   81.3692060 2008-06-03 00:00:00     18
2165  105.5935767 2008-06-03 00:00:00     18
787   110.5419733 2008-06-19 00:00:00     19
1501  107.4216213 2008-06-19 00:00:00     19
2193  112.4938891 2008-06-19 00:00:00     19
816   112.5189079 2008-07-05 00:00:00     20
1529  109.6719842 2008-07-05 00:00:00     20
2222   56.9699256 2008-07-05 00:00:00     20
845   120.1732331 2008-07-21 00:00:00     21
1558   61.0669027 2008-07-21 00:00:00     21
2249   60.0322339 2008-07-21 00:00:00     21
[1] "602189A" "602190A" "602191A"

SyncMove documentation built on May 2, 2019, 9:58 a.m.