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 in

orca = 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 time timescale[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

set_timescale(new_timescale)

Replaces timescale with new_timescale.

Trajectory generation

matpopmod.trajectories.compute_trajectory(model, n0, t_max, step=1)

Internal implementation of the method trajectory() of MPM. 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() of MPM. 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.