GeoEco.Connectivity.LarvalDispersal.LarvalDispersal.VisualizeMultipleResults2012

classmethod LarvalDispersal.VisualizeMultipleResults2012(simulationDirectory, resultsDirectories, outputConnections, summaryStatistic, mortalityRate=None, mortalityMethod='A', minimumDispersal=1e-05, minimumDispersalType='Quantity', overwriteExisting=False)

Produces GIS outputs that summarize multiple connectivity simulation runs executed with the Treml et al. (2012) algorithm.

It is often useful to execute the Run Larval Dispersal Simulation tool for different time periods to investigate how variations in ocean currents affect connectivity. The Visualize Multiple Larval Dispersal Simulation Results tool reads the results of multiple simulations, combines them, and produces a line feature class that summarizes the connections between patches using the statistic you specify. For example, if you ran 10 simulations and selected the Mean summary statistic, the output line features would show the average connectivity between each pair of patches over the 10 simulations.

You many also optionally apply a mortality rate. The same mortality rate will be applied to all simulations prior to combining them and computing the summary statistic.

References:

Treml EA, Roberts J, Chao Y, Halpin P, Possingham HP, Riginos C (2012) Reproductive output and duration of the pelagic larval stage determine seascape-wide connectivity of marine populations. Integrative and Comparative Biology 52(4): 525-537.

Requires: ArcGIS Pro 3.6.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.6.0 or later, ArcGIS ‘spatial’ extension, Python numpy module, Python matplotlib module.

Parameters:

• simulationDirectory (str) –

  Existing larval dispersal simulation directory that has been loaded with ocean currents.

  The directory must have been created using the Create Larval Dispersal Simulation tool and then loaded with ocean currents using one of the tools provided for this purpose.

  Minimum length꞉ 1. Must exist.

• resultsDirectories (list of str) – List of one or more results directories created by the Run Larval Dispersal Simulation (2012 Algorithm) tool. Minimum length꞉ 1.

• outputConnections (str) –

  Output line feature class to create showing the connections between patches.

  The lines are directional, originating at a source patch centroid and terminating at a destination patch (or “sink patch”) centroid. The tool creates them as follows:

  1. If a morality rate is provided, the tool applies it to all simulation results. If no mortality is provided, this step is skipped.

  2. The tool aggregates all of the simulation results and applies the summary statistic to all possible pairs of patches. For any given pair of patches, A and B, there are four possible connections: A to B, B to A, A to A, and B to B. The tool applies the statistic to all four possible connections, for all pairs of patches that were simulated.

  3. The tool iterates through all possible connections and compares the summarized result to the Minimum Dispersal Threshold parameter to determine if a connection was strong enough for a line to be drawn. If sufficient larvae flowed in both directions between two patches, a line will be drawn in each direction; the two lines will exactly overlap. If a patch experienced sufficient self recruitment (larvae released by the patch settled at that same patch), a circular line will be drawn from the patch’s centroid to itself. For convenience of visualization, the size of the circle is scaled to the length of the “minor axis” of the zonal geometry of the patch; the size does not relate to the degree of connectivity.

  Each line has four attributes:

  • FromPatchID - source patch that released larvae.

  • ToPatchID - destination patch that larvae settled on.

  • Quantity - quantity of larvae that settled. The units are relative to the maximum possible quantity that can occupy a cell at the start of the simulation when larvae are first released. The value 1.0 corresponds to the quantity of larvae released at the start of the simulation in one cell that is fully covered by suitable habitat (i.e. the Patch Cover Raster has the value 1.0 in that cell).

  • Probability - probability that a larva released by the source patch settled on the destination patch. This is computed by dividing the Quantity (above) by the total amount of larvae released by the source patch at the start of the simulation. (Note: probabilities are first computed for each simulation, then the summary statistic is applied.)

  Minimum length꞉ 1.

• summaryStatistic (str) –

  Statistic to calculate. The same statistic is calculated for each of the two output fields, Quantity and Probability.

  Standard Deviation is the sample standard deviation, i.e. the standard deviation estimated using Bessel’s correction. In order to calculate this, at least two simulations must have been conducted.

  Allowed values꞉ 'Maximum', 'Mean', 'Median', 'Minimum', 'Range', 'Standard Deviation'.

• mortalityRate (float, optional) –

  Instantaneous daily mortality rate, as the proportion of larvae killed per day. It must be greater than 0 and less than 1. Expressed as a percentage killed per day, the value 0.1 corresponds to 10%.

  If omitted (the default), larvae will not be subject to mortality. If provided, survivorship will be calculated according to the Mortality Method parameter using this mortality rate. For example, if the mortality rate is 0.1 and the mortality method is ‘A’, the proportion alive 1, 2, and 3 days after the larvae were released will be 0.9, 0.81, and 0.729, respectively.

  When mortality is used, the tool will create a plot named X_SurvivorshipCurve.png that shows the proportion of larvae alive over time, assuming all drift without settling. X is the name of the output geodatabase. If competency was used, the tool also creates a plot called X_SurvivorshipCurveWithCompetency.png that multiplies the survivorship curve by the competency curve, giving the number of larvae alive that are competent to settle at each point in time.

  The tool applies mortality at each summarization period, after larvae have moved but before they settle. For plausible results, it is therefore important to ensure the summarization period is small relative to between-patch transit times, or an unrealistically large fraction of larvae will be killed by mortality before they have the chance to settle.

  For example, consider a situation in which larvae can drift from a source patch to destination patch in one day. Assume they are immediately competent and can therefore settle at the destination patch as soon as they arrive, with a settlement rate of 1.0. We would therefore expect that many larvae will have settled between the first and second day. But if the first summarization period does not elapse until day 10, survivorship will be calculated for all the larvae that settle within the first 10 days using t=10 in the equation above. This would effectively assume that it took all of these larvae 10 days to drift to the destination patch, during which time they were subject to 10 days of mortality. Because it only took took them 1 or 2 days to drift and settle, the loss due to mortality will be unrealistically high, because they only should have been subject to 1 or 2 days of mortality.

  To ensure plausible results, when running the simulation we we recommend you configure the Summarization Period parameter so that summaries occur every 1 day or less, particularly if you have a high mortality rate. The most realistic results will be obtained by setting the Summarization Period parameter to 1, so that summaries occur for every time step of the simulation. However, if there are many time steps, as would occur if the Duration parameter is large and the Time Step parameter is small, there may not be sufficient memory for the simulation to execute. If so, the simulation may fail immediately with an “OUT OF MEMORY” error. In that case, you have little choice but to increase the Summarization Period.

  For some readers, this discussion may prompt the question: why was mortality implemented in this post-hoc way, rather than as part of the execution of the simulation itself? If mortality were applied at each time step while the simulation was executing, rather than at each summarization step after the simulation is over, couldn’t this problem could be avoided entirely?

  The answer is that the approach of applying it after the simulation is over allows you to quickly test the effects of different mortality rates without rerunning the simulation, which can require hours if your simulation has a long duration or hundreds of patches. Mortality has a strong influence on connectivity (Treml et al. 2012). We have found it useful to perform this kind of sensitivity analysis when mortality rates are uncertain and optimized the design of the tool to facilitate this.

  References:

  Treml EA, Roberts J, Chao Y, Halpin P, Possingham HP, Riginos C (2012) Reproductive output and duration of the pelagic larval stage determine seascape-wide connectivity of marine populations. Integrative and Comparative Biology 52(4): 525-537.

  Must be greater than 0.0. Must be less than 1.0.

• mortalityMethod (str, optional) –

  Method used to calculate survivorship from the Mortality Rate parameter:

  • A - Survivorship will be calculated according to the expression exp(log(1-L)*t). This is the default. Under this method, the number of larvae killed between t and t+1 is the number alive at t multiplied by the mortality rate L. Treml et al. (2012, 2015) and Schill et al. (2015) all used this method. For the mortality rate L=0.1 and t=1, 2, and 3 days, the proportions of surviving larvae are 0.9, 0.81, and 0.729, respectively.

  • B - Survivorship will be calculated according to the expression exp(-L*t). This method assumes an exponential decline in the surviving population at a constant rate. The formula is known as the survival function of the exponential distribution, among other names. Connolly and Baird (2010) presented this as their equation 8. For the mortality rate L=0.1 and t=1, 2, and 3 days, the proportions of surviving larvae are 0.904837, 0.818731, 0.740818, respectively.

  In these expressions, L is the mortality rate, t is the number of days elapsed since larvae were released, log(x) is the natural logarithm of x, and exp(x) is the mathematical constant e raised to the power of x.

  References:

  Connolly SR, Baird AH (2010) Estimating dispersal potential for marine larvae: dynamic models applied to scleractinian corals. Ecology 91(12): 3572-3583.

  Schill SR, Raber GT, Roberts JJ, Treml EA, Brenner J, Halpin PN (2015) No reef is an island: Integrating coral reef connectivity data into the design of regional-scale marine protected area networks. PLoS ONE 10(12): e0144199.

  Treml EA, Roberts J, Chao Y, Halpin P, Possingham HP, Riginos C (2012) Reproductive output and duration of the pelagic larval stage determine seascape-wide connectivity of marine populations. Integrative and Comparative Biology 52(4): 525-537.

  Treml EA, Roberts J, Halpin PN, Possingham HP, Riginos C (2015) The emergent geography of biophysical dispersal barriers across the Indo-West Pacific. Diversity and Distributions 21(4): 465-476.

  Allowed values꞉ 'A', 'B'.

• minimumDispersal (float, optional) –

  Minimum dispersal threshold that must be met or exceeded for the tool to draw a line connecting the source patch to a destination patch.

  The threshold can be specified as either a minimum quantity of larvae released by the source that must settle at the destination, or as the minimum probability that a larva released by the source will settle at the destination. The Minimum Dispersal Threshold Type parameter specifies which kind of threshold is used.

  This parameter must be greater than zero. If you set it to a very small value, almost all patches will have lines drawn between them. This result may seem surprising. For most simulations, larvae will have spread throughout the entire study area, albeit in very small quantities for most cells, via the diffusion component of the hydrodynamic calculations. Diffusion occurs equally in all directions at the rate specified by the Diffusivity parameter. Given enough time, an infinitesimal fraction of larvae from any given patch can theoretically spread throughout the entire ocean simply by diffusion.

  An important question is: why not set this parameter to a very small value and then filter weak connections later, e.g. in the map itself by applying a Definition Query to the layer? This is a valid approach. The main reason not to do this is it may take the tool a long time to create so many lines in the feature class. Whether or not this is a problem depends on the number of patches you have. Assuming each patch can be both a source and sink for larvae, the number of possible connections is 2 * P^2, where P is the number of patches. So if you only have 20 patches, at most 800 lines will be created, a relatively small number. But if you have 500 patches, as many as 500,000 lines will be created, which can take a considerable amount of time.

  Must be greater than 0.0.

• minimumDispersalType (str, optional) –

  Type of minimum dispersal threshold that will be used to determine whether a line should be drawn from a source patch to a destination patch. One of:

  • Quantity - the minimum absolute quantity of larvae released by the source patch that must settle at the destination patch. A cell that is 100% covered by suitable habitat will release 1 unit of larvae, while one that is only 50% covered will release 0.5 units of larvae.

  • Probability - the minimum probability that a larva released by the source patch will settle at the destination patch. For each source-destination pair, the probability is computed by dividing the absolute quantity of larvae from the source that settled on the destination by the total absolute quantity of larvae released by the source. For example, consider a source comprised of 5 cells that are 100% covered and 3 cells that are 50% covered. The total quantity of larvae released will be 6.5 units. If a destination patch receives in 0.52 units of larvae, totaled across all of its cells, then the probability is 0.52 / 6.5 = 0.08.

  Allowed values꞉ 'Quantity', 'Probability'.

• overwriteExisting (bool, optional) – If True, the output feature class will be deleted and recreated, if it exists. If False, a ValueError will be raised if the output feature class exists.