The R package FlywayNet implements the inference of
the structure of migratory bird flyway networks given counts.
It relies on a HSMM discrete time model.
Underlying hypothesis:
sites are ordered, birds can only fly forward, no loop possible,
initial state (ie number of birds at each site) at time t0 known,
death probabilities at each site known,
a multinomial law for site transition probabilities,
a Poisson law for site sojourn time distribution,
a Poisson law for observed counts.
Parameters to infer:
sites transition probabilities,
sites sojourn time law parameters.
Given S site. For sites transition probabilities, due to the order of sites, the parameters to infer are in a upper triangular matrix. As the death probability is known, the number of free parameters to infer is <U+00BD> S . (S+1). When site links are known to be impossible, the number of transition parameters to infer is reduced. For mean sites sojourn time, there is 1 parameter per site to infer.
Two approaches: ABC and MCEM are available to infer parameters.
The package is organized around a central class (structure) called migration. This structure may be use to infer parameters, to simulate trajectories and even to generate observations (counts) depending on the information store in the structure.
Attributes of the migration class representing a migration network fo S sites:
site_name: list of ordered (a site can only be related to a successor site in the list) sites names [list of S caracter set].
link_knowledge: known possible relation between sites [matrix S x S of logical]. TRUE when link is possible, FALSE if not. Beware, this attribute must be consistent with the considering of site_name attribut.
flight_duration: times to fly between two linked sites [matrix S x S, integer], -1 stands for unknown.
initial_state: initial state (number of birds per site at t=0) [vector 1 x S, integer].
horizon: migration duration [integer]. t = 0, 1,<U+2026>, horizon.
death_probability: death probability at each site [vector 1 x S of double].
transition_law_type: name of site transition law [caracter set, <U+201C>multinomial<U+201D>].
transition_law_param: parameters of site transition law [NULL or matrix S x S of double]. Beware, row sums may not sum to 1 because of death probability on each site.
sojourn_law_type: name of site sojourn time law [caracter set, <U+201C>Poisson<U+201D>]
sojourn_law_param: parameters of site sojourn time distribution law [NULL or vector 1 x S of double].
observation_law_type: name of site observation probability law, [caracter set, <U+201C>Poisson<U+201D>]
observation_law_param: parameters [NULL or vector 1 x S of double].
observation: observed counts [NULL or matrix (S+2) x (horizon+1), integers in {1,<U+2026>, S, NA}. The first column is for time step zero. The two last rows are filled with NA.
estimation_method:
name: name [caracter set in <U+201D>ABC<U+201D>, <U+201D>MCEM<U+201D> ],
settings: information provided to the method [list of pair (parameter, value) ],
output:
transition_law_param: estimated probabilities of transition,
sojour_law_param: estimated sojourn time,
additional output (trace<U+2026>) [free format related to each method].
Required attributes of a migration structure for inference: site_name, link_knowledge, flight_duration, initial_state, horizon, death_probability, transition_law_type, sojourn_law_type.
For simulation, two more attributes are required: transition_law_param, sojourn_law_param.
Counts of birds are expressed as a matrix (S+2) x (horizon+1) of integer with S being the number of sites. Then a row i (i in 1,...,S) of the matrix is the observed counts of bird at each time step from 0 to horizon. Birds are not observed at time step 0, so the first column is filled of NA. The two last rows are filled with NA. This format is adapted also for counts of birds from a set of bird trajectories. In this case, the two last rows are also computed: states flying and dead.
Trajectories of birds are expressed as a matrix N x (horizon+1) of integer with N being the number of birds in initial state (time step 0). Then a row i of the matrix is the trajectory of the bird i at each time step indicating the state of the bird. Possible states of birds are a site number (1,<U+2026>,S), flying (0), or death (-1).
Model creation new_migration Generate a specific migration structure usable for inference or simulation depending of given attributs. generate_toy_migration Generate a toy problem, usable for inference or simulation. generate_random_migration Generate a random migration structure, usable for inference or simulation. generate_modified_migration Generate a modified migration structure, usable for inference or simulation.
Parameters estimation estimate_migration_ABC Infer parameters using ABC (Approximate Bayesian Computation) approach. estimate_migration_MCEM Infer parameters using MCEM (Monte Carlo Expectation Maximization) approach. reestimate_migration_from_MCEMruns Infer parameters using logs of several runs of MCEM. estimate_migration_from_trajectories Infer parameters just using a set of trajectories.
Simulation generate_trajectories Generate a trajectory for each bird. generate_observedcounts Generate a set of observed counts.
Utilities validate_migration Check the validity of a migration structure. read_migration Read a file describing a migration. write_migration Write a file describing a migration. plot Plot the migration graph of a given migration. plot_observedcounts Plot a set of observed counts as a flow. plot_trajectories Plot a set of trajectories as a flow. get_counts Compute the count of birds in each state (site number, flying, dead) at each time step, given a set of birds trajectories. set_freeparametersvalue Assign free parameter values to a migration structure. get_freeparametersvalue Extract free parameter values from a migration structure. get_paramlikelihood Computes, by simulation, the log-likelihood of parameters. get_observation_probability Computes the probability of observations given the birds count from trajectories.