matpopmod.trajectories¶
This module implements the class Trajectory
. Instances of this class
are returned by MPM.trajectory
and
taken as argument by plot.trajectory
.
- class matpopmod.trajectories.Trajectory(timescale, Y, model, stochastic=False)¶
High-level representation of population trajectories.
The main purpose of this class is simply to bundle the various data needed to plot population trajectories. Thus,
Trajectory
objects are mostly meant to be passed around by the user, as inorca = matpopmod.examples.orcinus_orca traj = orca.trajectory([0, 10, 0, 0], t_max=100) matpopmod.plot.trajectory(traj)
rather than manipulated directly. However, the interface of the class also makes it easy for users to use trajectories in numerical calculations.
Basic attributes of the trajectory
- timescale¶
The vector of times at which the population is observed. That is,
timescale[k]
is the absolute time corresponding to the k-th step of the trajectory.This is a read-only NumPy array. Use
set_timescale()
to modify it.
- Y¶
The 2D array of population vectors. That is,
Y[k]
is the population vector at timetimescale[k]
.This is a read-only NumPy array. See
centered_Y()
,rescaled_Y()
and other methods below for common transformations of the population vector.
- model¶
The
MPM
associated with the trajectory (for stochastic trajectories, this is the matrix population model giving the expected value of the population vector).
- stochastic¶
Whether the trajectory is a realization of a multitype Galton–Watson process, or simply the deterministic trajectory of the associated matrix population model.
Transformations of the population vector
- rescaled_Y¶
The trajectory rescaled by its (expected) order of magnitude, that is,
\[\mathbf{Y}(t) \; / \; \lambda^t, \]where \(\lambda\) is the asymptotic growth rate (for stochastic trajectories, this is the expected asymptotic growth rate; trajectories that go extinct have an asymptotic growth rate of 0 and trajectories conditioned on not going extinct have a larger asymptotic growth rate).
- centered_Y¶
The trajectory minus its expected value, that is,
\[\mathbf{Y}(t) - \mathbf{A}^{\!t\,} \mathbf{Y}(0).\]For deterministic trajectories, this is not relevant as it is always zero. For stochastic trajectories, this is what is known in the ecological literature as the demographic stochasticity.
- rescaled_centered_Y¶
The fluctuations of the trajectory around its mean, rescaled by their expected order of magnitude:
\[\big(\mathbf{Y}(t) - \mathbf{A}^{\!t\,} \mathbf{Y}(0)\big) \;/\; \lambda^t.\]
- second_order_Y¶
The trajectory minus its (expected) first-order dynamics, that is,
\[\mathbf{Y}(t) - \mathbf{v} \mathbf{Y}(0) \, \lambda^t \, \mathbf{w}.\]For deterministic trajectories, this shows the second-order dynamics, i.e. the dynamics associated with the largest subdominant eigenvalue(s). For stochastic trajectories, this mostly shows the fluctuations around the mean (because those are on the same scale as the first-order dynamics, whereas the second-order dynamics are on a smaller scale).
- rescaled_second_order_Y¶
The trajectory minus its first-order dynamics, rescaled by the order of magnitude of the second-order dynamics, that is,
\[\big(\mathbf{Y}(t) - \mathbf{v} \mathbf{Y}(0) \,\lambda^t\, \mathbf{w} \big) \;/\; \tau^t, \]where \(\tau\), if it exists and is non-zero, is the largest modulus of the subdominant eigenvalues (as in the definition of the damping ratio, \(\rho = \lambda / \tau\)).
With deterministic trajectories, this is useful to show the periodic component of the second-order dynamics.
Other methods
Trajectory generation
- matpopmod.trajectories.compute_trajectory(model, n0, t_max, step=1)¶
Internal implementation of the method
trajectory()
ofMPM
. Refer to the documentation of that method for a more detailed description.model: the
MPM
whose trajectory we want to compute.n0: the initial population vector.
t_max: the maximal time.
step: the time-step of the trajectory.
Returns a
Trajectory
.
- matpopmod.trajectories.compute_stochastic_trajectories(model, n0, t_max, reps, reproduction='poisson', Z=None)¶
Internal implementation of the method
stochastic_trajectories()
ofMPM
. Refer to the documentation of that method for a more detailed description.model: the
MPM
parametrizing the trajectories.n0: the (deterministic) initial population vector.
t_max: the maximal time.
reps: the number of independent replicates.
reproduction: the offspring distribution. Should be either
"poisson"
or, for monotocous species,"bernoulli"
. Note that this is the law of the number of offspring in the biological sense, not in the “Galton–Watson” one. This argument is ignored if Z is supplied.Z: the random variable such that \(\mathbf{Y}(t+1) = Z(\mathbf{F}, \mathbf{S}, \mathbf{Y}(t))\) if the A = S + F decomposition is available, and \(\mathbf{Y}(t+1) = Z(\mathbf{A}, \mathrm{None}, \mathbf{Y}(t))\) otherwise.
Returns a list of
Trajectory
objects.