MGSurvE package

Submodules

MGSurvE.auxiliary module

Various functions that are serve I/O purposes or not relevant to any specific module.

MGSurvE.auxiliary.cheapRuler(pointA, pointB): Calculates the distance between two (lon,lat) points assumming flat approximations. https://blog.mapbox.com/fast-geodesic-approximations-with-cheap-ruler-106f229ad016

MGSurvE.auxiliary.dumpLandscape(landscape, fPath, fName, fExt='bz2')

Exports a serialized landscape to disk.

Parameters:

landscape (object) – Landscape object to export.
fPath (path) – Path to where the landscape will be exported.
fName (string) – Filename.
fExt (string) – File extension.

MGSurvE.auxiliary.exportLandscape(landscape, fPath, fName)

Exports a landscape to disk to CSV files (for use in MGDrivE).

Parameters:

landscape (object) – Landscape object to export.
fPath (path) – Path to where the landscape will be exported.
fName (string) – Filename.

MGSurvE.auxiliary.haversineDistance(pointA, pointB): Calculates the distance between two (lon,lat) points using the haversine approximation.

MGSurvE.auxiliary.isNotebook()

Checks if the script is running from a Jupyter environment.

Returns:: Flags Jupyter environment.
Return type:: bool

MGSurvE.auxiliary.loadLandscape(fPath, fName, fExt='bz2')

Loads a serialized landscape from disk.

Parameters:

fPath (path) – Path from where the landscape will be loaded.
fName (string) – Filename.
fExt (string) – File extension.

Returns:

Landscape object.

Return type:

(object)

MGSurvE.auxiliary.makeFolder(path)

Crates a folder in the specified directory.

Parameters:: path (string) – Path of the folder than needs to be created.

MGSurvE.auxiliary.makeFolders(pathsList)

Creates a list of folders if they don’t exist.

Parameters:: paths (list) – List path to the desired directories.

MGSurvE.auxiliary.vincentyDistance(pointA, pointB, meters=True)

Calculates the Vincenty arc distance between points.

Parameters:

pointA (tuple) – First point in (lon, lat) format.
pointB (tuple) – Second point in (lon, lat) format.

Returns:

Distance between points

Return type:

(float)

MGSurvE.colors module

Color-related functions for alphas and cmaps.

MGSurvE.colors.colorPaletteFromHexList(clist)

Generates a matplotlib-compliant cmap from a list of hex colors.

Parameters:: clist (list) – List of hex codes (eg. ‘#f72585’) to blend in the map.
Returns:: Matplotlib’s colormap object.
Return type:: cmap

MGSurvE.constants module

Constants used across the pkg (colors, symbols, bio).

MGSurvE.constants.AEDES_EXP_PARAMS = [0.01848777, 1e-10, inf]: Aedes aegypti’s migration parameters for kernel.

MGSurvE.constants.BASIC_EXP_TRAP = {'A': 0.5, 'b': 0.15}: Generic params for an exponential-decay trap

MGSurvE.constants.LAND_TUPLES = (('10m', '#dfe7fd55', 30), ('10m', '#ffffffDD', 5)): Base colors for land boundaries.

MGSurvE.constants.MCOL = ('#bdb2ff', '#a0c4ff', '#e0c3fc', '#ffd6a5', '#caffbf', '#d0d1ff'): A cute pastel colors list.

MGSurvE.constants.MEDIUM_MOV_EXP_PARAMS = [0.075, 1e-10, inf]: Dummy migration parameters for short-distance kernel.

MGSurvE.constants.MKRS = ('o', '^', 's', 'p', 'd', 'X'): Markers for point-types

MGSurvE.constants.PINK_NAVY = <matplotlib.colors.LinearSegmentedColormap object>: Pink to Navy Blue cmap.

MGSurvE.constants.SHORT_EXP_PARAMS = [1, 1e-10, inf]: Dummy migration parameters for short-distance kernel.

MGSurvE.constants.TRP_COLS = {0: '#f7258515', 1: '#5ddeb125', 2: '#fe5f5515', 3: '#f038ff15', 4: '#e2ef7015', 5: '#9381ff15'}: Base colors for trap types.

MGSurvE.kernels module

Kernel functions and operations used for movement and traps attractivenesses.

MGSurvE.kernels.exponentialAttractiveness(dist, A=1, k=1, s=1, gamma=1, epsilon=1)

Calculates the probability of moving between points as a complex decaying exponential.

Parameters:

dist (float) – Distance between points.
A (float) – Maximum amplitude at distance 0 (attractiveness).
k (float) –
s (float) –
gamma (float) –
epsilon (float) – Error term

Returns:

Movement probability.

Return type:

float

MGSurvE.kernels.exponentialDecay(dist, A=1, b=1)

Calculates the probability of moving between points as a decaying exponential.

Parameters:

dist (float) – Distance between points.
A (float) – Maximum amplitude at distance 0.
b (float) – Decay rate (higher means tighter kernel).

Returns:

Movement probability.

Return type:

float

MGSurvE.kernels.exponentialKernel(distMat, decay=0.01848777)

Calculates the migration matrix using a decaying exponential function.

Parameters:

distMat (numpy array) – Distances matrix.
decay (float) – Exponential decay rate

Returns:

Migration matrix.

Return type:

numpy array

MGSurvE.kernels.inverseLinearStep(distance, params=[0.75, 1])

Calculates the zero-inflated linear distance-based movement probability.

Parameters:: distMat (numpy array) – Distances matrix.
Returns:: Migration matrix.
Return type:: numpy array

MGSurvE.kernels.nSolveKernel(kernelDict, yVal, guess=0, latlon=False, R=6371000.0)

Calculates the distance it takes for the kernel to match a given probability (yVar).

Parameters:

kernelDict (dict) – Dictionary with the kernel info {‘kernel’, ‘params’}.
yVal (float) – Probability for which we are solving the distance.
guess (float) – Initial guess for the distance.

Returns:

Distance for the probability value.

Return type:

float

MGSurvE.kernels.sigmoidDecay(dist, A=1, rate=0.5, x0=10)

Calculates the probability of moving between points as a sigmod.

Parameters:

dist (float) – Distance between points.
A (float) – Maximum amplitude at distance 0.
rate (float) – Logistic growth rate or steepness of the curve.
x0 (float) – The x value of the sigmoid’s midpoint

Returns:

Movement probability.

Return type:

float

MGSurvE.kernels.truncatedExponential(distance, params=[0.01848777, 1e-10, inf])

Calculates the zero-inflated exponential distance-based movement probability.

Parameters:

distance (float) – Distances matrix.
params (list) – Shape distribution parameters [rate, a, b].

Returns:

Migration probability.

Return type:

float

MGSurvE.kernels.zeroInflatedExponentialKernel(distMat, params=[0.01848777, 1e-10, inf], zeroInflation=0.75)

Calculates the migration matrix using a zero-inflated exponential function.

Parameters:

distMat (numpy array) – Distances matrix.
params (list) – Shape distribution parameters [rate, a, b].
zeroInflation (float) – Probability to stay in the same place.

Returns:

Migration matrix.

Return type:

numpy array

MGSurvE.kernels.zeroInflatedLinearMigrationKernel(distMat, params=[0.75, 1])

Calculates the zero-inflated linear distance-based movement probability.

Parameters:: distMat (numpy array) – Distances matrix.
Returns:: Migration matrix.
Return type:: numpy array

MGSurvE.landscape module

Main object with sites, traps, and masks to optimize and visualize the landscape to be analyzed.

class MGSurvE.landscape.Landscape(points, pointsTrapBanned=None, maskingMatrix=None, attractionVector=None, distanceMatrix=None, distanceFunction=None, migrationMatrix=None, kernelFunction=<function zeroInflatedExponentialKernel>, kernelParams={'params': [1, 1e-10, inf], 'zeroInflation': 0.75}, maskedMigrationMatrix=None, traps=None, trapsKernels={0: {'inverse': None, 'kernel': <function exponentialDecay>, 'params': {'A': 0.5, 'b': 0.15}}}, trapsMask=None, trapsRadii=[0.25, 0.2, 0.1, 0.05], landLimits=None, populations=None)

Bases: object

Stores the information for a mosquito landscape. Works with different point-types in the form of matrices and coordinates.

Parameters:

points (pandas dataframe) – Sites positions with mandatory {x,y} coordinates and optional {t: type, a: attractiveness} values for each site in the landscape.
kernelFunction (function) – Function that determines de relationship between distances and migration probabilities.
kernelParams (dict) – Parameters required for the kernel function to determine migration probabilities.
maskingMatrix (numpy array) – Matrix that determines the probability of shifting from one point-type to another one (squared with size equal to the number of point types). If None, every point-type transition is equiprobable.
attractionVector (list) – Relative attraction of one site to another (does not preserve migration matrix diagonal)
distanceMatrix (numpy array) – Matrix with the distances between all the points in the landscape. If None, it’s auto-calculated (see calcPointsDistances).
migrationMatrix (numpy array) – Markov matrix that determines the probability of moving from one site to another. If None, it’s auto-calculated (see calcPointsMigration).
maskedMigrationMatrix (numpy array) – Markov matrix that biases migration probabilities as dictated by the masking matrix. If None, it’s auto-calculated (see calcPointsMaskedMigration).
distanceFunction (function) – Function that takes two points in the landscape and calculates the distance between them.
traps (pandas dataframe) – Traps positions with mandatory {x,y} coordinates and optional {t: trap type integer, f: fixed bool (immovable)}.
trapsKernels (dict) – Traps’ kernels functions and parameters in dictionary form (where the indices must match the “t” values in the traps dataframe).
trapsMask (numpy array) – Traps’ masking matrix to make traps act upon mosquitos searching for a specific resource (shape: {trapsNum, sitesNum}).
trapsRadii (list) – List of probability values at which we want rings to be plotted in dataviz functions.
landLimits (tuple) – Landscape’s bounding box.

calcFundamentalMatrix(): Calculates the Markov fundamental matrix on the landscape.

calcPointsDistances(): Calculates the distancesMatrix amongst the points (in place).

calcPointsMaskedMigration(): Calculates the maskedMigrationMatrix depending on point-type (in place).

calcPointsMigration(): Calculates the migrationMatrix amongst the points (in place).

calcTrapsDistances(): Calculates the trapsDistances matrix (in place).

calcTrapsMigration(): Replaces section in the trapsMigration matrix (in place).

exportForMGDrivE()

getBoundingBox(): Returns the landscape’s ((minX, maxX), (minY, maxY)).

getDaysTillTrapped(fitFuns={'inner': <function max>, 'outer': <function mean>}): Gets the number of timesteps until a walker falls into a trap

plotDirectedNetwork(fig, ax, markers=('o', '^', 's', 'p', 'd', 'X'), colors=('#bdb2ff', '#a0c4ff', '#e0c3fc', '#ffd6a5', '#caffbf', '#d0d1ff'), edgecolors='black')

plotLandBoundary(fig, ax, landTuples=(('10m', '#dfe7fd55', 30), ('10m', '#ffffffDD', 5)))

plotMaskedMigrationNetwork(fig, ax, lineColor='#03045e', lineWidth=20, alphaMin=0.5, alphaAmplitude=2.5, zorder=0, **kwargs): Plots the base sites migration network.

plotMigrationNetwork(fig, ax, lineColor='#03045e', lineWidth=20, alphaMin=0.5, alphaAmplitude=2.5, zorder=0, **kwargs): Plots the base sites migration network.

plotSites(fig, ax, markers=('o', '^', 's', 'p', 'd', 'X'), colors=('#bdb2ff', '#a0c4ff', '#e0c3fc', '#ffd6a5', '#caffbf', '#d0d1ff'), size=350, edgecolors='w', linewidths=2, zorder=5, **kwargs): Plots the sites coordinates.

plotTraps(fig, ax, colors={0: '#f7258515', 1: '#5ddeb125', 2: '#fe5f5515', 3: '#f038ff15', 4: '#e2ef7015', 5: '#9381ff15'}, marker='X', edgecolor='w', lws=(2, 1), ls=':', size=300, zorders=(25, -5), **kwargs): Plots the traps locations.

plotTrapsNetwork(fig, ax, lineColor='#f72585', lineWidth=20, alphaMin=0.5, alphaAmplitude=1.5, zorder=0, **kwargs): Plots the traps networks.

updateTraps(traps, trapsKernels)

Updates the traps locations and migration matrices (in place).

Parameters:

traps (pandas dataframe) –
trapsKernel (dictionary) –

updateTrapsCoords(trapsCoords)

Updates current trap coordinates.

Parameters:: trapsCoords (numpy array) –

updateTrapsCoordsByID(trapPositionsID)

Updates current trap coordinates by sites ID.

Parameters:: trapPositionsID (numpy array) –

updateTrapsRadii(probValues)

MGSurvE.matrices module

Migration and masking operations upon matrices.

MGSurvE.matrices.calcAttractiveness(migrationMtx, attractionVector)

Calculates the effects of attractiveness in the migration matrix.

Parameters:

migrationMtx (numpy array) – Original migration matrix (Tau).
attractivenessVct (numpy array) – Relative attractiveness modifier for sites.

Returns:

Full migration matrix with attractiveness effects.

Return type:

(numpy array)

MGSurvE.matrices.calcDistanceMatrix(pointCoords, distFun=<built-in function dist>)

Calculates the distance matrix between all the provided coordinates.

Parameters:

pointCoords (numpy array) – Coordinates of the sites.
distFun (function) – Distance function to be used in the computations.

Returns:

Distances matrix

Return type:

(numpy array)

MGSurvE.matrices.calcMaskedMigrationMatrix(migrationMatrix, maskingMatrix, pointTypes)

Calculates the masked migration matrix between points according to their types.

Parameters:

migrationMatrix (numpy array) – Migration probabilities amongst points.
maskingMatrix (numpy array) – Transition probabilities between point-types.
pointTypes (numpy vector) – Point-types for each one of the sites in the matrix (in the same order).

Returns:

Masked migration matrix

Return type:

(numpy array)

MGSurvE.matrices.calcTrapsProbabilities(trapsDistances, trapsTypes, trapsKernels, trapsMask, pointTypes)

Calculates the traps probabilities given distances to points in the landscape and their effectiveness kernels.

Parameters:

trapsDistances (numpy array) – Distances to all points.
trapsTypes (numpy array) – Types of the traps.
trapsKernels (function) – Kernels functions and params for trap types.
trapsMask (np array) – Traps’ catching bias mask (with shape: trapTypes, pointTypes)
pointTypes (list) –

Returns:

Traps probabilities

Return type:

(numpy array)

MGSurvE.matrices.calcTrapsToPointsDistances(trapsCoords, pointCoords, dFun=<built-in function dist>)

Generates the distances matrix between the traps and the sites.

Parameters:

trapsCoords (numpy array) – Coordinates of the traps.
pointsCoords (numpy array) – Coordinates of the sites.
dFun (function) – Distance function to be used in the computations.

Returns:

Distances matrix

Return type:

(numpy array)

MGSurvE.matrices.genVoidFullMigrationMatrix(migrationMatrix, trapsNumber)

Calculates a migration matrix with sections for traps (Xi) to be filled in place.

Parameters:

migrationMatrix (numpy array) – Migration matrix without any traps (Tau).
trapsNumber (int) – Number of traps in the landscape

Returns:

Full migration matrix with no traps effects

Return type:

(numpy array)

MGSurvE.network module

Network-analysis operations.

MGSurvE.network.calculateNetworkCentralities(transitionsMatrix, nodeCentrality=<function newman_betweenness_centrality>, edgeCentrality=<function edge_betweenness_centrality>, weight='distance')

MGSurvE.optimization module

GA Operators to calculate fitness and perform operations to search through optimization space.

MGSurvE.optimization.calcDiscreteFitness(chromosome, landscape, optimFunction=<function getDaysTillTrapped>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>})

Calculates the fitness function of the landscape given a chromosome (in place, so not thread-safe).

Parameters:

chromosome (list) – Discrete optimization chromosome.
landscape (object) – Landscape object to use for the analysis.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.calcDiscreteFitnessPseudoInverse(chromosome, landscape, optimFunction=<function getDaysTillTrappedPseudoInverse>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>}, rcond=1e-30)

Calculates the fitness function of the landscape given a chromosome (in place, so not thread-safe).

Parameters:

chromosome (list) – Discrete optimization chromosome.
landscape (object) – Landscape object to use for the analysis.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.
rcond (float) – Cutoff for small singular values.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.calcDiscreteSexFitness(chromosome, landscapeMale=None, landscapeFemale=None, weightMale=1, weightFemale=1, optimFunction=<function getDaysTillTrapped>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>})

Calculates the fitness function of a Male/Female set of landscapes with a weighted sum of the time-to catch between them.

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
landscapeMale (object) – Male landscape object to use for the analysis.
landscapeFemale (object) – Female landscape object to use for the analysis.
weightMale (float) – Preference on catching males over females.
weightFemale (float) – Preference on catching females over males.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.calcFitness(chromosome, landscape=None, optimFunction=<function getDaysTillTrapped>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>})

Calculates the fitness function of the landscape given a chromosome (in place, so not thread-safe).

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
landscape (object) – Landscape object to use for the analysis.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.calcFitnessPseudoInverse(chromosome, landscape=None, optimFunction=<function getDaysTillTrappedPseudoInverse>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>}, rcond=1e-30)

Calculates the fitness function of the landscape given a chromosome using the matrix pseudo-inverse function (in place, so not thread-safe).

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
landscape (object) – Landscape object to use for the analysis.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.
rcond (float) – Cutoff for small singular values.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.calcSexFitness(chromosome, landscapeMale=None, landscapeFemale=None, weightMale=1, weightFemale=1, optimFunction=<function getDaysTillTrapped>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>})

Calculates the fitness function of a Male/Female set of landscapes with a weighted sum of the time-to catch between them.

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
landscapeMale (object) – Male landscape object to use for the analysis.
landscapeFemale (object) – Female landscape object to use for the analysis.
weightMale (float) – Preference on catching males over females.
weightFemale (float) – Preference on catching females over males.
optimFunction (function) – Function that turns a matrix into a fitness value.
optimFunctionArgs (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Landscape’s fitness function.

Return type:

(tuple of floats)

MGSurvE.optimization.chromosomeIDtoXY(chromosome, ptsID, pointCoords)

Converts a sites-ID crhomosome into a set of XY or lon-lat coordinates.

Parameters:

chromosome (list) – Discrete optimization chromosome.
ptsID (list) – Set of IDs for the sites (usually lnd.pointID).
pointCoords (numpy array) – Set of coordinates for matching points IDs (usually lnd.pointCoords)

Returns:

Traps positions xy or lon-lat pairs as defined by the selected sites IDs.

Return type:

(numpy array)

MGSurvE.optimization.cxBlend(ind1, ind2, fixedTrapsMask, alpha=0.5)

Mates two chromosomes by “blend” based on the provided mask (in place).

This implementation is similar to DEAP’s cxBlend (https://deap.readthedocs.io/en/master/api/tools.html#deap.tools.cxBlend). Follow this link for the original code: https://github.com/DEAP/deap/blob/master/deap/tools/crossover.py

Parameters:

ind1 (floats numpy array) – GA’s float chromosome generated by initChromosome.
ind2 (floats numpy array) – GA’s float chromosome generated by initChromosome.
fxdTrpsMsk (bool numpy array) – Array of bools that define which alleles can be mutated (1).
alpha (float) – weight for each of the chromosomes.

Returns:

Mated individuals.

Return type:

(list of chromosomes)

MGSurvE.optimization.cxDiscreteUniform(ind1, ind2, fixedTraps, indpb=0.5)

Mates two chromosomes in place by swapping alleles between them.

Parameters:

ind1 (list) – Chromosome of the first parent in the mating operation.
ind2 (list) – Chromosome of the first parent in the mating operation.
fixedTraps (_type_) – List of flags on traps that can be moved (lnd.trapsFixed).
indpb (float, optional) – Mutation probability for each independent allele. Defaults to 0.5.

Returns:

Mated individuals.

Return type:

(list of chromosomes)

MGSurvE.optimization.exportLog(logbook, outPath, filename)

Dumps a dataframe with the report of the GA’s history.

Parameters:

logbook (object) – DEAP GA object.
outPath (path) – Path where the file will be exported.
F_NAME (string) – Filenamme (without extension).

MGSurvE.optimization.genFixedTrapsMask(trapsFixed, dims=2)

Creates a mask for the fixed traps (non-movable).

Parameters:

trapsFixed (bool numpy array) – Boolean array with the traps that are not movable (lnd.trapsFixed).
dims (int) – Unused for now, but it’s the number of dimensions for the landscape.

Returns:

Mask of the elements that can be moved in the GA operations.

Return type:

(numpy array)

MGSurvE.optimization.getCanonicalElements(tau, sitesN, trapsN)

Helper function to return canonical elements of the traps matrix (Q (tau), R (v), I).

Parameters:

tau (numpy array) – Migration matrix with traps included
sitesN (int) – Number of sites
trapsN (int) – Number of traps

Returns:

Dictionary of elements in canonical matrix.

Return type:

(dict)

MGSurvE.optimization.getDaysTillTrapped(landscape, fitFuns={'inner': <function max>, 'outer': <function mean>})

Gets the number of timesteps until a walker falls into a trap.

Parameters:

landscape (object) – Landscape object to use for the analysis.
fitFuns (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Number of days for mosquitoes to fall into traps given the fitFuns.

Return type:

(float)

MGSurvE.optimization.getDaysTillTrappedPseudoInverse(landscape, fitFuns={'inner': <function max>, 'outer': <function mean>}, rcond=1e-30)

Gets the number of timesteps until a walker falls into a trap (using pseudo-inverse matrix function).

Parameters:

landscape (object) – Landscape object to use for the analysis.
fitFuns (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.
rcond (float) – Cutoff for small singular values.

Returns:

Number of days for mosquitoes to fall into traps given the fitFuns.

Return type:

(float)

MGSurvE.optimization.getDaysTillTrappedVector(landscape, fitFuns={'inner': None, 'outer': <function mean>})

Gets the number of timesteps until a walker falls into a trap in vector form.

Parameters:

landscape (object) – Landscape object to use for the analysis.
fitFuns (dict) – Dictionary with the outer (row) and inner (col) functions to use on the matrix.

Returns:

Number of days for mosquitoes to fall into traps given the fitFuns.

Return type:

(float)

MGSurvE.optimization.getFundamentalFitness(fundamentalMatrix, fitFuns={'inner': <function max>, 'outer': <function mean>})

Get fitness from Markov’s fundamental matrix.

Parameters:

fundamentalMatrix (numpy array) – Markov’s fundamental matrix (calcFundamentalMatrix)
fitFuns (dict) – Dictionary containing the inner (row) and outer (col) operations for the fundamental matrix.

Returns:

Summarized fitness function for the fundamental matrix.

Return type:

(float)

MGSurvE.optimization.getFundamentalMatrix(tau, sitesN, trapsN)

Get Markov’s fundamental matrix (pseudo-inverse).

Equivalent to using reshapeInCanonicalForm and getMarkovAbsorbing (which: should be deprecated).

Parameters:

tau (numpy array) – Traps migration matrix in canonical form.
sitesN (int) – Number of sites.
trapsN (int) – Number of traps.

Returns:

Time to fall into absorbing states from anywhere in landscape.

Return type:

(numpy array)

MGSurvE.optimization.getFundamentalMatrixPseudoInverse(tau, sitesN, trapsN, rcond=1e-20)

Get Markov’s fundamental matrix (inverse).

Equivalent to using reshapeInCanonicalForm and getMarkovAbsorbing (which: should be deprecated).

Parameters:

tau (numpy array) – Traps migration matrix in canonical form.
sitesN (int) – Number of sites.
trapsN (int) – Number of traps.
rcond (float) – Cutoff for small singular values.

Returns:

Time to fall into absorbing states from anywhere in landscape.

Return type:

(numpy array)

MGSurvE.optimization.getFundamentalVector(tau, sitesN)

Get Markov’s fundamental vector.

Equivalent to:: np.sum(srv.getFundamentalMatrix(tau, sitesN, trapsN), axis=1) np.sum(srv.getFundamentalMatrixPseudoInverse(tau, sitesN, trapsN), axis=1)

Parameters:

tau (numpy array) – Traps migration matrix in canonical form.
sitesN (int) – Number of sites.

Returns:

Time to fall into absorbing states from anywhere in landscape.

Return type:

(numpy array)

MGSurvE.optimization.getMarkovAbsorbing(tauCan, trapsN)

Get Markov’s absorbing states (deprecated).

Parameters:

tauCan (numpy array) – Traps migration matrix in canonical form.
trapsN (int) – Number of traps.

Returns:

Time to fall into absorbing states from anywhere in landscape.

Return type:

(numpy array)

MGSurvE.optimization.getMeanTimeToCapture(canonElems, pseudoInv=True, rcond=1e-20)

Calculates the average time to capture given the Q, R, I Markov canonical elements.

Parameters:

canonElems (dict) – Dictionary containing the Q, R, and I matrices as calculated by Markov’s fundamental matrix.
pseudoInv (bool, optional) – Boolean to choose either normal matrix inverse or matrix pseudo-inverse. Defaults to True.
rcond (_type_, optional) – Limit condation for floating precision on pseudo-inverse. Defaults to 1e-20.

Returns:

Mean time to capture.

Return type:

float

MGSurvE.optimization.getTimeToCapture(landscape, fitFuns={'outer': <function sum>}, pseudoInv=True, rcond=1e-10)

Wrapper function for ‘getMeanTimeToCapture’ given a landscape.

Parameters:

landscappe (object) – Landscape object
fitFuns (dict) – Dictionary containing the outer function for summarize.

Returns:

Mean time to capture.

Return type:

float

MGSurvE.optimization.importLog(inPath, filename)

Gets the number of timesteps until a walker falls into a trap.

Parameters:

LOG_PTH (path) – Path where the file is stored.
F_NAME (dict) – Filename with extension.

Returns:

GA optimization log.

Return type:

(pandas dataframe)

MGSurvE.optimization.initChromosome(trapsCoords, fixedTrapsMask, coordsRange)

Generates a random uniform chromosome for GA optimization.

Parameters:

trapsCoords (int) – Number of traps to lay down in the landscape.
fixedTrapsMask (list of bools) – Mask with coordinates that can be moved (true) and which can’t (false).
coordsRange (tuple of tuples of floats) –

Returns:

List of xy coordinates for the traps’ positions.

Return type:

(list)

MGSurvE.optimization.initChromosomeMixed(trapsCoords, fixedTrapsMask, typeOptimMask, coordsRange, trapsPool, indpb=0.75)

Generates a compound chromosome for optimization with a coordinates-type composition (currently unusued).

Parameters:

trapsCoords (numpy array) – Current traps positions.
fxdTrpsMsk (bool numpy array) – Array of bools that define which alleles can be mutated (1).
typeOptimMask (bool numpy array) – Array of bools that define which alleles can be mutated (1).
coordsRange (numpy array) – Allowed trap coordinates for init.
trapsPool (integers array) – Types of traps available in the pool.
indpb (float, optional) – Allele mutation probability. Defaults to .75.

Returns:

Randomly-generated chromosome.

Return type:

list

MGSurvE.optimization.initDiscreteChromosome(ptsIds, fixedTraps, trapsSiteID=None, banSites=None)

Generates a random uniform chromosome for discrete GA optimizations (from available sites).

Parameters:

ptsIds (list) – List of points ids as stored in landscape (lnd.pointID).
fixedTraps (list) – List of flags on traps that can be moved (lnd.trapsFixed).
banSites (set) – List of sites that should not be taken into account for optimization (lnd.trapsBan).

Returns:

List of sites at which the traps are located for GA optimization.

Return type:

list

MGSurvE.optimization.mutShuffleIndexes(individual, typeOptimMask, indpb=0.5)

Shuffles allele indices in pairs.

Parameters:

individual (list) – Chromosome for optimization
typeOptimMask (bool numpy array) – Array of bools that define which alleles can be mutated (1).
indpb (float, optional) – Mutation probability for each independent allele. Defaults to 0.5.

Returns:

Mutated chromosome

Return type:

list

MGSurvE.optimization.mutateChromosome(chromosome, fixedTrapsMask, randFun=<built-in method normal of numpy.random.mtrand.RandomState object>, randArgs={'loc': 0, 'scale': 0.1}, indpb=0.5)

Mutates a chromosome with a probability distribution based on the mutation mask (in place).

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
fxdTrpsMsk (bool numpy array) – Array of bools that define which alleles can be mutated (1).
randFun (function) – Probability function for the mutation operation.
randArgs (dict) – Arguments to control the shape of the probability function.
indpb (float) – Independent probability to mutate each allele.

Returns:

Selectively-mutated chromosome.

Return type:

(numpy array list)

MGSurvE.optimization.mutateChromosomeAsymmetric(chromosome, fixedTrapsMask, randFun=<built-in method normal of numpy.random.mtrand.RandomState object>, randArgs={'x': {'loc': 0, 'scale': 0.1}, 'y': {'loc': 0, 'scale': 0.1}}, indpb=0.5)

Mutates a chromosome with a probability distribution based on the mutation mask with different probabilities for XY elements (in place).

Parameters:

chromosome (floats numpy array) – GA’s float chromosome generated by initChromosome.
fxdTrpsMsk (bool numpy array) – Array of bools that define which alleles can be mutated (1).
randFun (function) – Probability function for the mutation operation.
randArgs (dict) – Arguments to control the shape of the probability function (‘x’ and ‘y’ entries).
indpb (float) – Independent probability to mutate each allele.

Returns:

Selectively-mutated chromosome.

Return type:

(numpy array list)

MGSurvE.optimization.mutateChromosomeMixed(chromosome, fixedTrapsMask, typeOptimMask, mutCoordFun=<function mutateChromosome>, mutCoordArgs={'indpb': 0.5, 'randArgs': {'loc': 0, 'scale': 10}, 'randFun': <built-in method normal of numpy.random.mtrand.RandomState object>}, mutTypeFun=<function mutShuffleIndexes>, mutTypeArgs={'indpb': 0.5})

Generates a compound chromosome for optimization with a coordinates-type composition (currently unusued).

Parameters:

trapsCoords (numpy array) – Current traps positions.
fxdTrpsMsk (bool numpy array) – Array of bools that define which alleles can be mutated (1).
typeOptimMask (bool numpy array) – Array of bools that define which alleles can be mutated (1).
mutCoordFun (function) – Coordinates mutation function.
mutCoordArgs (dictionary) – Coordinates mutation function’s arguments.
mutTypeFun (function) – Trap types mutation function.
mutTypeArgs (dictionary) – Trap types mutation function’s arguments.

Returns:

Mutated chromosome.

Return type:

list

MGSurvE.optimization.mutateDiscreteChromosome(chromosome, ptsIds, fixedTraps, indpb=0.5, banSites=None)

Mutates a discrete chromosome from the available sites in the landscape (in place).

Parameters:

chromosome (list) – GA’s float chromosome generated by initChromosome.
ptsIds (list) – List of IDs for the sites (points) in the landscape (lnd.pointID).
fixedTraps (list) – List of flags on traps that can be moved (lnd.trapsFixed).
indpb (float, optional) – Mutation probability for each independent allele. Defaults to 0.5.
banSites (set, optional) – List of sites that should not be taken into account for optimization (lnd.trapsBan). Defaults to None.

Returns:

Mutated chromosome (in place).

Return type:

list

MGSurvE.optimization.optimizeDiscreteTrapsGA(landscape, generations=1000, bbox='auto', pop_size='auto', mating_params={'cxpb': 0.3, 'indpb': 0.5}, mutation_params={'indpb': 0.5, 'mutpb': 0.4}, selection_params={'tSize': 3}, fitnessFun=<function calcDiscreteFitness>, optimFunction=<function getDaysTillTrapped>, fitFuns={'inner': <function max>, 'outer': <function mean>}, verbose=True)

Optimizes the traps’ positions using a simple GA algorithm.

Parameters:

landscape (object) – Landscape object to use for the analysis.
generations (int, optional) – Number of generations to run in the GA. Defaults to 1000.
bbox (tuple, optional) – If not ‘auto’, tuple with the landscape’s bounding box for mutation operations. Defaults to ‘auto’.
pop_size (str, optional) – If not ‘auto’, size of the chromosome population size in the GA. Defaults to ‘auto’.
mating_params (dict, optional) – Mating probability (‘mate’) and crossover blending rate (‘cxpb’) for mating operations. Defaults to {‘mate’: .3, ‘cxpb’: 0.5}.
mutation_params (dict, optional) – Gaussian mean (‘mean’) and deviation (‘sd’) for mutation operations, as well as independent allele mutation probability (‘ipb’). Defaults to {‘mean’: 0, ‘sd’: 100, ‘mutpb’: .4, ‘ipb’: .5}.
selection_params (dict, optional) – Tournament size for the selection algorithm. Defaults to {‘tSize’: 3}.
optimFunction (function, optional) – Fitness function to be used upon the movement matrices. Defaults to getDaysTillTrapped.
fitFuns (dict, optional) – Fitness matrix reduction statistics (inner applied first, and outter applied to the result). Defaults to {‘outer’: np.mean, ‘inner’: np.max}.
verbose (bool, optional) – Verbosity on the optimization. Defaults to True.

Returns:

Returns the landscape and logbook for the optimization.

Return type:

(object, dataframe)

MGSurvE.optimization.optimizeTrapsGA(landscape, generations=1000, bbox='auto', pop_size='auto', mating_params={'alpha': 0.5, 'cxpb': 0.5}, mutation_params={'ipb': 0.5, 'mean': 0, 'mutpb': 0.4, 'sd': 100}, selection_params={'tSize': 3}, fitnessFun=<function calcFitness>, optimFunction=<function getDaysTillTrapped>, fitFuns={'inner': <function max>, 'outer': <function mean>}, verbose=True)

Optimizes the traps’ positions using a simple GA algorithm.

Parameters:

landscape (object) – Landscape object to use for the analysis.
generations (int, optional) – Number of generations to run in the GA. Defaults to 1000.
bbox (tuple, optional) – If not ‘auto’, tuple with the landscape’s bounding box for mutation operations. Defaults to ‘auto’.
pop_size (str, optional) – If not ‘auto’, size of the chromosome population size in the GA. Defaults to ‘auto’.
mating_params (dict, optional) – Mating probability (‘mate’) and crossover blending rate (‘cxpb’) for mating operations. Defaults to {‘mate’: .3, ‘cxpb’: 0.5}.
mutation_params (dict, optional) – Gaussian mean (‘mean’) and deviation (‘sd’) for mutation operations, as well as independent allele mutation probability (‘ipb’). Defaults to {‘mean’: 0, ‘sd’: 100, ‘mutpb’: .4, ‘ipb’: .5}.
selection_params (dict, optional) – Tournament size for the selection algorithm. Defaults to {‘tSize’: 3}.
optimFunction (function, optional) – Fitness function to be used upon the movement matrices. Defaults to getDaysTillTrapped.
fitFuns (dict, optional) – Fitness matrix reduction statistics (inner applied first, and outter applied to the result). Defaults to {‘outer’: np.mean, ‘inner’: np.max}.
verbose (bool, optional) – Verbosity on the optimization. Defaults to True.

Returns:

Returns the landscape and logbook for the optimization.

Return type:

(object, dataframe)

MGSurvE.optimization.optimizeTwoSexesTrapsGA(landscapeMale, landscapeFemale, sexWeights={'F': 0.5, 'M': 0.5}, generations=1000, bbox='auto', pop_size='auto', mating_params={'alpha': 0.5, 'cxpb': 0.3}, mutation_params={'ipb': 0.5, 'mean': 0, 'mutpb': 0.4, 'sd': 100}, selection_params={'tSize': 3}, optimFunction=<function getDaysTillTrapped>, fitFuns={'inner': <function max>, 'outer': <function mean>}, verbose=True)

Optimizes the traps’ positions using a simple GA algorithm for two-sexes kernels.

Parameters:

landscapeMale (object) – Male landscape object to use for the analysis.
landscapeFemale (object) – Female landscape object to use for the analysis.
sexWeights (dictionary) – Male-to-Female priority dictionary.
generations (int, optional) – Number of generations to run in the GA. Defaults to 1000.
bbox (tuple, optional) – If not ‘auto’, tuple with the landscape’s bounding box for mutation operations. Defaults to ‘auto’.
pop_size (str, optional) – If not ‘auto’, size of the chromosome population size in the GA. Defaults to ‘auto’.
mating_params (dict, optional) – Mating probability (‘mate’) and crossover blending rate (‘cxpb’) for mating operations. Defaults to {‘mate’: .3, ‘cxpb’: 0.5}.
mutation_params (dict, optional) – Gaussian mean (‘mean’) and deviation (‘sd’) for mutation operations, as well as independent allele mutation probability (‘ipb’). Defaults to {‘mean’: 0, ‘sd’: 100, ‘mutpb’: .4, ‘ipb’: .5}.
selection_params (dict, optional) – Tournament size for the selection algorithm. Defaults to {‘tSize’: 3}.
optimFunction (function, optional) – Fitness function to be used upon the movement matrices. Defaults to getDaysTillTrapped.
fitFuns (dict, optional) – Fitness matrix reduction statistics (inner applied first, and outter applied to the result). Defaults to {‘outer’: np.mean, ‘inner’: np.max}.
verbose (bool, optional) – Verbosity on the optimization. Defaults to True.

Returns:

Returns the landscape and logbook for the optimization.

Return type:

(object, dataframe)

MGSurvE.optimization.reshapeInCanonicalForm(tau, sitesN, trapsN)

Reshapes a migration matrix into canonical form (deprecated).

Parameters:

tau (numpy array) – Traps migration matrix.
sitesN (int) – Number of sites.
trapsN (int) – Number of traps.

Returns:

Reshaped matrix in canonical form.

Return type:

(numpy array)

MGSurvE.optimizationPSO module

PSO Operators to calculate fitness and perform operations to search through optimization space.

class MGSurvE.optimizationPSO.Particle_Swarm(traps, p_min, p_max, lnd, num_particles=50, num_gens=500, s_min=-3, s_max=3, phi1=2, phi2=2, optimFunction=<function getDaysTillTrapped>, optimFunctionArgs={'inner': <function max>, 'outer': <function mean>})

Bases: object

evaluate()

Main function that executes PSO.

Output:: pop: The resulting particle locations logbook: Log of the changes that particles underwent best: The global best trap locations found by PSO

generate(p_min, p_max, smin, smax)

Generate 1 particle.

Particle location is randomized for movable traps; it remains the same for immovable traps. Particle speed is randomized for all elements in vector regardless of movable/immovable. This is fine because we multiply the speed by the trpMsk. smin, smax set by variables passed in.

getImmovableLocMask(traps_df)

Generate a mask for immovable trap locations. If trap movable, location mask should be (0, 0). If trap immovable, location mask should be its original location (x, y)

Input:

traps: dataframe representing original locations of traps with the following 4 columns:: x: x coordinate y: y coordinate t: type of trap f: 0 if movable, 1 if immovable

setup_toolbox()

Set up toolbox by registering particles, population, update function, and evaluate function.

Output: toolbox object for DEAP package

updateParticle(best, phi1, phi2)

Update location of the particle for 1 timestep.

Inputs:: part: Array containing particle positions in (x, y) coordinates best: Global best particle position so far phi1: Upper bound for random number generation for particle velocity (u1) phi2: Upper bound for random number generation for particle velocity (u2) equation from https://machinelearningmastery.com/a-gentle-introduction-to-particle-swarm-optimization/ speed/velocity per particle: V[t] X[t+1] = X[t] + V[t+1] V[t+1] = w * V[t] + c1 * r1 * (personal_best - X[t]) + c2 * r2 * (global_best - X[t])

w: inertia weight constant = 1 c1 = 1 r1 = u1 c2 = 1 r2 = u2 v_u1 = r1 * (personal_best - X[t]) = u1 * (part.best - part) v_u2 = r2 * (global_best - X[t]) = u2 * (best - part)

MGSurvE.optimizationPSO.setup_stats(pop): Set up Statistics

MGSurvE.plots module

Data-Visualization functions (thanks to Elijah Bartolome in the implementation of some of the visualization functions).

MGSurvE.plots.plotClean(fig, ax, frame=False, bbox=None, labels=False, pad=(0, 0))

Makes axes equally spaced and removes frame.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
frame (bool) – Flag to remove plot’s frame.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotDirectedNetwork(fig, ax, sites, pTypes, transMtx, markers=('o', '^', 's', 'p', 'd', 'X'), colors=('#bdb2ff', '#a0c4ff', '#e0c3fc', '#ffd6a5', '#caffbf', '#d0d1ff'), alphaNodeMin=1, alphaEdgeMin=1, alphaNodeAmplitude=50, alphaEdgeAmplitude=100, sizeNodeAmplitude=10000000000, widthEdgeAmplitude=10, edgecolors='black', transform=None, **kwargs)

Plots edge and node centrality.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
sites (numpy array) – Coordinates of the points.
pTypes (numpy array) – Point types.
transMtx (numpy matrix) – Transitions matrix.
markers (list) – List of marker shapes for point-types (matplotlib).
colors (list) – List of colors for point-types (matplotlib).
alphaNodeMin (float) – Minimum alpha value allowed for nodes.
alphaEdgeMin (float) – Minimum alpha value allowed for edges.
alphaNodeAmplitude (float) – Alpha multiplier for nodes of matrix.
alphaEdgeAmplitude (float) – Alpha multiplier for edges of matrix.
sizeNodeAmplitude (float) – Size multiplier for nodes of matrix.
widthEdgeAmplitude (float) – Width multiplier for edges of matrix.
edgecolors (color) – Edge color.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotFitness(fig, ax, fitness, pos=(0.5, 0.5), fmt='{:.2f}', fontSize=125, color='#00000011', zorder=5, **kwargs)

Adds the fitness value to the plot.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
pos (floats tuple) – Position for the text.
fmt (string formating) – String format for the fitness text.
fontSize (float) – Text’s font size.
color (color) – Font color
zorder (int) – Zorder for the text.
**kwargs – Matplotlib’s text kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotGAEvolution(fig, ax, gaLog, colors={'envelope': '#1565c0', 'mean': '#ffffff'}, alphas={'envelope': 0.5, 'mean': 0.75}, aspect=0.3333333333333333)

Makes axes equally spaced and removes frame.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
gaLog (pandas dataframe) – Flag to remove plot’s frame.
colors (dict) – Mean and envelope colors
alphas (dict) – Mean and envelope alphas

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotLandBoundary(fig, ax, landTuples=(('10m', '#dfe7fd55', 30), ('10m', '#ffffffDD', 5)))

Plots the land’s boundary as a polygon.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
landTuples (list of tuples) – Check the constants.py file for format.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotMatrix(fig, ax, matrix, trapsNumber=None, vmin=0, vmax=1, cmap='Purples', linecolor='#222222', linestyle=':', lw=0.5, ticks=False, **kwargs)

Block matrix plot for the connection network.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
trapsNumber (int) – Number of traps in landscape.
vmin (float) – Lower clipping value.
vmax (float) – Higher clipping value.
cmap (matplotlib colormap) – Matplotlib’s colormap object.
lineColor (color) – Color for the block’s boundaries.
lineStyle (matplotlib linestyle) – Linestyle for the block matrix’ boundaries.
lw (float) – Linewidth for block matrix boundaries.
ticks (bool) – Imshow ticks on/off
zorders (tuple) – Zorders for marker and circles.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotMigrationNetwork(fig, ax, transMtx, sitesB, sitesA, lineColor='#03045e', lineMin=0.025, lineWidth=20, alphaMin=0.5, alphaAmplitude=2.5, zorder=0, transform=None, **kwargs)

Plots a transitions matrix.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
transMtx (numpy matrix) – Transitions matrix.
sitesB (numpy array) – Coordinates of the vertices origins (sites/traps).
sitesA (numpy array) – Coordinates of the vertices desinations (sites/traps).
lineColor (color) – Color for the network.
lineWidth (float) – Amplitude for the linewidth.
alphaMin (float) – Minimum alpha value allowed.
alphaAmplitude (float) – Alpha multiplier for matrix.
zorder (int) – Matplotlib’s zorder.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotMovementKernel(fig, ax, xPoints, lnd, colors=('#8093f1', '#ec0868', '#7371fc22'), lineWidths=(4, 8, 0.5))

Generates a relative movement kernel plot.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
xPoints (np array) – Set of points
colors (list of hex) – List of colors to be used in the kernel profiles (zero inflation, kernel, vlines).
lineWidths (list of floats) – List of line widths to be used in the kernel profiles (zero inflation, kernel, vlines)

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotSites(fig, ax, sites, pTypes, markers=('o', '^', 's', 'p', 'd', 'X'), colors=('#bdb2ff', '#a0c4ff', '#e0c3fc', '#ffd6a5', '#caffbf', '#d0d1ff'), size=350, edgecolors='w', linewidths=1.25, zorder=5, transform=None, **kwargs)

Plots a transitions matrix.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
sites (numpy array) – Coordinates of the points.
pTypes (numpy array) – Point types.
markers (list) – List of marker shapes for point-types (matplotlib).
colors (list) – List of colors for point-types (matplotlib).
size (float) – Marker size.
edgecolors (color) – Edge color for markers.
linewidths (float) – Edge line width for markers.
zorder (int) – Matplotlib’s zorder.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotTraps(fig, ax, trapsCoords, trapsTypes, trapsKernels, trapsFixed, colors={0: '#f7258515', 1: '#5ddeb125', 2: '#fe5f5515', 3: '#f038ff15', 4: '#e2ef7015', 5: '#9381ff15'}, marker='X', edgecolors=('w', 'k'), lws=(2, 1), ls=':', size=350, zorders=(25, -5), fill=True, transform=None, transparencyHex='DD', latlon=False, proj=None, **kwargs)

Plots the traps with the radii of effectiveness.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
trapsCoords (numpy array) – Coordinates of the vertices.
trapsTypes (list ints) – Trap types IDs.
trapsKernels (dict) – Dictionary of traps kernels.
colors (dict) – List of colors for different trap types.
marker (mrk) – Marker type for matplotlib.
edgecolor (color) – Edgecolor for trap marker.
lws (tuple) – Line widths for marker and radii (in order).
ls (str) – Linestyle for the radii.
size (float) – Size of the marker.
zorders (tuple) – Zorders for marker and circles.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotTrapsKernels(fig, ax, lnd, colors={0: '#f7258515', 1: '#5ddeb125', 2: '#fe5f5515', 3: '#f038ff15', 4: '#e2ef7015', 5: '#9381ff15'}, alpha=0.75, distRange=(0, 100), aspect=0.3)

Creates a distance-attractiveness plot for kernels present in the landscape.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
colors (list of hex) – List of colors to be used in the kernel profiles.
alpha (float) – Opacity for the traces.
distRange (tuple) – Distances range for the x-axis.
aspect (float) – Aspect ratio for the axes.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotTrapsNetwork(fig, ax, transMtx, traps, sites, lineColor='#3d0e61', lineWidth=20, alphaMin=0.5, alphaAmplitude=2.5, zorder=0, transform=None, **kwargs)

Plots the connectivity network of traps in the landscape.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
transMtx (numpy array) – Full transitions matrix.
traps (numpy array) – Traps’ coordinates.
sites (numpy array) – Sites’ coordinates.
lineColor (color) – Color for the network’s line.
lineWidth (float) – Base width for the connections.
alphaMin (float) – Minimum alpha value for connections.
alphaAmplitude (float) – Multiplier for the alpha (proportional to connection).
zorders (tuple) – Z-orders for marker and circles.
kwargs (dict) – Matplotlib’s plot-compliant kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.plots.plotsClearMemory(): Forces matplotlib to clear all memory (probably an overkill). https://stackoverflow.com/questions/28757348/how-to-clear-memory-completely-of-all-matplotlib-plots

MGSurvE.plots.saveFig(fig, ax, filepath, filename, dpi=300, facecolor='w', transparent=False, bbox_inches='tight', pad_inches=0, **kwargs)

Save figure to disk.

Parameters:

fig (matplotlib) – Matplotlib fig object.
ax (matplotlib) – Matplotlib ax object.
filepath (string) – Path for figure export.
filename (string) – Filename for the export.
dpi (int) – Image resolution.
facecolor (color) – Background for the plot.
transparent (bool) – Transparent background.
bbox_inches (string) – Bounding box inches.
pad_inches (float) – Padding inches.
**kwargs – Matplotlib savefig kwargs.

Returns:

Matplotlib (fig, ax) tuple.

Return type:

(fig, ax)

MGSurvE.pointProcess module

Synthetic Landscape generation functions (thanks to Elijah Bartolome in the impelemntation of some of the point-process functions).

MGSurvE.pointProcess.ptsDonut(pointsNumber, radii, center=(0, 0))

Creates a distribution of points laid around a donut shape.

Parameters:

pointsNumber (int) – Number of sites.
radii (tuple of floats) – Minimum and maximum radii for the donut shape.
center (tuple of floats) – Coordinates for the center of the donut (x, y).

Returns:

Points’ coordinates.

Return type:

(numpy array)

MGSurvE.pointProcess.ptsPossion(pointsNumber, clustersNumber, radius, randomState=1698953410.342164, bbox=None, polygon=None)

Generates a synthetic landscape from a Poisson distribution.

Parameters:

pointsNumber (int) – Number of sites.
clustersNumber (int) – Number of sites’ clusters.
radius (float) – Radius of the circle centered on each parent.
randomState (int) – Random seed.
bbox (tuple of tuples) – Bounding box in the form ((xLo, xHi), (yLo, yHi))
polygon (name of shp file) – Shape-file for the points to be generated within.

Returns:

Points’ coordinates

Return type:

(numpy array)

MGSurvE.pointProcess.ptsRandUniform(pointsNumber, bbox)

Creates a random unifor distribution of points.

Parameters:

pointsNumber (int) – Number of sites
bbox (tuple of tuples) – Bounding box in the form ((xLo, xHi), (yLo, yHi))

Returns:

Points’ coordinates

Return type:

(numpy array)

MGSurvE.pointProcess.ptsRegularCircle(pointsNumber, radius, solStart=10)

Creates concentric circles of points.

Parameters:

pointsNumber (int) – Approximate number of sites (real number will be lower).
radius (float) – Radius of the circle to set points on.
solStart (float) – Starting point for the steps solver

Returns:

Points’ coordinates.

Return type:

(numpy array)

MGSurvE.pointProcess.ptsRegularGrid(pointsNumber, bbox)

Creates a regular grid (lattice) of points.

Parameters:

pointsNumber (int) – Number of sites.
bbox (tuple of tuples) – Bounding box in the form ((xLo, xHi), (yLo, yHi)).

Returns:

Points’ coordinates.

Return type:

(numpy array)

MGSurvE package

Submodules

MGSurvE.auxiliary module

MGSurvE.colors module

MGSurvE.constants module

MGSurvE.kernels module

MGSurvE.landscape module

MGSurvE.matrices module

MGSurvE.network module

MGSurvE.optimization module

MGSurvE.optimizationPSO module

MGSurvE.plots module

MGSurvE.pointProcess module

Module contents