,
Namrata Banerji [ctb]| Title: | Leadership-Inference Framework for Multivariate Time Series |
|---|---|
| Description: | A leadership-inference framework for multivariate time series. The framework for multiple-faction-leadership inference from coordinated activities or 'mFLICA' uses a notion of a leader as an individual who initiates collective patterns that everyone in a group follows. Given a set of time series of individual activities, our goal is to identify periods of coordinated activity, find factions of coordination if more than one exist, as well as identify leaders of each faction. For each time step, the framework infers following relations between individual time series, then identifying a leader of each faction whom many individuals follow but it follows no one. A faction is defined as a group of individuals that everyone follows the same leader. 'mFLICA' reports following relations, leaders of factions, and members of each faction for each time step. Please see Chainarong Amornbunchornvej and Tanya Berger-Wolf (2018) <doi:10.1137/1.9781611975321.62> for methodology and Chainarong Amornbunchornvej (2021) <doi:10.1016/j.softx.2021.100781> for software when referring to this package in publications. |
| Authors: | Chainarong Amornbunchornvej [aut, cre]
,
Namrata Banerji [ctb] |
| Maintainer: | Chainarong Amornbunchornvej <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.6 |
| Built: | 2025-03-08 04:34:07 UTC |
| Source: | https://github.com/darkeyes/mflica |
followingNetwork is a support function for calculating a following network of a set of time series
followingNetwork(TS, timeLagWindow, lagWindow = 0.1, sigma = 0.1)followingNetwork(TS, timeLagWindow, lagWindow = 0.1, sigma = 0.1)
TS |
is a set of time series where |
timeLagWindow |
is a maximum possible time delay in the term of time steps. |
lagWindow |
is a maximum possible time delay in the term of percentage of time length of |
sigma |
is a threshold of following relation. It is used to discretize an adjacency matrix |
This function returns adjacency matrices of a following network of TS.
adjWeightedMat |
An adjacency matrix of a following network
s.t. if |
adjBinMat |
A binary version of |
# Run the function ? out<-followingNetwork(TS=mFLICA::TS[,60:90,],sigma=0.5)# Run the function ? out<-followingNetwork(TS=mFLICA::TS[,60:90,],sigma=0.5)
03/24/2021: Chai's code rewritten by Namrata to replicate Matlab version The changes are in the DTW function, which is implemented here as DTW2 instead of the one in the R package DTW
followingRelation is a function that infers whether Y follows X.
followingRelation(Y, X, timeLagWindow, lagWindow = 0.1)followingRelation(Y, X, timeLagWindow, lagWindow = 0.1)
Y |
is a T-by-D matrix of numerical time series of a follower |
X |
is a T-by-D matrix numerical time series of a leader |
timeLagWindow |
is a maximum possible time delay in the term of time steps. |
lagWindow |
is a maximum possible time delay in the term of percentage of length(X).
If |
This function returns a list of following relation variables below.
follVal |
is a following-relation value s.t. if |
dtwIndexVec |
is a numeric vector of index-warping difference: dtwIndexVec[k] = dtwOut$index1[k] - dtwOut$index2[k] where dtwOut is the output from dtw::dtw(x=Y,y=X) function. |
# Load example data ??? leader<- mFLICA::TS[1,1:200,] follower<- mFLICA::TS[2,1:200,] # Run the function out<-followingRelation(Y=follower,X=leader)# Load example data ??? leader<- mFLICA::TS[1,1:200,] follower<- mFLICA::TS[2,1:200,] # Run the function out<-followingRelation(Y=follower,X=leader)
getADJNetDen is a support function for calculating a network density of a network.
getADJNetDen(adjMat)getADJNetDen(adjMat)
adjMat |
is an adjacency matrix of a dominant-distribution network. |
This function returns a value of network density of of a network for a given adjMat.
# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE # Get a network density of an adjacency matrix getADJNetDen(adjMat=A)# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE # Get a network density of an adjacency matrix getADJNetDen(adjMat=A)
getDynamicFollNet is a support function for calculating a dynamic following network of a set of time series
getDynamicFollNet( TS, timeWindow, timeShift, sigma = 0.5, lagWindow = 0.1, silentFlag = FALSE )getDynamicFollNet( TS, timeWindow, timeShift, sigma = 0.5, lagWindow = 0.1, silentFlag = FALSE )
TS |
is a set of time series where |
timeWindow |
is a time window parameter that limits a length of each sliding window. The default is 10 percent of time series length. |
timeShift |
is a number of time steps a sliding window shifts from a previous window to the next one. The default is 10 percent of |
sigma |
is a threshold of following relation. The default is 0.5. |
lagWindow |
is a maximum possible time delay in the term of percentage of time length of |
silentFlag |
is a flag that prohibit the function to print the current status of process. |
This function returns adjacency matrices of a dynamic following network of TS as well as the corresponding time series of network densities.
dyNetWeightedMat |
An adjacency matrix of a dynamic following network
s.t. if |
dyNetBinMat |
A binary version of |
dyNetWeightedDensityVec |
A time series of dynamic network densities of |
dyNetBinDensityVec |
A time series of dynamic network densities of |
# Run the function out<-getDynamicFollNet(TS=mFLICA::TS[,1:10,],timeWindow=5,timeShift = 5,sigma=0.5)# Run the function out<-getDynamicFollNet(TS=mFLICA::TS[,1:10,],timeWindow=5,timeShift = 5,sigma=0.5)
getFactions is a support function for inferring faction leaders and their members as well as a faction size ratio of each faction. Leaders are nodes that have zero outgoing degree. Members of leader A's faction are nodes that have some directed path to A in a following network.
getFactions(adjMat)getFactions(adjMat)
adjMat |
is an adjacency matrix of a following network. |
This function returns a list of leader IDs, a list of faction members, and network densities of factions.
leaders |
is a list of faction leader IDs |
factionMembers |
is a list of members of factions where |
factionSizeRatio |
is a vector of faction size ratio of each faction.
|
# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE A[5,3]<-TRUE # Get faction leaders and their members as well as a network density of each faction. out<-getFactions(adjMat=A)# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE A[5,3]<-TRUE # Get faction leaders and their members as well as a network density of each faction. out<-getFactions(adjMat=A)
getFactionSizeRatio is a support function for calculating a faction size ratio of a given faction. A faction size ratio is a number of edges that connect between faction-member nodes divided by a number of total nodes within a following network.
getFactionSizeRatio(adjMat, members)getFactionSizeRatio(adjMat, members)
adjMat |
is an adjacency matrix of a dominant-distribution network. |
members |
is a list of member IDs of a given faction. |
This function returns a faction size ratio of a given faction.
# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE # Get a faction size ratio of a given faction getFactionSizeRatio(adjMat=A,members=c(1,2,3,4))# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE # Get a faction size ratio of a given faction getFactionSizeRatio(adjMat=A,members=c(1,2,3,4))
getReachableNodes is a support function for inferring reachable nodes that have some directed path to a node targetNode.
This function uses Breadth-first search (BFS) algorithm.
getReachableNodes(adjMat, targetNode)getReachableNodes(adjMat, targetNode)
adjMat |
is an adjacency matrix of a following network of which its elements are binary: zero for no edge, and one for having an edge. |
targetNode |
is a node in a graph that we want to find a set of nodes that can reach this target node via some paths. |
This function returns a set of node IDs followers that have some directed path to a node targetNode.
# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE A[5,3]<-TRUE # Get a set of reachable nodes of targetNode. followers<-getReachableNodes(adjMat=A,targetNode=1)$followers# Given an example of adjacency matrix A<-matrix(FALSE,5,5) A[2,1]<-TRUE A[c(3,4),2]<-TRUE A[5,3]<-TRUE # Get a set of reachable nodes of targetNode. followers<-getReachableNodes(adjMat=A,targetNode=1)$followers
A leadership-inference framework for multivariate time series. The framework uses a notion of a leader as an individual who initiates collective patterns that everyone in a group follows. Given a set of time series of individual activities, our goal is to identify periods of coordinated activity, find factions of coordination if more than one exist, as well as identify leaders of each faction. For each time step, the framework infers following relations between individual time series, then identifying a leader of each faction whom many individuals follow but it follows no one. A faction is defined as a group of individuals that everyone follows the same leader. mFLICA reports following relations, leaders of factions, and members of each faction for each time step. Please see Chainarong Amornbunchornvej and Tanya Berger-Wolf (2018) <doi:10.1137/1.9781611975321.62> when referring to this package in publications.
mFLICA( TS, timeWindow, timeShift, lagWindow = 0.1, sigma = 0.5, silentFlag = FALSE )mFLICA( TS, timeWindow, timeShift, lagWindow = 0.1, sigma = 0.5, silentFlag = FALSE )
TS |
is a set of time series where |
timeWindow |
is a time window parameter that limits a length of each sliding window. The default is 10 percent of time series length. |
timeShift |
is a number of time steps a sliding window shifts from a previous window to the next one. The default is 10 percent of |
lagWindow |
is a maximum possible time delay in the term of percentage of time length of |
sigma |
is a threshold of following relation. The default is 0.5. Note that if |
silentFlag |
is a flag that prohibit the function to print the current status of process. |
This function returns dynamic following networks, as well as leaders of factions, and members of each faction for each time step.
dyNetOut$dyNetWeightedMat |
An adjacency matrix of a dynamic following network
s.t. if |
dyNetOut$dyNetBinMat |
A binary version of |
dyNetOut$dyNetWeightedDensityVec |
A time series of dynamic network densities of |
dyNetOut$dyNetBinDensityVec |
A time series of dynamic network densities of |
leadersTimeSeries |
A time series of leaders of each faction where |
factionMembersTimeSeries |
A time series of sets of faction members where |
factionSizeRatioTimeSeries |
A time series of faction-size ratios of all individuals. A faction size ratio is a number of edges that connect between faction-member nodes divided by a number of total nodes within a following network. If a leader has a higher faction-size ratio, then it has more followers than a leader with a lower faction-size ratio. A faction-size ratio has a value between 0 and 1. |
Chainarong Amornbunchornvej, [email protected]
# Run the function obj1<-mFLICA(TS=mFLICA::TS[,60:90,],timeWindow=10,timeShift=10,sigma=0.5) # Plot time series of faction size ratios of all leaders plotMultipleTimeSeries(TS=obj1$factionSizeRatioTimeSeries, strTitle="Faction Size Ratios")# Run the function obj1<-mFLICA(TS=mFLICA::TS[,60:90,],timeWindow=10,timeShift=10,sigma=0.5) # Plot time series of faction size ratios of all leaders plotMultipleTimeSeries(TS=obj1$factionSizeRatioTimeSeries, strTitle="Faction Size Ratios")
plotMultipleTimeSeries is a function for visualizing time series
plotMultipleTimeSeries(TS, strTitle = "Time Series Plot", TSnames)plotMultipleTimeSeries(TS, strTitle = "Time Series Plot", TSnames)
TS |
is a set of time series where |
strTitle |
is a string of the plot title |
TSnames |
is a list of legend of |
This function returns an object of ggplot class.
# Run the function plotMultipleTimeSeries(TS=mFLICA::TS[1:5,1:60,1])# Run the function plotMultipleTimeSeries(TS=mFLICA::TS[1:5,1:60,1])
A dataset containing simulated trajectories of 30 individuals moving to form coordination in x-y coordinates. In the interval [1,200], ID1 leads the group and everyone follows. ID2 leads the group during the interval [201,400]. Lastly, ID3 leads the group during the interval [401,600]. The interval [601,800] is the time when everyone trying to stop moving.
TSTS
An array with 30 rows of individuals, 800 columns of time steps, and 2 dimensions of coordinate (x,y):
It is a set of time series where TS[i,t,d] is a numeric value of ith time series at time t and dimension d.
...
TSNANNearestNeighborPropagation is a function that fills NA values with nearest real values in the past ( or future if the first position of time series is NA), for time series X.
TSNANNearestNeighborPropagation(X)TSNANNearestNeighborPropagation(X)
X |
is a T-by-D matrix numerical time series |
This function returns a list of following relation variables below.
Xout |
is a T-by-D matrix numerical time series that all NAN have been filled with nearest real values. |
# Load example data z<-1:20 z[2:5]<-NA z<-TSNANNearestNeighborPropagation(z)# Load example data z<-1:20 z[2:5]<-NA z<-TSNANNearestNeighborPropagation(z)