GeoEco.Connectivity.LarvalDispersal.LarvalDispersal.VisualizeResults2012

classmethod LarvalDispersal.VisualizeResults2012(simulationDirectory, resultsDirectory, outputGDBName, mortalityRate=None, mortalityMethod='A', createDensityRasters=True, minimumDensity=1e-05, useCompetencyForDensityRasters=False, createConnectionsFeatureClass=True, minimumDispersal=1e-05, minimumDispersalType='Quantity', overwriteExisting=False)

Produces GIS outputs that visualize the results of a simulation executed with the Treml et al. (2012) algorithm.

Run this tool after the Run Larval Dispersal Simulation (2012 Algorithm) tool to produce a time series of rasters showing larval density throughout the study area and a line feature class showing connections between patches. You many also optionally apply a mortality rate.

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.

• resultsDirectory (str) – Directory in which the results of the simulation have been created by the Run Larval Dispersal Simulation (2012 Algorithm) tool. Minimum length꞉ 1. Must exist.

• outputGDBName (str) –

  Name of the output file geodatabase (.gdb) to create.

  The geodatabase will be created in the results directory. If it already exists, the tool will either overwrite it or fail with an error, depending on whether you have requested that outputs be overwritten.

  Minimum length꞉ 1.

• 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'.

• createDensityRasters (bool, optional) –

  If this option is enabled (the default) the tool will create in the output geodatabase a time series of rasters showing the density of larvae throughout the study area as the simulation progresses.

  The first raster will be created at the start of the simulation, before any larvae have moved. Subsequent rasters will be created each time the summarization period elapses. The rasters will be named Density_YYYYMMDD_HHMM where YYYY, MM, DD, HH, and MM are the year, month, day, hour, and minute.

  The units of the rasters are the quantity of larvae per grid cell, 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).

• minimumDensity (float, optional) –

  Minimum value that a density raster cell must be to not be masked.

  You may set this parameter as low as zero. If you set it to zero, the density rasters will be produced with no masking. The results 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. To avoid a confusing visualization, use this parameter to mask the extremely density values that result from diffusion.

  Minimum value꞉ 0.0.

• useCompetencyForDensityRasters (bool, optional) –

  If this option is disabled (the default) the tool will include all larvae in the density rasters. If enabled, the tool will exclude larvae that are not yet competent from the density rasters.

  This option is only useful if you configured the larval competency parameters of your simulation such that larvae did not become immediately competent to settle. This configuration raises the possibility that larvae released from a patch may drift by a nearby patch before they become competent, leading to a potentially surprising result that nearby patches may not be highly connected. Use this option to help visualize whether this might be happening.

• createConnectionsFeatureClass (bool, optional) –

  If this option is enabled (the default) the tool will create a Connections line feature class in the output geodatabase 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 Minimum Dispersal Threshold parameter controls how strong the connection must be for a line to be drawn. If sufficient larvae flowed in both directions between two patches, one 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.

• 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 geodatabase will be deleted and recreated, if it exists. If False, a ValueError will be raised if the output geodatabase exists.

Returns:

1. str: Updated results directory.

2. str: Results geodatabase.

Return type:

tuple of 2 items