movements: Calculate movements
In SNMA: Stream Network Movement Analyses
movements R Documentation
Calculate movements
Description
Calculate movements in a stream network for multiple individuals
Usage
movements(
data = NULL,
space.use = TRUE,
from.previous = TRUE,
cumulative = TRUE,
downstream.node = NULL,
coords,
lon.name = "lon",
lat.name = "lat",
id.name = "id",
date.time.name = NULL
)
Arguments
data
(list) Output from prep.data.
space.use
(logical) If TRUE (default), total space use (range) will be calculated up to and including each point
from.previous
(logical) If TRUE (default), the distance from the previous point will be calculated.
cumulative
(logical) If TRUE (default), the cumulative distance moved up to and including each point will be calculated.
downstream.node
(integer) The ID (number) of the node representing the furthest point downstream in your network (the root). If included, the distance from that point and the direction of movement (upstream or downstream) will be calculated per point.
coords
(data.frame) Data frame containing coordinates for animal locations. At a minimum, it must include a column of animal IDs and columns of latitude and longitude (in decimal degrees projected to the same system as the rest of the data). It can optionally include a date.time column (highly recommended) containing the date and time of each point (in POSIX format). If the date.time column is present, the data will be sorted by that. Otherwise, ensure the data are sorted from oldest to newest. Other columns of metadata can be included and will be returned.
lon.name
(character) For the coords object, the name of the column of longitudes (in quotes). Default = "lon"
lat.name
(character) For the coords object, the name of the column of latitudes (in quotes). Default = "lat"
id.name
(character) For the coords object, the name of the column of animal identities (in quotes). Default = "id"
date.time.name
(character: optional) For the coords object, the name of the column of dates and times (in a POSIX format). If included, the data will be sorted from oldest to newest (otherwise sort before running), and the time difference between consecutive points will be returned. Default = NULL
Details
It takes a data frame of coordinates and calculates the specified summary statistics for each individual. All results are in meters. Input data should be sorted from oldest point to newest, unless a date.time column is included, in which case the sorting will be done internally.
space.use If TRUE, for each point, it will calculate the total space use up to and including the given point. This includes all branches of the network covered by the points, but no portion is measured more than once. It is simply the total area of the stream (expressed as linear meters) visited by the animal. Note that there may occasionally be a very slight difference between this metric and the other metrics when they describe the same space. This is caused by a slight misalignment between a node and the end of a segment, but usually will be trivial.
from.previous If TRUE, for each point, it calculates the distance between that point and the previous point (following the stream network). This calculation is required for the cummualtive calculations and outputs will be returned anytime cummualtive == T, even if from.previous == F.
cumulative If TRUE, for each point, it calculates the total distance moved up to and including that point. This differs from space.use because stretches of river get included each time they are visited, so the cumulative distance increases anytime the animal moves.
downstream.node If this is included, for each point, it calculates the current distance from the point furthest downstream. This can be a useful way to visualize movements over time by referencing a fixed point (the furthest downstream). It also returns a column showing the direction of movement. Keep in mind that on branched rivers, these results may be somewhat misleading. If, for example, a stream forks 10 m upstream, and an animal moves from 5 m up the right fork then backtracks on goes 6 m up the left fork, the distances from the furthest downstream point will be 15 and 16 (respectively) even though the animal moved 5 m downstream the left fork before moving 6 m up the other. Likewise, the direction would be scored as "upstream" even though it first moved downstream. The direction is based simply on whether the shortest distance to the furthest downstream point increased or decreased.
Note: This function does not incorporate the amount of time between points. Bear that in mind when interpreting data collected over uneven time intervals.
Example: If an individual starts 100 meters upstream from the furthest downstream point in your network and moves 10 m upstream from day 1 to 2, another 5 m upstream from day 2 to 3, then 4 m downstream from day 3 to 4, then doesn't move between days 4 and 5, it will return the following:
space.use dist.from.prev cumulative.dist dist.from.downstream direction
NA NA NA 100 NA
10 10 10 110 upstream
15 5 15 115 upstream
15 4 19 111 downstream
15 0 19 111 no.change
The first row is NA in most cases because there are no previous points to make comparisons. The dist.from.prev column is simply the distances described in the example. The space.use column shows increasing total space use over time. Notice that it does not change on days 4 and 5 because the animal visits areas where it had already been recorded. In contrast, the cumulative.dist increased on day 4 because it is simply the sum of all distances. Most values remained the same on the last day because there was no movement (as reflected by the dist.from.prev and direction columns).
Value
Data frame including all original columns, plus a columns of summary data. Column order may have changed. All measurements are in linear meters.
Column space.use = result of space.use = TRUE
Column dist.from.prev = result of from.previous = TRUE
Column cumulative.dist = result of cumulative = TRUE
Column dist.from.downstream = result of downstream.node
Column direction = result of downstream.node (direction)
Column time.diff = returned if a date.time column is included. Shows the elapsed time (in hours) between consecutive points
Examples
data(stream.line)
data(nodes)
data(animal.points)
network.20 <- prep.data(
l = stream.line,
freq = 20,
nodes = nodes,
lon.name = "lon",
lat.name = "lat",
node.name = "id"
)
move.results <- movements(data=network.20,
space.use=TRUE,
from.previous=TRUE,
cumulative=TRUE,
downstream.node=1,
coords=animal.points,
lon.name="lon.raw",
lat.name="lat.raw",
id.name="id",
date.time.name="date.time")
SNMA documentation built on Aug. 27, 2026, 1:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| movements | R Documentation |
Calculate movements
Description
Calculate movements in a stream network for multiple individuals
Usage
movements(
data = NULL,
space.use = TRUE,
from.previous = TRUE,
cumulative = TRUE,
downstream.node = NULL,
coords,
lon.name = "lon",
lat.name = "lat",
id.name = "id",
date.time.name = NULL
)
Arguments
data |
(list) Output from |
space.use |
(logical) If |
from.previous |
(logical) If |
cumulative |
(logical) If |
downstream.node |
(integer) The ID (number) of the node representing the furthest point downstream in your network (the root). If included, the distance from that point and the direction of movement (upstream or downstream) will be calculated per point. |
coords |
(data.frame) Data frame containing coordinates for animal locations. At a minimum, it must include a column of animal IDs and columns of latitude and longitude (in decimal degrees projected to the same system as the rest of the data). It can optionally include a date.time column (highly recommended) containing the date and time of each point (in POSIX format). If the date.time column is present, the data will be sorted by that. Otherwise, ensure the data are sorted from oldest to newest. Other columns of metadata can be included and will be returned. |
lon.name |
(character) For the |
lat.name |
(character) For the |
id.name |
(character) For the |
date.time.name |
(character: optional) For the |
Details
It takes a data frame of coordinates and calculates the specified summary statistics for each individual. All results are in meters. Input data should be sorted from oldest point to newest, unless a date.time column is included, in which case the sorting will be done internally.
space.use If TRUE, for each point, it will calculate the total space use up to and including the given point. This includes all branches of the network covered by the points, but no portion is measured more than once. It is simply the total area of the stream (expressed as linear meters) visited by the animal. Note that there may occasionally be a very slight difference between this metric and the other metrics when they describe the same space. This is caused by a slight misalignment between a node and the end of a segment, but usually will be trivial.
from.previous If TRUE, for each point, it calculates the distance between that point and the previous point (following the stream network). This calculation is required for the cummualtive calculations and outputs will be returned anytime cummualtive == T, even if from.previous == F.
cumulative If TRUE, for each point, it calculates the total distance moved up to and including that point. This differs from space.use because stretches of river get included each time they are visited, so the cumulative distance increases anytime the animal moves.
downstream.node If this is included, for each point, it calculates the current distance from the point furthest downstream. This can be a useful way to visualize movements over time by referencing a fixed point (the furthest downstream). It also returns a column showing the direction of movement. Keep in mind that on branched rivers, these results may be somewhat misleading. If, for example, a stream forks 10 m upstream, and an animal moves from 5 m up the right fork then backtracks on goes 6 m up the left fork, the distances from the furthest downstream point will be 15 and 16 (respectively) even though the animal moved 5 m downstream the left fork before moving 6 m up the other. Likewise, the direction would be scored as "upstream" even though it first moved downstream. The direction is based simply on whether the shortest distance to the furthest downstream point increased or decreased.
Note: This function does not incorporate the amount of time between points. Bear that in mind when interpreting data collected over uneven time intervals.
Example: If an individual starts 100 meters upstream from the furthest downstream point in your network and moves 10 m upstream from day 1 to 2, another 5 m upstream from day 2 to 3, then 4 m downstream from day 3 to 4, then doesn't move between days 4 and 5, it will return the following:
| space.use | dist.from.prev | cumulative.dist | dist.from.downstream | direction |
| NA | NA | NA | 100 | NA |
| 10 | 10 | 10 | 110 | upstream |
| 15 | 5 | 15 | 115 | upstream |
| 15 | 4 | 19 | 111 | downstream |
| 15 | 0 | 19 | 111 | no.change |
The first row is NA in most cases because there are no previous points to make comparisons. The dist.from.prev column is simply the distances described in the example. The space.use column shows increasing total space use over time. Notice that it does not change on days 4 and 5 because the animal visits areas where it had already been recorded. In contrast, the cumulative.dist increased on day 4 because it is simply the sum of all distances. Most values remained the same on the last day because there was no movement (as reflected by the dist.from.prev and direction columns).
Value
Data frame including all original columns, plus a columns of summary data. Column order may have changed. All measurements are in linear meters.
Column space.use = result of space.use = TRUE
Column dist.from.prev = result of from.previous = TRUE
Column cumulative.dist = result of cumulative = TRUE
Column dist.from.downstream = result of downstream.node
Column direction = result of downstream.node (direction)
Column time.diff = returned if a date.time column is included. Shows the elapsed time (in hours) between consecutive points
Examples
data(stream.line)
data(nodes)
data(animal.points)
network.20 <- prep.data(
l = stream.line,
freq = 20,
nodes = nodes,
lon.name = "lon",
lat.name = "lat",
node.name = "id"
)
move.results <- movements(data=network.20,
space.use=TRUE,
from.previous=TRUE,
cumulative=TRUE,
downstream.node=1,
coords=animal.points,
lon.name="lon.raw",
lat.name="lat.raw",
id.name="id",
date.time.name="date.time")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.