API reference

This file is part of the ResIPy project (https://gitlab.com/hkex/resipy). @licence: GPLv3 @author: ResIPy authors and contributors

The ‘Project’ class wraps all main interactions between R* executables and other filtering or meshing part of the code. It’s the entry point for the user.

class resipy.Project.Project(dirname='', typ='R2')

Master class to handle all processing around the inversion codes.

Parameters

dirnamestr, optional: Path of the working directory. Can also be set using R2.setwd().
typstr, optional: Either R2 or R3t for 3D. Complex equivalents are cR2 and cR3t. Automatically infered when creating the survey.

addData(**kwargs)

Adds data to the survey - used usually to add reciprocal datasets

Parameters

**kwargs: Keyword arguments to be passed to Survey.addData()

addFilteredIP(): Add filtered IP to the dataframes.

addFlatError(percent=2.5)

Add a flat percentage error to resistivity data (for each survey in the class). This action is irreversable. Use case is for simulating modelling errors in unconventional surveys.

resError = res*(percent/100) + resError

Parameters

percentfloat: Error in percent.

addRegion(xz, res0=100, phase0=1, blocky=False, fixed=False, ax=None, iplot=False)

Add region according to a polyline defined by xz and assign it the starting resistivity res0.

Parameters

xzarray: Array with two columns for the x and y coordinates.
res0float, optional: Resistivity values of the defined area.
phase0float, optional: Read only if you choose the cR2 option. Phase value of the defined area in mrad
blockybool, optional: If True the boundary of the region will be blocky if inversion is block inversion.
fixedbool, optional: If True, the inversion will keep the starting resistivity of this region.
axmatplotlib.axes.Axes: If not None, the region will be plotted against this axes.
iplotbool, optional: If True , the updated mesh with the region will be plotted.

checkTxSign(): Checking and correcting the polarity of the transfer resistances (flat 2D surveys only !).

computeAttribute(formula, name, dump=None)

Compute a new attribute for each meshResults.

NOTE: this function present a security risk as it allows execution of python code inputed by the user. It should be used with caution.

Parameters

formulastr: Formula as a string. All attribute already in the mesh object are available from the x dictionary and can be sed as x[‘nameOfAttribute’]. e.g. : “1/x[‘Resistivity’]” will compute the inverse of the ‘Resistivity’ attribute if this attribute exists. Operators available are addition (+), soustraction (-), division (/) multiplication (*) and exponent (**). Parenthesis are also taken into account. numpy function such as np.sqrt() or np.cos() are also available. e.g. : “(np.sqrt(x[‘Resistivity’]) + 100)*1000” Note: use a mixture of double and single quote such as double for the entire string and single for indexing the dictionnary x[‘keyName’].
namestr: Name of the new attribute computed.
dumpfunction, optional: Function to write stdout.

computeDiff(): Compute the absolute and the relative difference in resistivity between inverted surveys.

computeFineMeshDepth(): Compute the Fine Mesh Depth (FMD) based on electrode positions and the larger dipole spacing. Express as a positive number, it represents the relative vertical distance to extend the fine mesh region below the surface.

computeModelError(rmTree=True)

Compute modelling error associated with the mesh. This is computed on a flat triangular or tetrahedral mesh.

Parameters

rmTreebool: Remove the working directory used for the error modelling. Default is True.

create3DSurvey(fname, lineSpacing=1, zigzag=False, ftype='Syscal', name=None, parser=None)

Create a 3D survey based on 2D regularly spaced surveys.

Parameters

fnamelist of str: List of 2D filenames in the right order for the grid or directory name (the files will be sorted alphabetically in this last case).
lineSpacingfloat, optional: Spacing in meter between each line.
zigzagbool, optional: If True then one survey out of two will be flipped. #TODO not implemented yet
ftypestr, optional: Type of the survey to choose which parser to use.
namestr, optional: Name of the merged 3D survey.

createBatchSurvey(dirname, ftype='Syscal', info={}, spacing=None, parser=None, isurveys=[], dump=None, debug=False)

Read multiples files from a folders (sorted by alphabetical order).

Parameters

dirnamestr: Directory with files to be parsed.
ftypestr, optional: Type of file to be parsed. Either ‘Syscal’ or ‘Protocol’.
infodict, optional: Dictionnary of info about the survey.
spacingfloat, optional: Electrode spacing to be passed to the parser function.
parserfunction, optional: A parser function to be passed to Survey constructor.
isurveyslist, optional: List of surveys index that will be used for error modelling and so reciprocal measurements. By default all surveys are used.
dumpfunction, optional: Function to dump the information message when importing the files.
debugbool, optional: If True informations about reciprocal computation, default filtering and so on will be displayed.

createMesh(typ='default', buried=None, surface=None, cl_factor=2, cl=-1, dump=None, res0=100, show_output=False, fmd=None, remote=None, refine=0, **kwargs)

Create a mesh.

Parameters

typstr, optional

Type of mesh. For 2D:

‘quad’: quadrilateral (fast to build)

‘trian’: triangular (fast to run) - default

‘circle’: close circular mesh

For 3D:

‘tetra’: tetrahedral mesh for half-space - default
‘cylinder’: column build with tetrahedral
‘prism’: column build with prism
‘tank’: closed geometry with tetrahedra

buriednumpy.array, optional

Boolean array of electrodes that are buried. Should be the same length as R2.elec

surfacenumpy.array, optional

Array with two or three columns x, y (optional) and elevation for additional surface points.

cl_factorfloat, optional

Characteristic length factor. Only used for triangular mesh to allow mesh to be refined close the electrodes and then expand.

clfloat, optional

Characteristic length that define the mesh size around the electrodes.

dumpfunction, optional

Function to which pass the output during mesh generation. print(): is the default.

res0float, optional

Starting resistivity for mesh elements.

show_outputbool, optional

If True, the output of gmsh will be shown on screen.

fmdfloat, optional

Depth of fine region specifies as a positive number relative to the mesh surface.

remotebool, optional

Boolean array of electrodes that are remote (ie not real). Should be the same length as Project.elec.

refineint, optional

Number times the mesh will be refined. Refinement split the triangles or the tetrahedra but keep the same number of parameter for the inversion. This helps having a more accurate forward response and a faster inversion (as the number of elements does not increase). Only available for triangles or tetrahedral mesh.

kwargs-

Keyword arguments to be passed to mesh generation schemes Specific for ‘tank mesh’:

originlist of 3 floats
Origin in X,Y,Z of one of the tank corner.

dimensionlist of 3 floats
Dimension from the corner on how to extend the tank.

Specific for ‘cylinder mesh’:

zlim : list of 2 int

For the bottom and top of the column along the Z axis.

createModel(ax=None, dump=None, typ='poly', addAction=None)

Interactive model creation for forward modelling.

Parameters

axmatplotlib.axes.Axes, optional: Axes to which the graph will be plotted.
dumpfunction, optional: Function that outputs messages from the interactive model creation.
typstr: Type of selection either poly for polyline or rect for rectangle.
addActionfunction: Function to be called once the selection is finished (design for GUI purpose).

Returns

figmatplotlib.figure: If ax is None, will return a figure.

createModelErrorMesh(**kwargs)

Create an homogeneous mesh to compute modelling error.

Same arguments as R2.createMesh().

createModelMesh(**kwargs)

Create a triangular mesh given the designed geometry by R2.designModel().

Parameters

All parameters to be passed are similar to `R2.createMesh()`.

createMultiMesh(runParallel=True, **kwargs)

Create multiple meshes from avalable Projects in self.projs.

Parameters

runParallelbool, optional: if True, mesh generation will run in multiple threads.
kwargs-: Keyword arguments to be passed to mesh generation schemes

createPseudo3DSurvey(dirname, lineSpacing=1, ftype='Syscal', parser=None, **kwargs)

Create a pseudo 3D survey based on 2D surveys. Multiple 2D Projects to be turned into a single pseudo 3D survey.: THIS WILL NEED CORRECT ELECTRODE LAYOUT - DONE IN self._updatePseudo3DSurvey()

Parameters

dirnamelist of str: List of 2D filenames in the right order for the grid or directory name (the files will be sorted alphabetically in this last case).
lineSpacingfloat, optional: Spacing in meter between each line.
ftypestr, optional: Type of the survey to choose which parser to use.
kwargs-: Keyword arguments to be passed to Project.createBatchSurvey()

createSequence(params=[('dpdp1', 1, 8)], seqIdx=None, *kwargs)

Creates a forward modelling sequence, see examples below for usage.

Parameters

paramslist of tuple, optional: Each tuple is the form (<array_name>, param1, param2, …) Types of sequences available are : ‘dpdp1’,’dpdp2’,’wenner_alpha’, ‘wenner_beta’, ‘wenner_gamma’, ‘schlum1’, ‘schlum2’, ‘multigrad’, ‘custSeq’. if ‘custSeq’ is chosen, param1 should be a string of file path to a .csv file containing a custom sequence with 4 columns (a, b, m, n) containing forward model sequence.
seqIdx: list of array like, optional: Each entry in list contains electrode indices (not label and string) for a given electrode string which is to be sequenced. The advantage of a list means that sequences can be of different lengths.

Examples

>>> k = Project()
>>> k.setElec(np.c_[np.linspace(0,5.75, 24), np.zeros((24, 2))])
>>> k.createMesh(typ='trian')
>>> k.createSequence([('dpdp1', 1, 8), ('wenner_alpha', 1), ('wenner_alpha', 2)]) # dipole-dipole sequence
>>> k.createSequence([('custSeq', '<path to sequence file>/sequence.csv')]) # importing a custom sequence
>>> seqIdx = [[0,1,2,3],[4,5,6,7],[8,9,10,11,12]]

createSequenceXBH(): Custom scheme for boreholes (not yet developed)

createSurvey(fname='', ftype='Syscal', info={}, spacing=None, parser=None, debug=True, **kwargs)

Read electrodes and quadrupoles data and return a survey object.

Parameters

fnamestr: Filename to be parsed.
ftypestr, optional: Type of file to be parsed. Either ‘Syscal’,’ProtocolDC’,’ResInv’, ‘BGS Prime’, ‘ProtocolIP’, ‘Sting’, ‘ABEM-Lund’, ‘Lippmann’ or ‘ARES’.
infodict, optional: Dictionnary of info about the survey.
spacingfloat, optional: Electrode spacing to be passed to the parser function.
parserfunction, optional: A parser function to be passed to Survey constructor.
debugbool, optional: If True, information about the reciprocal measurements, default filtering, etc. will be displayed.
**kwargs: Keyword arguments to be passed to Survey()

createTimeLapseSurvey(dirname, ftype='Syscal', info={}, spacing=None, parser=None, isurveys=[], dump=None, debug=False)

Read electrodes and quadrupoles data and return a survey object.

Parameters

dirnamestr or list of str: Directory with files to be parsed or list of file to be parsed.
ftypestr, optional: Type of file to be parsed. Either ‘Syscal’ or ‘Protocol’.
infodict, optional: Dictionnary of info about the survey. Put inverse_type = 1 to allow for a changing number of measurements between surveys.
spacingfloat, optional: Electrode spacing to be passed to the parser function.
parserfunction, optional: A parser function to be passed to Survey constructor.
isurveyslist, optional: List of surveys index that will be used for error modelling and so reciprocal measurements. By default all surveys are used.
dumpfunction, optional: Function to dump information message when importing the files.
debugbool, optional: If True informations about reciprocal computation, default filtering and so on will be displayed.

designModel(ax=None, dump=<built-in function print>, typ='poly', addAction=None, fmd=None)

Interactive model design for forward modelling (triangular only). As opposite to R2.createModel(). R2.designModel() allows to draw mesh region before meshing. This allows to have straight boundaries for triangular mesh.

Parameters

axmatplotlib.axes.Axes, optional: Axes to which the graph will be plotted.
dumpfunction, optional: Function that outputs messages from the interactive model creation.
typstr: Type of selection either poly for polyline or rect for rectangle.
addActionfunction: Function to be called once the selection is finished (design for GUI purpose).
fmdfloat, optional: Depth of of interest specifies as a relative positive number from the surface.

Returns

figmatplotlib.figure: If ax is None, will return a figure.

detectStrings(tolerance=5, max_itr=None)

Automatically detect electrode strings

Parameters

tolerancefloat, optional: Maximum (+/-) bearing (ie directional angle) tolerance each subsiquent electrode may have. The default is 5.
max_itrint, optional: Maximum number of searches that can be performed to find colinear nieghbouring electrodes. The default is None.

Returns

list (of list): Each entry in the list corresponds to an electrode string, and is a list of integers which are the indices of the respective electrodes in self.elec

Raises

ValueError: if the change in x and y direction for 2 neighbouring electrodes is the same. ie no 2 electrodes can occupy the same x y position in this code.
ValueError: if the change maxium number of searches is exceeded.

elec2distance(yDominant=False, iMoveElec=False)

Convert 3D electrode XY coordinates into just X coordinates. Use for 2D lines only! If self.elec has been set then each survey will use the electrodes set in the R2 master class. If not then the R2 master class will take on the elec values set for the first survey in a sequence.

Parameters

yDominant: bool, optional: If electrodes are prodimently spaced in the y direction then set yDominant to True.
iMoveElec: bool, optional: If moving electrodes are present then set to True, so that the same electrode positions are not given to each survey.

elec2horidist(): Convert 2D xz data into a true horizontal distance. Assumes that survey was done with a tape measure and the X distances are not true horizontal distance but distances measured along the ground.

estimateError(a_wgt=0.01, b_wgt=0.02)

Estimate reciprocal error data for data with no reciprocals for each survey, using the same routine present in R2. This allows for the additional inclusion of modelling errors. It could be used when the user want to assign invidual errors based on a_wgt/b_wgt. This action is irreversable.

Parameters

a_wgt: float, optional: a_wgt documented in the R2 documentation
b_wgt: float, optional: b_wgt documented in the R2 documentation

filterAppResist(index=-1, vmin=None, vmax=None)

Filter measurements by apparent resistivity for surface surveys

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).

filterContRes(index=-1, vmin=None, vmax=None)

Filter measurements by contact resistance if avialable.

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).

filterDCA(index=-1, dump=None)

Execute DCA filtering. Decay Curve Analysis (DCA) based on. Flores Orozco, A., Gallistl, J., Bücker, M., & Williams, K. H. (2017)., Decay curve analysis for data error quantification in time-domain induced polarization imaging., Geophysics, 83(2), 1–48. https://doi.org/10.1190/geo2016-0714.1

Parameters

indexint, optional: Index of the survey to use for processing. Default index == -1 will apply the processing to all surveys.
dumpfunction, optional: Function onto pass the progress.

filterDummy(index=-1)

Remove measurements where abs(a-b) != abs(m-n) (likely to be dummy measurements added for speed).

Parameters

indexint, optional: Index of the survey to process. If index == -1 (default) then the processing is applied on all survey independantly.

filterElec(elec=[], index=-1)

Filter out measurements associated with specific electrodes.

Parameters

eleclist: List of electrode number to be removed.
indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).

filterInvError(index=-1, vmin=None, vmax=None)

Remove measurements where inversion error is outside of the defined range.

Parameters

vminfloat, optional: minimum value of normalized error below which data will be discarded.
vmaxfloat, optional: maximum value of normalized error above which data will be discarded.
indexint, optional: Index of the survey to process. If index == -1 (default) then the processing is applied on all survey independantly.

filterManual(index=-1, ax=None, **kwargs): Interactive manually filters the data visually. The manually selected points index are stored in Survey.iselect or Survey.eselect``if it is an electrodes. Use `Survey.filterData() to filter them out for a single survey. Or R2._filterSimilarQuads() to filter quadrupoles amongs all R2.surveys.

filterNegative(): Remove negative apparent resistivty values

filterNested(index=-1)

Removes nested measurements: Where M or N are in between A and B.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.

filterRangeIP(index=-1, phimin=None, phimax=None)

Filter IP data according to a specified range.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly.
phiminfloat, optional: Minimium phase angle [mrad].
phimaxfloat, optional: Maximum phase angle [mrad].

filterRecip(percent=20, index=-1)

Filter on reciprocal errors.

Parameters

indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).
percentfloat, optional: Percentage of reciprocal error above witch a measurement will be discarded. 20% by default.

filterRecipIP(index=0): Remove reciprocal for IP data ONLY. Additional arguments to be passed to :func: ~resipy.Survey.filterRecipIP.

filterStack(percent=2, index=-1)

Filter on stacking (dev) errors.

Parameters

indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).
percentfloat, optional: Percentage of stacking error above witch a measurement will be discarded. 2% by default.

filterTransferRes(index=-1, vmin=None, vmax=None)

Filter measurements by transfer resistance.

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).

filterUnpaired(index=-1)

Remove quadrupoles that don’t have reciprocals. This might remove dummy measurements added for sequence optimization.

Parameters

indexint, optional: Index of the survey on which to apply the processing. If the processing is to be applied to all surveys then specifiy index=-1 (default).

filterZeroMeasSurveys(): Filter out badly behaved surveys, where after all other QC no measurements are actually left.

fitErrorLME(index=-1, ax=None, rpath=None, iplot=True)

Fit a linear mixed effect (LME) model by having the electrodes as as grouping variables.

Parameters

Index of the survey to fit. If `index == -1` (default) then the fit: is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.
axmatplotlib.Axes, optional: If specified, the graph will be plotted against this axis, otherwise a new figure will be created.
rpathstr, optional: Path of the directory with R (for Windows only).
iplotbool, optional: If True plot it.

fitErrorLin(index=-1, ax=None)

Fit a linear relationship to the resistivity data.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorParabolaIP(index=-1, ax=None)

Plot the reciprocal phase errors with a parabola fit.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorPwl(index=-1, ax=None)

Fit an power law to the resistivity data.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorPwlIP(index=-1, ax=None)

Plot the reciprocal phase errors with a power-law fit.

Parameters

indexint, optional: Index of the survey to fit. If index == -1 (default) then the fit is done on all surveys independantly. If ìndex == -2 then the fit is done on the combined surveys.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fixLegendItems(ax)

Display legend items with survey names in the case of fitting individual error models to multiple data sets.

Parameters

axmatplotlib axes: Axes handle with reciprocal error plots in it.

forward(noise=0.0, noiseIP=0.0, iplot=False, dump=None)

Operates forward modelling.

Parameters

noisefloat, optional 0% <= noise <= 100%: Noise level in percent from a Gaussian distribution that should be applied on the forward apparent resistivities obtained.
noiseIPfloat, optional: Absolute noise level in mrad from a Gaussian distribution that should be applied on the forward phase values obtained.
iplotbool, optional: If True will plot the pseudo section after the forward modelling.
dumpfunction, optional: Function to print information messages when running the forward model.

generateElec(nb=24, dx=0.5, dz=0, nline=1, lineSpacing=2)

Generate electrodes positions for 2D and 3D surveys.

Parameters

nbint, optional: Number of electrodes per line. For 3D survey, if multiple lines, the total number of electrodes will be nb x nline.
dxfloat, optional: Spacing in meters between electrodes in the X direction.
dzfloat, optional: Increment in the Z direction (elevation) between consecutive electrodes.
nlineint, optional: Number of lines. 1 for 2D and multiple for 3D.
lineSpacingfloat, optional: Spacing between lines (3D only).

getR2out()

Reat the .out file and parse its content.

Returns

Dataframe with the dataset name, and the RMS decrease for each iteration.

getResults(dirname=None)

Collect inverted results after running the inversion and adding them to R2.meshResults list.

Parameters

dirnamestr, optional: If specified, dirname will be used as the working directory (this is needed for R2.loadResults()). Default is self.dirname.

hasElecString()

Determine if a electrode strings are present in the electrode labels

Returns

bool: True if strings present in electrode label

importElec(fname='')

Import electrodes positions.

Parameters

fnamestr: Path of the CSV (or file containing the electrodes positions. It should contains 3 columns maximum with the X, Y, Z positions of the electrodes.

importMesh(file_path, mesh_type=None, node_pos=None, elec=None, order_nodes=True, res0=100)

Import mesh from .vtk / .msh / .dat, rather than having ResIPy create one for you.

Parameters

file_pathstr: File path mapping to the mesh file
mesh_typestr: Not used anymore.
node_posarray like, optional: Array of ints referencing the electrode nodes. If left as none no electrodes will be added to the mesh class. Consider using mesh.moveElecNodes() to add nodes to mesh using their xyz coordinates.
elecarray, optional: N*3 numpy array of electrode x,y,z coordinates. Electrode node positions will be computed by finding the nearest nodes to the relevant coordinates.
res0float, optional: Starting resistivity for mesh elements.

importPseudo3DElec(fname='')

Import electrodes positions. The label columns should include line number separated by space (like in 3D):

label,x,y,z 1 3,0,0,0 1 4,1,1,0 1 5,1,2,1

Parameters

fnamestr: Path of the CSV file containing the electrodes positions. It should contains 3 columns maximum with the X, Y, Z positions of the electrodes.

importSequence(fname='')

Import sequence for forward modelling.

Parameters

fnamestr: Path of the CSV file to be imported. The file must have 4 columns with headers (a, b, m, n) containing 4 electrodes numbers.

invert(param={}, iplot=False, dump=None, modErr=False, parallel=False, iMoveElec=False, ncores=None, rmDirTree=True, modelDOI=False)

Invert the data, first generate R2.in file, then run inversion using appropriate wrapper, then return results.

Parameters

paramdict, optional: Dictionary of parameters for inversion. Will be passed to R2.write2in().
iplotbool, optional: If True, will plot the results of the inversion using R2.showResults().
dumpfunction, optinal: Function to print the output of the inversion. To be passed to R2.runR2().
modErrbool, optional: If True, the model error will be compute and added before inversion.
parallelbool, optional: If True, batch and time-lapse survey will be inverted in //. No output will be display during inversion.
iMoveElecbool, optional: If True, then different electrode location will be used for the different surveys. Electrodes location are specified in the Survey object. Only for parallel inversion for now.
ncoresint, optional: If parallel==True then ncores is the number of cores to use (by default all the cores available are used).
rmDirTreebool, optional: Remove excess directories and files created during parallel inversion
modelDOIbool, optional: If True, the Depth of Investigation will be model by reinverting the data on with an initial res0 different of an order of magnitude. Note that this option is only available for single survey.

invertPseudo3D(invLog=None, runParallel=False, **kwargs)

Run pseudo3D inversions.

Parameters

invLogfunction, optional: Passes project inversion outputs.
runParallelbool: if True, inversions will run in parallel based on number of CPU cores.
kwargs-: Keyword arguments to be passed to invert().

loadProject(fname)

Load data from project file.

Parameters

fnamestr: Path where the file will be saved.

loadResults(invdir)

Given working directory, will attempt to load the results of an already run inversion.

Parameters

invdirstr: Path to the inversion directory.

matchSurveys(): Will trim all surveys to get them ready for difference inversion where all datasets must have the same number of quadrupoles.

mergeElec(dist=-1)

Merge electrodes that have less than a certain distance to eache other

Parameters

distfloat, optional: maximum distance of close electrodes in meters (electrodes that have a distance less than dist will be merged) -1 flag for auto calculation where dist = average(electrode spacing)/100

Returns

bool: True: merge successful False: merge unsuccessful

modelDOI(dump=None): Will rerun the inversion with a background constrain (alpha_s) with the normal background and then a background 10 times more resistive. From the two different inversion a senstivity limit will be computed.

normElecIdx(): Normalise electrode indexes to start at 1 in consective and ascending order.

resetRegions(): Just reset all regions already drawn. Shouldn’t be needed as the self.runR2() automatically use a homogenous model when starting for inversion. The only purpose of this is to use an inhomogeous starting model to invert data from forward modelling.

runParallel(dirname=None, dump=None, iMoveElec=False, ncores=None, rmDirTree=True)

Run several instances of R2 in parallel according to the number of cores available.

Parameters

dirnamestr, optional: Path of the working directory.
dumpfunction, optional: Function to be passed to R2.runR2() for printing output during inversion.
iMoveElecbool, optional: If True will move electrodes according to their position in each Survey object.
ncoresint, optional: Number or cores to use. If None, the maximum number of cores available will be used.
rmDirTree: bool, optional: Remove excess directories and files created during parallel. Default is True.

runR2(dirname='', dump=None)

Run the executable in charge of the inversion.

Parameters

dirnamestr, optional: Path of the directory where to run the inversion code.
dumpfunction, optional: Function to print the output of the invrsion code while running.

saveData(outputdir)

Save all data (_res.dat, .vtk, …) from the working directory generated during inversion to the designated directory.

Parameters

outputdirstr: Path to the directory to save the files.

saveErrorData(fname)

Save quadruople, resistance, phase and their respective reciprocal errors as .csv file.

Parameters

fnamestr: Path where to save the file.

saveFilteredData(fname, savetyp='Res2DInv (*.dat)')

Save filtered data in formats to be used outside ResIPy (e.g. Res2DInv).

Parameters

fnamestr: Path where to save the file.
savetypstr, optional: Saving format. To be determined in GUI. Default: Res2DInv (.dat)

saveForwardModelResult(fname)

Save the result of a forward model run to a specific file name/

Parameters

fnamestr: path to file.

saveInvPlots(outputdir=None, **kwargs)

Save all plots to output (or working directory). Parameters are passed to the showResults() method.

Parameters

outputdirstr, optional: Path of the output directory. Default is the working directory.

saveMesh(outputname=None)

Save mesh as .vtk to be viewed in paraview.

Parameters

outputnamestr, optional

Output path with extension. Available mesh format are:

.vtk (Paraview)
.node (Tetgen)
.dat (R* codes)

If not provided the mesh is saved in the working directory as mesh.vtk.

saveMeshVtk(outputname=None)

Save mesh as .vtk to be viewed in paraview.

Parameters

outputnamestr, optional: Output path of the .vtk produced. By default the mesh is saved in the working directory self.dirname as mesh.vtk.

saveProject(fname): Save the current project will all dataset in custom ResIPy format (.resipy) for future importation.

saveSequence(fname='')

Save sequence as .csv file.

Parameters

fnamestr, optional: Path where to save the sequence.

saveVtks(dirname=None)

Save vtk files of inversion results to a specified directory.

Parameters

dirname: str: Directory in which results will be saved. Default is the working directory.

setBorehole(val=False): Set all surveys in borehole type if True is passed.

setElec(elec, elecList=None)

Set electrodes. Automatically identified remote electrode.

Parameters

elecnumpy array: Array of NxM dimensions. N = number of electrodes, M = 2 for x,z or M = 3 if x,y,z coordinates are supplied.
elecListlist, optional: If not None then elec is ignored in favor of elecList. This option is to be used in the advanced use case where electrodes move which each survey. Each entry of the list is a numpy array the same format of ‘elec’, which is then assigned to each survey class.

static setNcores(ncores)

Set the number of cores to use for big calculations, for now this value only to mesh generation and calculations done on 3D meshes.

Parameters

ncoresint: Number of cores to use
Raises
——
EnvironmentError: Raised if ncores is more than that avialable

setPseudo3DElec(elec)

Set pseudo 3D electrodes (with an electrode label as:: <line number> <electrode number>).

Parameters

elecListlist of dataframes, optional: List of electrodes dataframes - each df must have 2D like XYZ (rotated to have y=0).

setRefModel(res0)

Set the reference model according to a previous inversion, avoids the need to invert reference model again for timelapse workflows. In contrast to R2.setStartingRes() which assign resistivity to group of elements, this method requires a vector of the same length as the number of elements. This enables, notably to manually perform consecutive background constrained inversion.

Parameters

res0: array like: Array of resistivity values, ideally from a previous inversion. The length of this array should be the same as the number of elements.

setStartingRes(regionValues={}, zoneValues={}, fixedValues={}, ipValues={})

Assign starting resitivity values.

Parameters

regionValuesdict, optional: Dictionnary with key being the region number and the value being the resistivity in [Ohm.m].
zoneValuesdict, optional: Dictionnary with key being the region number and the zone number. There would be no smoothing between the zones if ‘block inversion’ is selected (inversion_type = 4).
fixedValuesdict, optional: Dictionnary with key being the region number and a boolean value if we want to fix the resistivity of the zone to the starting one. Note that it only works for triangular mesh for now.
ipValuesdict, optional: Dictionnary with key being the region number and the values beeing the phase [mrad].

setTitle(linetitle): Set the title of the survey name when inverting data. Input is a string.

setwd(dirname)

Set the working directory.

Parameters

dirnamestr: Path of the working directory.

showError(index=0, ax=None)

Plot the reciprocal errors.

Parameters

indexint, optional: Index of the survey to plot. If index == -1 then all combined data of all survey will be plotted together. Default is to plot the first survey (index==0).
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

showErrorDist(index=0, ax=None)

Calculate and plots reciprocal error probablity histogram. Good data will have a bell shape (normal) distribution where most datapoints have near zero reciprocal error.

Parameters

indexint, optional: Index of the survey to plot. Default is first survey index == 0. If index == -2 then the error distribution of the combined data will be plotted.
axMatplotlib.Axes: If specified, the graph will be plotted against it.

showErrorIP(index=0, ax=None)

Plot the reciprocal phase discrepancies against the reciprocal mean transfer resistance.

Parameters

indexint, optional: Index of the survey to show. Default is the first survey index == 0. If ìndex == -2 then the combined data from all surveys are shown.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib.Figure, optional: If ax is not specified, the function will return a figure object.

showHeatmap(index=0, ax=None)

Plot a phase heatmap (x = M, y = A and value = -phi) based on: Orozco, A. F., K. H. Williams, and A. Kemna (2013), Time-lapse spectral induced polarization imaging of stimulated uranium bioremediation, Near Surf. Geophys., 11(5), 531–544, doi:10.3997/1873-0604.2013020)

Parameters

indexint, optional: Index of the survey to fit. Default is the first survey index == 0.
axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

showInParaview(index=0, paraview_loc=None)

Open paraview to display the .vtk file.

Parameters

index: int, optional: Timestep to be shown in paraview (for an individual survey this 1).
paraview_loc: str, optional: Windows ONLY maps to the excuatable paraview.exe. The program will attempt to find the location of the paraview install if not given.

showInvError(index=0, ax=None)

Display inversion error by measurment numbers.

Parameters

indexint, optional: Index of survey (if time-lapse or batch). Default index == 0.
axmatplotlib axis: If provided, the graph will be plotted against this axis.

showIter(index=-2, ax=None, modelDOI=False, cropMaxDepth=False)

Dispay temporary inverted section after each iteration.

Parameters

indexint, optional: Iteration number to show.
axmatplotib axis, optional: If specified, the graph will be plotted along ax.
modelDOIbool, optional: As modelDOI() is always computed using R2 (not cR2), this tells the method to look for an R2 looking iteration file.
cropMaxDepthbool, optional: if True, below max depth will be cropped

showMesh(ax=None, **kwargs): Display the mesh and handles best default values.

showMeshInParaview(paraview_loc=None)

Show the mesh in paraview (mostly useful for 3D surveys.

Parameters

paraview_loc: str, optional: Windows ONLY maps to the excuatable paraview.exe. The program will attempt to find the location of the paraview install if not given.

showParam(): Print parameters in R2.param dictionary.

showPseudo(index=0, vmin=None, vmax=None, ax=None, **kwargs)

Plot pseudo-section with dots.

Parameters

indexint, optional: Index of the survey to be used for the pseudo-section (in case of timelapse or batch).
vminfloat, optional: Minimum value for colorscale.
vmaxfloat, optional: Maximum value for colorscale.
axmatplotlib.Axes, optional: If specified, axis along which to plot the graph.
**kwargsoptional: Passed to Survey.showPseudo().

showPseudo3DMesh(ax=None, color_map='Greys', meshList=None, cropMesh=True, color_bar=False, returnMesh=False, cropMaxDepth=False, clipCorners=False, pvshow=True, **kwargs)

Show 2D meshes in 3D view

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.
color_mapstr, optional: Name of the colormap to be used.
meshListlist of Mesh classes: If not None, pseudo 3D meshes will be plotted by default.
cropMeshbool, optional: If True, 2D mesh will be bound to electrodes and zlim.
color_barBoolean, optional: True to plot colorbar.
returnMesh: bool, optional: if True method returns a merged mesh.
cropMaxDepthbool, optional: If True, region below fine mesh depth (fmd) will be cropped.
clipCornersbool, optional: If ‘True’, triangles from bottom corners will be cropped (only if the whole mesh is not shown).
pvshowbool, optional: Set to False to not call Plotter.show() (useful for subplots).
kwargs-: Keyword arguments to be passed to Mesh.show() class.

showPseudo3DResults(cropMesh=False, **kwargs)

Show 2D Inversions in 3D view

Parameters

cropMeshbool, optional: If True, 2D mesh will be bound to electrodes and zlim.
kwargs-: Keyword arguments to be passed to showPseudo3DMesh().

showPseudoIP(index=0, vmin=None, vmax=None, ax=None, **kwargs)

Plot pseudo-section with dots for IP data.

Parameters

indexint, optional: Index of the survey to be used for the pseudo-section (in case of timelapse or batch).
vminfloat, optional: Minimum value for colorscale.
vmaxfloat, optional: Maximum value for colorscale.
axmatplotlib.Axes, optional: If specified, axis along which to plot the graph.
**kwargsoptional: Passed to Survey.showPseudoIP().

showPseudoInvError(index=0, ax=None, vmin=None, vmax=None, elec=True)

Plot pseudo section of errors from file f001_err.dat.

Parameters

indexint, optional: Index of the survey (if time-lapse or batch). Default index == 0.
axmatplotlib axis: If specified, the graph will be plotted against ax.
vminfloat, optional: Min value.
vmaxfloat, optional: Max value.
elecbool, optional: If True, the electrodes are displayed and can be used for filtering.

showPseudoInvErrorIP(index=0, ax=None, vmin=None, vmax=None)

Display normalized phase error.

Parameters

indexint, optional: Index of the survey (if time-lapse or batch). Default index == 0.
axmatplotlib axis: If specified, the graph will be plotted against ax.
vminfloat, optional: Min value.
vmaxfloat, optional: Max value.

showRMS(index=0, ax=None)

Show the RMS decrease for each iteration.

Parameters

indexint, optional: Index of the dataset for which to plot the RMS.
axmatplotlib axis, optional: If provided, the graph will be plotted against it.

showResults(index=0, ax=None, edge_color='none', attr='', sens=True, color_map='viridis', zlim=None, clabel=None, doi=False, doiSens=False, contour=False, cropMaxDepth=True, clipContour=True, clipCorners=False, use_pyvista=True, background_color=(0.8, 0.8, 0.8), pvslices=([], [], []), pvspline=None, pvthreshold=None, pvgrid=True, pvcontour=[], pvdelaunay3d=False, **kwargs)

Show the inverteds section.

Parameters

indexint, optional: Index of the inverted section (mainly in the case of time-lapse inversion). If index == -1, then all 2D survey will be plotted on a 3D grid.
axmatplotlib axis, optional: If specified, the inverted graph will be plotted agains ax.
edge_colorstr, optional: Color of the edges of the mesh.
attrstr, optional: Name of the attribute to be plotted.
sensbool, optional: If True and if sensitivity is available, it will be plotted as a white transparent shade on top of the inverted section.
color_mapstr, optional: Name of the colormap to be used.
clabelstr, optional: Label of the colorbar (by default the label is the value of attr).
doibool, optional: If True, it will draw a dotted red line corresponding to 0.02 from the Oldenburg and Li method. Note that R2.modeDOI() needs to be run for that.
doiSensbool, optional: If True, it will draw a dashed line corresponding to 0.001 of the maximum of the log10 sensitivity.
contourbool, optional: If True, contours will be plotted.
cropMaxDepthbool, optional: If True, the mesh will be clipped with at a depth following the surface. If False, the mesh will be clipped at the maximum depth available. This doesn’t have any effect if clipContour is False.
clipContourbool, optional: If True, the contour of the area of interest will be clipped (default).
clipCornersbool, optional: If ‘True’, triangles from bottom corners will be cropped (only if the whole mesh is not shown).
use_pyvistabool, optional: (3D only) Use visual toolkit backend for displaying 3D mesh, note that pyvista must be installed for this to work.
background_colortuple, optional: (3D only) Background color assigned to pyvista plotter object when created. Not yet supported for matplotlib axis handles.
pvslicestuple of list of float, optional: (3D only) Determine the X, Y, Z slices. e.g.: ([3], [], [-3, -4]) will add a slice normal to X in 3 and two slices normal to Z in -3 and -4.
pvspline‘elec’ or numpy array, optional: (3D only) If ‘elec’ mesh will be sliced along the electrodes path otherwise an array of X, Y, Z of points on a path to slice the mesh along that path is needed.
pvthresholdlist of two floats, optional: (3D only) Keep values between pvthreshold[0] and pvthreshold[1].
pvgridbool, optional: (3D only) Show grid or not.
pvcontour: list of float, optional: (3D only) Values of the isosurface to be plotted.
pvdelaunay3dbool, optional: If True a “Delaunay 3D” triangulation filter will be applied on the mesh.

showSlice(index=0, ax=None, attr=None, axis='z', vmin=None, vmax=None)

Show slice of 3D mesh interactively.

Parameters

indexint, optional: Index of the survey. Default is first survey (index == 0).
axmatplotlib.Axes, optional: Axis on which to plot the graph.
attrstr, optional: Attribute to plot. Default is ‘Resistivity(ohm.m)’.
axisstr, optional: Either ‘x’, ‘y’, or ‘z’ (default).
vminfloat, optional: Minimum value for colorbar.
vmaxfloat, optional: Maximum value for colorbar.

split3DGrid(elec=None, changeLabel=True)

Split self.elec to available lines based on ‘label’

Parameters

elecdataframe, optional: Contains the electrodes information. “label” column must be provided and have “<line number> <electrode number>” format.
changeLablebool, optional: If True, the line number will be dropped from labels - Flase for GUI related surveys.

Returns

elecListlist of dataframes: List of electrodes dataframes - each df can have a 3D like XYZ.

static topo2distance(x, y, z): Convert 3d xy data in pure x lateral distance. Use for 2D data only!

write2in(param={})

Create configuration file for inversion. Write mesh.dat and res0.dat.

Parameters

paramdict: Dictionnary of parameters and values for the inversion settings.

write2protocol(err=None, errTot=False, fm0=None, **kwargs)

Write a protocol.dat file for the inversion code.

Parameters

errbool, optional: If True error columns will be written in protocol.dat provided an error model has been fitted or errors have been imported.
errTotbool, optional: If True, it will compute the modelling error due to the mesh and add it to the error from an error model.
fm0numpy.array of float, optional: Only for 3D time-lapse with reg_mode == 2 (difference inversion). Response of the inverted reference survey according to sequence of the reference survey as transfer resistance (Ohm).
**kwargsoptional: To be passed to Survey.write2protocol().

class resipy.Project.R2(*args, **kwargs)

class resipy.Project.cd(newPath): Context manager for changing the current working directory

resipy.Project.cudaRm(invdir)

Compute Resolution and Covariance matrix for 2D problems using nVIDIA GPU.

Parameters

invdirstring: Inversion directory used by R2.

Returns

covarnd array: Values along the diagonal of the coviarance matrix.
rematnd array: Values along the diagonal of the Resolution matrix..

resipy.Project.getSysStat()

Return processor speed and usage, and free RAM and usage.

Returns

cpu_speed: float: in Mhz.
cpu_usage: float: in percent.
ram_avail: float: avialable memory.
ram_usage: float: in percent.

resipy.Project.parallelRm(invdir)

Compute Resolution and Covariance matrix for 2D problems using multicore CPU. Behaves the same as cudaRm but uses numpy / openBlas.

Parameters

invdirstring: Inversion directory used by R2.

Returns

covarnd array: Values along the diagonal of the coviarance matrix.
rematnd array: Values along the diagonal of the Resolution matrix..

resipy.Project.systemCheck(dump=<built-in function print>)

Performs a simple diagnostic of the system, no input commands needed. System info is printed to screen, number of CPUs, memory and OS. This check is useful for parallel processing.

Parameters

dumpfunction: stdout pointer

Returns

system_info: dict: Dictionary keys refer information about the system

Created on Fri Jun 1 11:21:54 2018

@author: ResIPy’s core developers

class resipy.Survey.Survey(fname=None, ftype='', df=None, elec=None, name='', spacing=None, parser=None, keepAll=True, debug=True, compRecip=True)

Class that handles geophysical data and some basic functions. One instance is created for each survey.

Parameters

fnamestr: Name of the file where the data are.
ftypestr: Type of the data file. This setting is not read if a parser is not None.
dfpandas.DataFrame, optional: Pandas dataframe with ‘a’,’b’,’m’,’n’ columns as string and at least a column ‘resist’ as float. Can be provided alternatively to fname.
elecpandas.DataFrame, optional: Pandas dataframe with ‘x’,’y’,’z’,’buried’,’remote’ columns. ‘x’,’y’,’z’ as float, ‘buried’ and ‘remote’ as bool. Should be provided alternatively to fname.
namestr: A personal name for the survey.
spacingfloat, optional: This will be passed to the parser function to determine the electrode positions.
parserfunction, optional: If provided, it should return tuple containing elec a 3 columns array containing electrodes position and data a pandas.DataFrame with the a,b,m,n,resist columns at least and ip if present.
keepAll: bool, optional: If True will keep all the measurements even the ones without reciprocal. Note that if none of the quadrupoles have reciprocal they will all be kept anyway.
compRecip: bool, optional: Compute reciprocal errors, default is True.

addData(fname, ftype='Syscal', parser=None): Add data to the actual survey (for instance the reciprocal if they are not in the same file).

addFilteredIP(): Add filtered IP data after IP filtering and pre-processing. This is because the IP filtering is done on a different dataframe and only merged when called this method.

addPerError(pnct=2.5)

Add a flat percentage error to resistivity data.

Parameters

pnct: float: Error in percent

checkTxSign(): Checking the sign of the transfer resistances (2D survey only !).

computeK(): Compute geomatrix factor (assuming flat 2D surface) and store it in self.df[‘K’].

computeKborehole(Gl=None): Compute geometric factor for a borehole survery assuming a flat 2D surface. Gl = ground level.

computeReciprocal()

Compute reciprocal measurements.

Notes

The method first sorts the dipole AB and MN. Then efficiently searches for reciprocal pairs with a bisection search.

computeReciprocal2()

Compute reciprocal measurements.

Notes

The method first sorts the dipole AB and MN. Then creates a reciprocal quadrupole matrix. These matrices are then used with numpy.equal to produce a 2D matrix from which reciprocal are extracted.

computeReciprocal3(): Compute reciprocal measurements using pandas.merge(). TODO Notes —– The method first sorts the dipole AB and MN. Then creates a reciprocal quadrupole matrix. These matrices are then used with numpy.equal to produce a 2D matrix from which reciprocal are extracted.

elec2distance(): Convert 3d xy data in pure x lateral distance. Use for 2D data only!

elec2horidist(): Convert 2D xz data into a true horizontal distance. Assumes that survey was done with a tape measure and the X distances are not true horizontal distance but distances measured along the ground.

estimateError(a_wgt=0.01, b_wgt=0.02)

Estimate reciprocal error data for data with no reciprocals, following the same routine present in R2. This allows for the additional inclusion of modelling errors.

Parameters

a_wgt: float, optional: a_wgt documented in the R2 documentation
b_wgt: float, optional: b_wgt documented in the R2 documentation

exportSrv(fname=None): Export .srv format for which is compatible with E4D. The e4d survey file includes the electrode locations, in addition to the scheduling matrix.

filterAppResist(vmin=None, vmax=None, debug=True)

Filter measurements by apparent resistivity for surface surveys

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
debugbool, optional: Print output to screen. Default is True.

filterContRes(vmin=None, vmax=None, debug=True)

Filter measurements by transfer resistance.

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
debugbool, optional: Print output to screen. Default is True.

filterDCA(dump=None)

Parameters

dumpfunction, optional: Callback function to print the progress in percent.

filterData(i2keep)

Filter out the data not retained in i2keep.

Parameters

i2keepndarray of bool: Index where all measurement to be retained are True and the others False.

filterDefault(): Remove NaN, Inf and duplicates values in the data frame.

filterDummy(): Remove measurements where abs(a-b) != abs(m-n) (likely to be dummy measurements added for speed).

filterElec(elec=[], debug=True)

Filter out specific electrodes given.

Parameters

eleclist: List of electrode number to be removed.
debugbool, optional: Print output to screen. Default is True.

filterInvError(vmin=None, vmax=None, debug=False)

Filter measurements by inversion error.

Parameters

vminfloat, optional: Minimum error.
vmaxfloat, optional: Maximum error.
debugbool, optional: Print output to screen. Default is False.

filterManual(attr='app', ax=None, log=False, label=None, vmin=None, vmax=None, elec=True, darkMode=False)

Manually filters the data visually. The points manually selected are flagged in the Survey.iselect vector and can subsequently be removed by calling Survey.filterData(~Survey.iselect).

Parameters

attrstr, optional: Columns of Survey.df to use for plotting. Default is app (apparent resistivity).
axmatplotlib axis, optional: If specified, the graph is plotted along the axis.
logbool, optional: If True then all data will be log transformed.
labelstr, optional: Label of the colorbar. If None, will be given from the ‘attr’ argument.
vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
elecbool, optional: If True, the electrodes are shown and can be used for filtering.
darkModebool, optional: If true, electrodes wil be plotted in white, else black

filterNegative(): Remove negative apparent resistivty values

filterNested(): Removes nested measurements: Where M or N are in between A and B

filterRangeIP(phimin, phimax)

Filter IP data according to a specified range.

Parameters

phiminfloat: Minimium phase angle [mrad].
phimaxfloat: Maximum phase angle [mrad].

filterRecip(percent=20, debug=True)

Filter measurements based on the level reciprocal error.

Parameters

percentfloat, optional: Percentage level of reciprocal error in which to filter the measurements. Percentage Errors > percentage will be removed. By default the value is 20.
debugbool, optional: Print output to screen. Default is True.

filterRecipIP(): Removing reciprocal measurements from dataset - only for visualization purposes on heatmap()

filterStack(percent=2, debug=True)

Filter measurements based on the stacking error.

Parameters

percentfloat, optional: Percentage level of stacking error in which to filter the measurements. Percentage Errors > percentage will be removed. By default the value is 2.
debugbool, optional: Print output to screen. Default is True.

filterTransferRes(vmin=None, vmax=None, debug=True)

Filter measurements by transfer resistance.

Parameters

vminfloat, optional: Minimum value.
vmaxfloat, optional: Maximum value.
debugbool, optional: Print output to screen. Default is True.

filterUnpaired(): Remove quadrupoles that don’t have a reciprocals. This might remove dummy measurements added for sequence optimization.

fitErrorLME(iplot=True, ax=None, rpath=None)

Fit a linear mixed effect (LME) model by having the electrodes as as grouping variables.

Parameters

iplotbool, optional: If True, then a graph will be plotted.
axmatplotlib.Axes, optional: If specified, the graph will be plotted against this axis, otherwise a new figure will be created.
rpathstr, optional: Path of the directory with R (for Windows only).

fitErrorLin(ax=None)

Fit a linear relationship to the resistivity data.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorParabolaIP(ax=None)

Plot the reciprocal phase errors with a parabola fit.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorPwl(ax=None)

Fit an power law to the resistivity data.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

fitErrorPwlIP(ax=None)

Plot the reciprocal phase errors with a power-law fit.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

hasElecString()

Determine if a electrode strings are present in the electrode labels

Returns

bool: True if strings present in electrode label

static logClasses3(datax, datay, func, class1=None)

Perform a log class of datay based on datay and applied function func to each bin.

Parameters

dataxarray: x values to be from which the log-classes will be made.
datayarray: y values to which the function func will be applied inside each log-class
funcfunction: Function to be applied to the y value of each log class.
class1array, optional: Array of values for the log classes. If given, the limit of the classes will be computed as 10**class1

Returns

mbinsarray: x-means of each bin.
vbinsarray: Value of each bin (output of the function func).
nbinsarray: Number of measurements in each bin.

normElecIdx(debug=True)

Normalise the electrode indexing sequencing to start at 1 and ascend consectively (ie 1 , 2 , 3 , 4 … )

Function firstly normalises all indexes so that the lowest electrode number is 1. Then removes jumps in the electrode indexing.

Parameters

debugbool, optional: Output will be printed to console if True.

normElecIdxwSeq(expected=None)

Normalise the electrode indexing sequencing to start at 1 and ascend consectively (ie 1 , 2 , 3 , 4 … ). Also checks for any electrodes which are missing out of sequence if an expected sequence is given.

Function firstly normalises all indexes so that the lowest electrode number is 1. Then removes jumps in the electrode indexing.

Parameters

expectedarray like: Expected sequence.

static numFormating(numList)

Formats numbers between -1 to 1 based on their decimals. e.g., 0.00001 would be 1e-5 while 0.1 would remain 0.1

Parameters

numList: list of floats

showError(ax=None)

Plot the reciprocal errors.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

showErrorDist(ax=None)

Calculate and plots reciprocal error probablity histogram. Good data will have a bell shape (normal) distribution where most datapoints have near zero reciprocal error.

Parameters

axMatplotlib.Axes: If specified, the graph will be plotted against it.

showErrorIP(ax=None)

Plot the reciprocal phase discrepancies.

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

showHeatmap(ax=None)

Plot a phase heatmap (x = M, y = A and value = -phi) based on:: Orozco, A. F., K. H. Williams, and A. Kemna (2013), Time-lapse spectral induced polarization imaging of stimulated uranium bioremediation, Near Surf. Geophys., 11(5), 531–544, doi:10.3997/1873-0604.2013020)

Parameters

axmatplotlib axis, optional: If specified, graph will be plotted on the given axis.

Returns

figmatplotlib figure, optional: If ax is not specified, the function will return a figure object.

showPseudo(ax=None, bx=None, threed=False, **kwargs): Plot pseudo section if 2D survey or just quadrupoles transfer resistance otherwise.

showPseudoIP(ax=None, bx=None, threed=False, **kwargs): Plot pseudo section if 2D survey or just quadrupoles phase otherwise.

swapIndexes(old_indx, new_indx)

Replace the electrode number in a sequence matrix with another. Survey dataframe is updated after running.

Parameters

old_idxint: Electrode number(or index) to be replaced
new_idxint: Replacement electrode number

write2protocol(outputname='', err=False, errTot=False, ip=False, res0=False, isubset=None, threed=False, fm0=None)

Write a protocol.dat file for R2, cR2, R3t, cR3t.

Parameters

outputnamestr, optional

Path of the output file.

errbool, optional: If True, then the resError and phaseError (if IP present) will be used in the protocol.dat file.
errTotbool, optional: If True, the modelling error will be added to the error from the error model to form the total error.
ipbool, optional: If True and IP columns will be added to the file.
res0bool, optional: For time-lapse inversion, the background resistivity will be added if True.
isubsetarray_like of bool, optional: If specified, it will be used to take a subset of the original array. It can be used for difference inversion to take measurements in common between all the surveys.
threedbool, optional: If True, it’s for a 3D survey (and then add line numbers) or for a 2D survey (default).

fm0numpy.array of float, optional

Only for 3D timelapse, to compute d-d0+fm0 (if reg_mode == 2). If provided, will automatically set res0 to False.

Returns

protocolpandas.DataFrame: Dataframe which contains the data for the protocol.dat.

resipy.Survey.bisectionSearch(arr, var): Efficent search algorithm for sorted array of postive ints

resipy.Survey.polyfit(x, y, deg=1)

Replacement function for numpy polyfit that works consistently (avoids SVD convergence error prsent on some W10 computers) Nb: is not as robust as numpy polyfit function.

Parameters

xarray like: x values of data
yTYPE: y values of data
degTYPE, optional: DESCRIPTION. The default is 1.

Returns

coefnp.array: coefficents of polynomail

Raises

ValueError: If deg < 0 .
TypeError: array data is not as expected for fitting a polynomail.

Created on Wed May 30 10:19:09 2018, python 3.6.5 @author: jamyd91 Module handles mesh generation, display, discretisation and post processing. The convention for x y z coordinates is that the z coordinate is the elevation.

Dependencies:: numpy (conda lib) matplotlib (conda lib) gmshWrap(ResIPy resipy module) python3 standard libaries

class resipy.meshTools.Mesh(node_x, node_y, node_z, node_data, cell_type, original_file_path='N/A', order_nodes=True, compute_centre=True, check2D=True)

Mesh class.

Parameters

node_xlist, 1d numpy array: x coordinates of nodes
node_ylist, 1d numpy array: coordinates of nodes
node_zlist, 1d numpy array: z coordinates of nodes
connection_matrix: M by N numpy array: nodes of element vertices in the form [[node1],[node2],[node3],…], each node id should be an integer type.
cell_typelist of ints: code referencing cell geometry (e.g. triangle) according to vtk format
original_file_pathstring, optional: file path to where the mesh file was originally imported
regionsoptional: element indexes for a material in the mesh (needs further explanation)

Returns

Meshclass
Attritbutes

numnp: int: Number of nodes
numel: int: Number of elements
node: N by 3 np array: Node coordinates (x y z columns)
connection: N by M np array: Connection matrix mapping elements on to thier respective vertices or nodes. Where N is the number of elements and M is the number of element vertices (i.e. M = 3 for a triangle mesh)
elmCentre: N by 3 np array: Coordinates for the geometric center for each element (x y z columns)
df: pandas dataframe: Contains attributes assocaited with each element inside the mesh, for example resistivity or parameter number
Note:

Something about the attribute_cache

addAttribute(values, key)

Add a new/update attribute to mesh.

Parameters

values: array like: must have a length which matches the number of elements. Discrete values which map to the elements.
key: str: Name of the attribute, this will be used to reference to the values in other mesh functions.

addPtAttribute(values, key)

Associate attributes with the mesh nodes

Parameters

values: array like: Must have a length which matches the number of nodes. Discrete values which map to the nodes.
key: str: Name of the attribute, this will be used to reference to the values in other mesh functions.

applyFunc(mesh_paras, material_no, new_key, function, *args)

Applies a function to a mesh by zone number and mesh parameter.

Parameters

mesh_parasarray like: Mesh parameters from which new parameters are calculated.
material_noarray like of ints: Material type assigned to each element, should be numbered consectively from 1 to n. in the form 1 : 1 : 2 : n. …ie if you have 2 materials in the mesh then pass an array of ones and twos. zeros will be ignored.
new_keystring: Key assigned to the parameter in the df. DOES NOT default.
functionfunction: Function to be applied to mesh attributes, first argument must be the mesh parameter.
args[see function info]: All arguments to be passed through function after to modify the mesh parameter, … argument must be in the form of [(argA1,argB1),(argA2,argB2)], … where letters are the material, numbers refer to the argument number

Notes

Mesh object will now have the new attribute added once the function is run. Use the mesh.show() (or .draw()) function to see the result.

assignZone(poly_data)

Assign material/region assocations with certain elements in the mesh say if you have an area you’d like to forward model. *2D ONLY*

Parameters

poly_datalist: list of 2 by N (x,y) numpy arrays describing each polygon.

Returns

material_nonumpy.array: Element associations starting at 1. So 1 for the first region defined in the region_data variable, 2 for the second region defined and so on. If the element can’t be assigned to a region then it’ll be left at 0.

assignZoneAttribute(attr_list, new_key, zone=None)

Asssigns values to the mesh which depend on region / material only. E.G a single resistivity value.

Parameters

attr_listlist: Values corresponding to a material number in the mesh. eg. if you had 3 regions in the mesh then you give [resistivity1,resistivity2,resistivity3].
new_keystring: Key identifier assigned to the attribute in the df.
zonearray or list: Integers starting at 0 or 1, and ascend in intervals of 1, which correspond to a material in the mesh returned from assign_attr_ID. Should have the same length as the number of elements in the mesh.

Notes

Mesh object will now have the new attribute added once the function is run. Use the mesh.show() (or .draw()) function to see the result.

cellArea(): Compute the element areas, or in the case of 3D meshes compute the cell volumes.

cellCentres(): A numpy-based approximation of cell centres for 2D and 3D elements. It’s calculated from the mean of cell x y z node coordinates

computeElmDepth(): Compute the depth of elements relative to the surface of the mesh.

computeNeigh(): Compute element neighbour matrix

copy(): Return a copy of mesh object.

crop(polyline)

Crop the mesh given a polyline in 2D.

Parameters

polylinearray of float: Array of size Nx2 with the XZ coordinates forming the polyline. Note that the first and last coordinates should be the same to close the polyline.

dat(file_path='mesh.dat')

Write a mesh.dat kind of file for mesh input for R2/R3t.

Parameters

file_pathstr, optional: Path to the file. By default ‘mesh.dat’ is saved in the working directory.

datAdv(file_path='mesh.dat', iadvanced=True)

Write a mesh.dat kind of file for mesh input for R2/R3t. Advanced format which includes the neighbourhood and conductance matrix.

Parameters

file_pathstr, optional: Path to the file. By default ‘mesh.dat’ is saved in the working directory.
iadvancedbool, optional: If True, use the advanced mesh format if False, use the normal mesh format.

downslopeID(attr='Resistivity')

Get the index of ‘downslope’ elements for a given attribute.

Parameters

attrstring, optional: Key inside of mesh dataframe. The default is ‘Resistivity’.

Returns

idxnd array: Indices of downslope elements.

draw(attr=None, edge_color='k', color_map='Spectral', color_bar=False, vmin=None, vmax=None)

Redraws a mesh over a prexisting figure canvas, this is intended for saving time when plotting each iteration of the resistivity inversion.

Parameters

color_mapstring, optional: color map reference
color_barboolean, optional: True to plot colorbar
axmatplotlib axis handle, optional: Axis handle if preexisting (error will thrown up if not) figure is to be cast to.
edge_colorstring, optional: Color of the cell edges, set to None if you dont want an edge.
vminfloat, optional: Minimum limit for the color bar scale.
vmaxfloat, optional: Maximum limit for the color bar scale.
attrstring, optional: Which attribute in the mesh to plot, references a dictionary of attributes. attr is passed as the key for this dictionary.

Returns

figurematplotlib figure: Figure handle for the plotted mesh object.

elemDist(): Work out the distance of each cell in the mesh to its closest electrode

exportTetgenMesh(prefix='mesh', zone=None, debug=False)

Export a mesh like the tetgen format for input into E4D. This format is composed of several files. Currently only tested for 3D surface array like surveys. Assumes the sides of the mesh are parrallel to the x and y plane and that the surface has gentle to no topography.

Parameters

prefix: string: Prefix assigned to exported files. Can include path to file.
zone: array like, optional: If using zones in the mesh, this attribute should include the zone attribute which is an array of integers identifying the zone associated with each element. By default each element is assigned to zone 1.
Notes
———-
Please note routine is experimental and not garanteed to work 100%

extractSurface(return_idx=False, post_neigh_check=True)

Extract the surface of a triangle or tetrahedral mesh. Ouput of function will depend on mesh type.

Parameters

return_idx: bool: Return the indices of elements on the top of the mesh (default is false)
post_neigh_check: bool: Perform a post processing step to check elements have neighbours, this is useful for meshes with uneven sides where false postives can crop up.

Returns

mesh: class: 2d faces of the top of the mesh, if the input mesh is a tetrahedral mesh
(x,z): tuple: 1D faces of the top of the mesh, if the input is a triangular mesh
idx: array like: if return_idx == True an array of int

file_path(): Returns the file path from where the mesh was imported

filterIdx(in_elem)

Filter mesh down on the basis of element number / index

Parameters

in_elem: array like: array of bool, True means to keep the element
attr: string: Name of attribute to threshold by

Returns

mesh: Class: New instance of mesh class which is filtered

findIdirichlet(): Find the best node for the dirchlet node Returns ——- idirchlet: int

A node far away as possible from each of the electrodes on the boundary of the mesh. (Add one if using inside of mesh(3d).dat)

static findParaview()

Run on windows to find paraview.exe command.

Returns

found: bool: If True the program was able to find where paraview is installed If false then the program could not find paraview in the default install locations.
location: str: if found == True. The string maps to the paraview executable if found == False. then ‘n/a’ is returned.

flipYZ(): Make Y column Z column and vice versa, this is useful for when dealing with 2D meshes. Dimensions are modified in place.

meshLookUp(look_up_mesh)

Look up values from another mesh using nearest neighbour look up, assign attributes to the current mesh class.

Parameters

look_up_mesh: class: Another mesh class.

moveElecNodes(new_x, new_y, new_z, debug=True)

Move the electrodes to different nodes which are close to the given coordinates. This is useful for timelapse surveys where the electrodes move through time, ideally this is implimented on a mesh which is refined near the surface. If no nodes are assigned to mesh, a mesh.e_nodes variable is created.

Parameters

new_x: array l ike: new electrode x coordinates
new_y: array like: new electrode y coordinates, if 2D mesh let new_y=None and the array will automatically be assigned an array of zeros.
new_z: array-like: new electrode z coordinates
debug: bool, optional: Controls if any changes to electrode nodes will be output to console.
Returns
————
node_in_mesh: np array: Array of mesh node numbers corresponding to the electrode postions/ coordinates.

Notes

Mesh.e_nodes parameter is updated (or added) after running function.

node2ElemAttr(node_array, name='NodeArray')

Maps node attributes onto mesh elements

Parameters

node_arrayarray like: Array with same number of entries as there are nodes in the mesh.
namestr, optional: Name of node attribute, will be used to index array in mesh dataframe. The default is ‘NodeArray’.

Returns

arrnd array: Node array mapped on mesh elements .

orderElem(param=None): Order elements based on the parameter number. Ideally parameters should be concurrent, and fixed elements should go at the base of the connection matrix

orderNodes(return_count=False)

Order mesh nodes in clockwise fashion

Parameters

return_count:bool, optional: Function returns the number of reordered elements, default is False.

paraview(fname='ResIPy_mesh.vtk', loc=None)

Show mesh in paraview

Parameters

fname: str,optional: A vtk file will be written to working directory and then displayed using paraview.
loc: str, optional: Path to paraview excutable, ignored if not using windows. If not provided the program will attempt to find where paraview is installed automatically.

pick3Dbox(ax=None, xlim=None, ylim=None, zlim=None, electrodes=True, darkMode=False)

Pick out regions on the mesh using the box widget (intended for 3D forward modelling)

Parameters

axclass, optional: pyvista plotting object. The default is None.
xlimtuple, list, array like, optional: x limit of the selection area. The default is None and assigned automatically.
ylimtuple, list, array like, optional: as with xlim. The default is None.
zlimtuple, list, array like, optional: as with xlim. The default is None.
electrodesbool, optional: If True the electrodes are also plotted on the mesh. The default is True.
darkmode: bool, optional: Alters coloring of pyvista plot for a darker appearance

Returns

pyvista clip box handle

Raises

Exception: If mesh is 2D

quad2tri()

Make a triangle mesh from a quad mesh

Returns

mesh: class: Triangle mesh class

quadMeshNp(topo=None)

Convert mesh nodes into x column indexes in the case of quad meshes. Does not currently support changes in electrode elevation!

Returns

colx: list: X column indexes for quad mesh

refine(): Refine the mesh into smaller elements

resetParam(): Reorder parameters into consective ascending order

saveMesh(fname, ftype=None)

Save mesh into a file. Avaialble formats are .dat, .vtk and .node

Parameters

fnameTYPE: DESCRIPTION.

setElecNode(e_nodes, iremote=None)

Assign node numbers to electrodes.

Parameters

e_nodes: array like: array of ints which index the electrode nodes in a mesh
iremote: array like, optional: Array of bool, if True then indexed electrode is remote.

show(color_map='Spectral', color_bar=True, xlim=None, zlim=None, ax=None, electrodes=True, sens=False, edge_color='k', contour=False, vmin=None, vmax=None, attr=None, clabel=None, hor_cbar=False, sensPrc=None, maxDepth=None, aspect='equal', darkMode=False, **kwargs)

Displays a 2d mesh and attribute.

Parameters

color_mapstring, optional: color map reference
color_barBoolean, optional: True to plot colorbar
xlimtuple, optional: Axis x limits as (xmin, xmax).
zlimtuple, optional: Axis z limits as (zmin, zmax).
axmatplotlib axis handle, optional: Axis handle if preexisting (error will thrown up if not) figure is to be cast to.
electrodesboolean, optional: Enter true to add electrodes to plot.
sensboolean, optional: Enter true to plot sensitivities.
edge_colorstring, optional: Color of the cell edges, set to None if you dont want an edge.
contourboolean, optional: If True, plot filled with contours instead of the mesh.
vminfloat, optional: Minimum limit for the color bar scale.
vmaxfloat, optional: Maximum limit for the color bar scale.
attrstring, optional: Which attribute in the mesh to plot, references a dictionary of attributes. attr is passed as the key for this dictionary.
clabelstring, optional: Label of the colorbar. Default is the value of attr argument.
hor_cbarboolean, optional: ‘True’ to make a horizontal color bar at the bottom of the plot, default is vertical color bar to the right of the plot.
sensPrcfloat, optional: Normalised (between 0 and 1) sensitivity value threshold. Default is None meaning the sensitivity is just overlay. Need sens=True to be used.
maxDepthfloat: Maximum absolute depth to be shown on the plotted figure.
aspectstring, optional: defines the aspect ratio of the plot. ‘equal’ locks the aspect ratio. ‘auto’, aspect ratio is define by plotting area.
darkModebool, optional: If True, electrodes will be plotted in white, else black

Returns

figurematplotlib figure: Figure handle for the plotted mesh object.

Notes

Show a mesh object using matplotlib. The color map variable should be a string refering to the color map you want (default is “jet”). As we’re using the matplotlib package here any color map avialable within matplotlib package can be used to display the mesh here also. See: https://matplotlib.org/2.0.2/examples/color/colormaps_reference.html

show3D(color_map='Spectral', color_bar=True, xlim=None, ylim=None, zlim=None, ax=None, electrodes=True, sens=False, edge_color='k', alpha=1, vmax=None, vmin=None, attr=None, elec_color='k', use_pyvista=True, background_color=(0.8, 0.8, 0.8), pvslices=([], [], []), pvspline=None, pvthreshold=None, pvgrid=True, pvcontour=[], pseudo3DContour=False, pvdelaunay3d=False, pvshow=True, darkMode=False, cell_picking=False, clipping=True)

Shows a 3D tetrahedral mesh.

Parameters

color_mapstring, optional: Matplotlib color map reference
color_barBoolean, optional: True to plot colorbar
xlimtuple, optional: Axis x limits as (xmin, xmax).
ylimtuple, optional: Axis y limits as (ymin, ymax).
zlimtuple, optional: Axis z limits as (zmin, zmax).
axmatplotlib axis handle, pvista plotter handle, optional: Axis handle if preexisting (error will thrown up if not) figure is to be cast to. If using pyvista then then ax is the plotter the object.
electrodesboolean, optional: Enter true to add electrodes to plot (if available in mesh class)
sensboolean, optional: Enter true to plot sensitivities (if available in mesh class). Note that for 3D this doesnt work so well.
edge_colorstring, optional: Color of the cell edges, set to None if you dont want an edge.
alpha: float, optional: Should be set between 0 and 1. Sets a transparancy value for the element faces.
vminfloat, optional: Minimum limit for the color bar scale.
vmaxfloat, optional: Maximum limit for the color bar scale.
attrstring, optional: Which attribute in the mesh to plot, references a dictionary of attributes. attr is passed as the key for this dictionary.
elec_colorstring, optional: Colour of the electrodes on the plot if electrodes = True. Default is ‘k’ for black. Can be a 3 by 1 tuple or string identifier.
use_pyvistabool, optional: Use visual toolkit backend for displaying 3D mesh, note that pyvista must be installed for this to work.
background_colortuple, optional: Background color assigned to pyvista plotter object when created. Not yet supported for matplotlib axis handles.
pvslicestuple of list of float, optional: Determine the X, Y, Z slices. e.g.: ([3], [], [-3, -4]) will add a slice normal to X in 3 and two slices normal to Z in -3 and -4.
pvspline‘elec’ or numpy array, optional: If ‘elec’ mesh will be sliced along the electrodes path otherwise an array of X, Y, Z of points on a path to slice the mesh along that path is needed.
pvthresholdlist of two floats, optional: Keep values between pvthreshold[0] and pvthreshold[1].
pvgridbool, optional: Show grid or not.
pvcontourlist of float, optional: Values of the isosurface to be plotted.
pseudo3DContour: bool, optional: If ‘True’, pseudo 3D plots will be contoured. Only use in case of pseudo 3D surveys.
pvdelaunay3dbool, optional: If True a “Delaunay 3D” triangulation filter will be applied on the mesh.
pvshowbool, optional: If False, that will prevent calling the pyvista.Plotter.show(). This is useful in case of subplots.
darkmode: bool, optional: Alters coloring of pyvista plot for a darker appearance
cell_picking: bool, optional: Interactive picking flag, for the use within the UI only. Leave as False.
clipping: bool, optional: Flag to clip mesh in pyvista window, if tank type problem is expected set to False else set to True. Default is True. Note if False then the X Y and Z limit extents will be ignored.

Returns

figurematplotlib figure, pyvista plotter: Figure handle for the plotted mesh object.

Notes

Show a mesh object using matplotlib. The color map variable should be a string refering to the color map you want (default is “Spectral”). As we’re using the matplotlib package here any color map avialable within matplotlib package can be used to display the mesh here also. See: https://matplotlib.org/2.0.2/examples/color/colormaps_reference.html

Plotting sensitivies using sens=True is not reccomended. The matplotlib renderer has trouble with it.

showAvailAttr(flag=True): Show available attributes in mesh.df.

showPrismMesh(color_map='Spectral', color_bar=True, ax=None, electrodes=True, sens=False, edge_color='k', alpha=1, aspect='equal', vmax=None, vmin=None, attr=None, xlim=None, ylim=None, zlim=None)

Shows a 3D prism mesh.

Parameters

color_mapstring, optional: color map reference
color_barBoolean, optional: True to plot colorbar
xlimtuple, optional: Axis x limits as (xmin, xmax).
ylimtuple, optional: Axis y limits as (ymin, ymax).
zlimtuple, optional: Axis z limits as (ymin, ymax).
axmatplotlib axis handle, optional: Axis handle if preexisting (error will thrown up if not) figure is to be cast to.
electrodesboolean, optional: Enter true to add electrodes to plot (if available in mesh class)
sensboolean, optional: Enter true to plot sensitivities (if available in mesh class). Note that for 3D this doesnt work so well.
edge_colorstring, optional: Color of the cell edges, set to None if you dont want an edge.
alpha: float, optional: Should be set between 0 and 1. Sets a transparancy value for the element faces.
vminfloat, optional: Minimum limit for the color bar scale.
vmaxfloat, optional: Maximum limit for the color bar scale.
attrstring, optional: Which attribute in the mesh to plot, references a dictionary of attributes. attr is passed as the key for this dictionary.
aspect = string, optional: defines the aspect ratio of the plot. ‘equal’ locks the aspect ratio. ‘auto’, aspect ratio is define by plotting area.

Returns

figurematplotlib figure: Figure handle for the plotted mesh object.

showSlice(attr='Resistivity(log10)', axis='z', vmin=None, vmax=None, ax=None)

Show 3D mesh slice.

Parameters

attrstr, optional: String the of the variable to plot. Default is Resistivity(log10).
axisstr, optional: Axis to be sliced either, x, y or z.
vminfloat, optional: Minimum value for colorbar.
vmaxfloat, optional: Maximum value for colorbar.
axmatplotlib.Axis: If provided, plot will be drawn on this axis.

splitTetra(param=None): Refine tetrahedra by splitting them in six smaller tetrahedra.

splitTri(param=None): Refine triangles by splitting them into 4 smaller triangles

summary(flag=True): Prints summary information about the mesh

threshold(attr=None, vmin=None, vmax=None)

Threshold the mesh to certian attribute values.

Parameters

attr: string: Name of attribute to threshold by
vmin: float: minimum value of attribute
vmax: float: maximum value of attribute

Returns

mesh: Class: New instance of mesh class which is thresholded

toCSV(file_name='mesh.csv')

Write a .csv file of the mesh, the first 3 columns are the element centres at coordinates x,y,z and the rest of the columns are the attributes in the df

Parameters

file_nameString, optional: The default is ‘mesh.csv’.

Returns

None.

transMesh(x, y, z): Translate mesh by x y z coordinate

truncateMesh(xlim=None, ylim=None, zlim=None)

Crop the mesh to a box of given limits, like how R3t behaves when outputting inverted results.

Parameters

xlimtuple, optional: Axis x limits as (xmin, xmax).
ylimtuple, optional: Axis y limits as (ymin, ymax).
zlimtuple, optional: Axis z limits as (ymin, ymax).

Returns

nmesh: Class: New instance of mesh class which is truncated

type2FaceNo(): Converts vtk cell types into number of faces each element has

type2VertsNo(): Converts vtk cell types into number of vertices each element has

vtk(file_path='mesh.vtk', title=None, replace_nan=-9999)

Writes a vtk file for the mesh object, everything in the df will be written to file as attributes. We suggest using Paraview to display the mesh outside of ResIPy. It’s fast and open source :).

Parameters

file_path: str, optional: Maps where python will write the file, if left as default then mesh.vtk will be written the current working directory.
titlestr, optional: Header string written at the top of the vtk file .

writeAttr(attr_key=None, file_name='_res.dat')

Writes a attribute to a _res.dat type file. file_name entered seperately because it will be needed for the R2 config file. The reason for this function is so you can write a forward model parameter input file.

Parameters

attr_key: string: Key identifying the attr to be written in the mesh object df.
file_name: string, optional: Name of the _res.dat type file.

writeRindex(fname)

Write out the neighbourhood matrix for R3t.

Parameters

fnamestr: Path to written file.

resipy.meshTools.check4repeatNodes(X, Y, Z, flag=None)

Raise error if repeated nodes present

Parameters

Xarray like: X coordinates of nodes (normally electrodes).
Yarray like: Y coordinates of nodes (normally electrodes).
Zarray like: Z coordinates of nodes (normally electrodes).
flaglist of string, optional: String flag assigned to each node. The default is None.

Returns

None.

Raises

ValueError: If repeated nodes detected

resipy.meshTools.cylinderMesh(elec_x, elec_y, elec_z, zlim=None, radius=None, file_path='cylinder_mesh.geo', cl=-1, cl_factor=2, finer=4, keep_files=True, show_output=True, path='exe', dump=<built-in function print>, handle=None)

Make a cylinder mesh.

Parameters

eleclist of array_like or nx3 array: First column/list is the x coordinates of electrode positions and so on …
zlimlist, tuple, optional: Bottom and top z coordinate of column, in the form (min(z),max(z))
radius: float, optional: Radius of column. If not provided, will be infered from elec positions.
file_pathstring, optional: Name of the generated gmsh file (can include file path also).
clfloat, optional: Characteristic length, essentially describes how big the nodes associated elements will be. Usually no bigger than 5. If set as -1 (default) a characteristic length 1/4 the minimum electrode spacing is computed.
finerint, optional: Number of line between two consecutive electrodes to approximate the circle shape. No longer used.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.

resipy.meshTools.dat_import(file_path='mesh.dat', order_nodes=True)

Import R2/cR2/R3t/cR3t .dat kind of mesh.

Parameters

file_path: str: Maps to the mesh (.dat) file.

Returns

mesh: class

resipy.meshTools.in_box(x, y, z, xmax, xmin, ymax, ymin, zmax, zmin)

Determine if a point lies inside a bounding volume.

Parameters

xarray like, float: x coordinate of query point
yarray like, float: y coordinate of query point
zarray like, float: z coordinate of query point
volume_datalist: contains column of poly_data, in the form (polyx, polyy, polyz)
ray_castfloat, optional: determines how the far in the x axis a point is ray casted

Returns

insideboolian, numpy array: true indexes where point is inside volume

resipy.meshTools.mergeMeshes(meshList)

Merge multiple meshes into one mesh object, useful for psuedo 3d surveys.

Parameters

meshListlist: List of seperate mesh classes .

Returns

mmesh: class: Merged mesh.

resipy.meshTools.moveMesh2D(meshObject, elecLocal, elecGrid)

Move mesh object to a certain place on the grid.: X, Y only. No Z relocation.

Parameters

meshObjectclass object: Mesh class object.
elecLocal: dataframe: dataframe of electrodes on local 2D grid (i.e., y = 0) ‘remote’ column (bool) required.
elecGrid: dataframe: dataframe of electrodes on 3D grid (i.e., y != 0) ‘remote’ column (bool) required

Returns

meshclass object: Copy of moved Mesh class object.

resipy.meshTools.points2vtk(x, y, z, file_name='points.vtk', title='points')

Function makes a .vtk file for some xyz coordinates. optional argument renames the name of the file (needs file path also) (default is “points.vtk”). title is the name of the vtk file.

Parameters

xlist, tuple, np array: X coordinates of points.
ylist, tuple, np array: Y coordinates of points.
zlist, tuple, np array: Z coordinates of points.
file_namestring, optional: Path to saved file, defualts to ‘points.vtk’ in current working directory.
titlestring, optional: Title of vtk file.

Returns

~.vtkfile

resipy.meshTools.prismMesh(elec_x, elec_y, elec_z, keep_files=True, show_output=True, path='exe', dump=<built-in function print>, handle=None, **kwargs)

Make a prism mesh.

Parameters

elec_x: array like: electrode x coordinates
elec_y: array like: electrode y coordinates
elec_z: array like: electrode z coordinates
poly: list, tuple, optional: Describes polygon where the argument is 2 by 1 tuple/list. Each entry is the polygon x and y coordinates, ie (poly_x, poly_y)
z_lim: list, tuple, optional: top and bottom z coordinate of column, in the form (min(z),max(z))
radius: float, optional: radius of column
file_path: string, optional: name of the generated gmsh file (can include file path also) (optional)
cl: float, optional: characteristic length (optional), essentially describes how big the nodes assocaited elements will be. Usually no bigger than 5. If set as -1 (default) a characteristic length 1/4 the minimum electrode spacing is computed.
elemz: int, optional: Number of layers in between each electrode inside the column mesh.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.

resipy.meshTools.quadMesh(elec_x, elec_z, elec_type=None, elemx=4, xgf=1.5, zf=1.1, zgf=1.25, fmd=None, pad=2, surface_x=None, surface_z=None, refine_x=None, refine_z=None)

Creates a quaderlateral mesh given the electrode x and y positions.

Parameters

elec_xlist, np array: Electrode x coordinates
elec_zlist, np array: Electrode y coordinates
elec_type: list, optional: strings, where ‘electrode’ is a surface electrode; ‘buried’ is a buried electrode
elemxint, optional: Number of nodes between electrodes.
xgffloat, optional: X factor multiplier for fine zone.
zffloat, optional: Z factor multiplier in the fine zone (must be >1).
zgffloat, optional: Z factor multiplier in the coarse zone (must be >1).
fmdfloat (m), optional: Fine mesh region depth specifies as positive number (if None, half survey width is used).
padint, optional: X padding outside the fine area (tipicaly twice the number of elements between electrodes).
surface_x: array like, optional: Default is None. x coordinates of extra surface topography points for the generation of topography in the quad mesh
surface_z: array like, optional: Default is None. z coordinates of extra surface topography points for the generation of topography in the quad mesh. Note an error will be returned if len(surface_x) != len(surface_z)
refine_x: array like, optional: Default is None. Inserts points in the resulting quad mesh for more control over mesh refinement at depth. X coordinates. An error will be returned if len(refine_x) != len(refine_z).
refine_z: array like, optional: Default is None. Inserts points in the resulting quad mesh for more control over mesh refinement at depth. Z coordinates. An error will be returned if len(refine_x) != len(refine_z).

Returns

Meshclass: Mesh object
meshxnumpy.array: Mesh x locations for R2in file.
meshznumpy.array: Mesh locations for R2in file (ie node depths).
toponumpy.array: Topography for R2in file.
elec_nodenumpy.array: x columns where the electrodes are.

resipy.meshTools.readMesh(file_path, node_pos=None, order_nodes=True)

Import user defined mesh, currently supports .msh, .vtk and .dat (native to R2/3t) format for quad, triangular and tetrahedral meshes. The type of file is guessed from the extension given to the code.

Parameters

file_pathstring: Path to file.
node_posarray like, optional: Array of ints referencing the electrode nodes. If left as none no electrodes will be added to the mesh class. Consider using mesh.move_elec_nodes() to add nodes to mesh using their xyz coordinates.
order_nodesbool, optional: Order nodes when importing a mesh

Returns

meshclass: mesh class used in ResIPy

resipy.meshTools.runGmsh(ewd, file_name, show_output=True, dump=<built-in function print>, threed=False, handle=None)

Parameters

ewdstr: Directory where gmsh copy is stored.
file_namestr: Name of the .geo file without extension.
show_outputTYPE, optional: If True, output of gmsh is displayed to dump. The default is True.
threedbool, optional: If True, 3D mesh is done, else 2D. The default is False.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.

Returns

None.

resipy.meshTools.tankMesh(elec=None, origin=None, dimension=[10, 10, 10], file_path='tank_mesh.geo', cl=-1, keep_files=True, show_output=True, path='exe', dump=<built-in function print>, handle=None)

Make a tank mesh (3D closed box).

Parameters

eleclist of array_like or nx3 array: First column/list is the x coordinates of electrode positions and so on …
originlist of float, optional: Origin of the corner where the mesh will be drawned from. If not provided and elec provided, the smaller elec position will be chosen.
dimensionlist of float, optional: Dimension of the mesh in X,Y,Z from the corner origin. The default is [10,10,10].
file_pathstring, optional: Name of the generated gmsh file (can include file path also).
clfloat, optional: Characteristic length, essentially describes how big the nodes associated elements will be. Usually no bigger than 5. If set as -1 (default) a characteristic length 1/4 the minimum electrode spacing is computed.
finerint, optional: Number of line between two consecutive electrodes to approximate the circle shape.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.

resipy.meshTools.tetgen_import(file_path, order_nodes=True)

Import Tetgen mesh into ResIPy. This isa little different from other imports as the mesh is described by several files. From meshTools’ perspective What is needed is the node(.node) file and element (.ele) files, which describe the coordinates of mesh nodes and the connection matrix.

Parameters

file_path: str: Maps to the mesh .node file. The program will automatically find the corresponding .ele file in the same directory.

Returns

mesh: class

resipy.meshTools.tetraMesh(elec_x, elec_y, elec_z=None, elec_type=None, keep_files=True, interp_method='triangulate', surface_refinement=None, mesh_refinement=None, show_output=True, add_refinement=True, path='exe', dump=<built-in function print>, whole_space=False, padding=20, search_radius=10, handle=None, **kwargs)

Generates a tetrahedral mesh for R3t (with topography). returns mesh3d.dat in the working directory. This function expects the current working directory has path: exe/gmsh.exe.

Uses post processing after mesh generation to super impose topography on to a flat 3D tetrahedral mesh.

Parameters

elec_x: array like: electrode x coordinates
elec_y: array like: electrode y coordinates
elec_z: array like: electrode z coordinates
elec_type: list of strings, optional: Defines if electrodes are buried or not.
keep_filesboolean, optional: True if the gmsh input and output file is to be stored in the working directory.
interp_method: string, default =’bilinear’ optional: Interpolation method to translate mesh nodes in the z direction. In other words the method in which topography is appended to the mesh. Here the topography is added to the mesh in post processing. The options documented in the notes. if == ‘idw’: then provide search_radius.
surface_refinementnp.array, optional: Numpy array of shape (3,n), should follow the format np.array([x1,x2,x3,…],[y1,y2,y3,…],[z1,z2,z3,…]). Allows for extra refinement for the top surface of the mesh. The points are not added to the mesh, but considered in post processing in order to super impose topography on the mesh.
mesh_refinementdict, pd.DataFrame, optional: Dataframe (or dict) contianing ‘x’, ‘y’, ‘z’, ‘type’ columns which describe points which can be used to refine the mesh, unlike surface_refinement, this argument allows the user granular control over the refinement of mesh elements. See further explanation in tetraMesh notes.
show_outputboolean, optional: True if gmsh output is to be printed to console.
add_refinement: boolean: If True then points are added near to surface electrodes to encourage extra refinement near electrodes (option in development)
pathstring, optional: Path to exe folder (leave default unless you know what you are doing).
whole_space: boolean, optional: flag for if the problem should be treated as a whole space porblem, in which case electrode type is ingored and all electrodes are buried in the middle of a large mesh.
dumpfunction, optional: Function to which pass the output during mesh generation. print() is the default.
paddingfloat, optional: amount of % the fine mesh region will be extended beyond the extent of the electrode positions
search_radius: float, None, optional: Defines search radius used in the inverse distance weighting interpolation. If None then no search radius will be used and all points will be considered in the interpolation.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.
**kwargsoptional: Key word arguments to be passed to box_3d.

Returns

mesh3d: class

Notes

Possible arguments for interp_method:

‘bilinear’4 known points are used to compute the equation of a plane: in which the interpolated point lies. This method is reccomended if elevation data is organised in a regular grid.
‘idw’Inverse distance weighting, interpolated points are assigned a: a z value which is a weighted average of all points in the search raduis. This method works best for gentle topography.
‘nearest’Nearest neighbour interpolation. Z value at the interpolated: point takes on the same Z value as the closest known point. This method can work well for dense elevation data, say in the case using a point cloud from a digital elevation model. This method is the most computationally cheap to run.
‘spline’Like bilinear interpolation, a function is fitted to a: quadlerateral of known points encompassing the interpolated Z value. The computed function is a higher order than linear interpolation though. Works best for irregular spaced elevation data.
‘triangulate’: Triangulation method, best for complicated topographies: where an irregular grid of known topography points is not avialable. This is the default.
NoneNo interpolation method is used to interpolated topography on to: mesh, hence a flat mesh is returned.

Format of mesh_refinement:

The variable must have x,y,z and type columns ‘x’: x coordinate array like ‘y’: y coordinate array like ‘z’: z coordinate array like ‘type’: list, object array of point types, use the tag ‘surface’ for

surface points, use ‘buried’ for buried points.

‘cl’: array like of characteristic lengths for each refinement point in: the mesh.

resipy.meshTools.triMesh(elec_x, elec_z, elec_type=None, geom_input=None, keep_files=True, show_output=True, path='exe', dump=<built-in function print>, whole_space=False, handle=None, **kwargs)

Generates a triangular mesh for r2. Returns mesh class … this function expects the current working directory has path: exe/gmsh.exe. Uses gmsh version 3.0.6.

Parameters

elec_x: array like: electrode x coordinates
elec_z: array like: electrode y coordinates
elec_type: list of strings, optional: List should be the same length as the electrode coordinate argument. Each entry in the list references the type of electrode: - ‘electrode’ = surface electrode coordinate, will be used to construct the topography in the mesh - ‘buried’ = buried electrode, placed the mesh surface - ‘remote’ = remote electrode (not actually placed in the mesh) - ‘borehole’ = borehole electrode, electrodes will be placed in the mesh with a line connecting them. borehole numbering starts at 1 and ascends numerically by 1.
geom_inputdict, optional: Allows for further customisation of the 2D mesh, its a dictionary contianing surface topography, polygons and boundaries
keep_filesboolean, optional: True if the gmsh input and output file is to be stored in the exe directory.
show_ouputboolean, optional: True if gmsh output is to be printed to console.
pathstring, optional: Path to exe folder (leave default unless you know what you are doing).
whole_space: boolean, optional: flag for if the problem should be treated as a whole space porblem, in which case electrode type is ingored and all electrodes are buried in the middle of a large mesh.
dumpfunction, optional: Function to which pass the output during mesh generation. print() is the default.
handlevariable, optional: Will be assigned the output of ‘Popen’ in case the process needs to be killed in the UI for instance.
**kwargsoptional: Key word arguments to be passed to genGeoFile.

Returns

mesh: class: <ResIPy> mesh class

Notes

geom_input format:

the code will cycle through numerically ordered keys (strings referencing objects in a dictionary”), currently the code expects a ‘surface’ and ‘electrode’ key for surface points and electrodes. the first borehole string should be given the key ‘borehole1’ and so on. The code stops searching for more keys when it cant find the next numeric key. Same concept goes for adding boundaries and polygons to the mesh. See below example:

geom_input = {‘surface’: [surf_x,surf_z],
‘boundary1’:[bound1x,bound1y], ‘polygon1’:[poly1x,poly1y]}

electrodes and electrode_type (if not None) format:

electrodes = [[x1,x2,x3,…],[y1,y2,y3,…]] electrode_type = [‘electrode’,’electrode’,’buried’,…]

like with geom_input, boreholes should be labelled borehole1, borehole2 and so on. The code will cycle through each borehole and internally sort them and add them to the mesh.

The code expects that all polygons, boundaries and electrodes fall within x values of the actaul survey area. So make sure your topography / surface electrode points cover the area you are surveying, otherwise some funky errors will occur in the mesh.

resipy.meshTools.vtk_import(file_path='mesh.vtk', order_nodes=True)

Imports a mesh file into the python workspace, can have triangular, quad or tetraheral shaped elements.

Parameters

file_pathstring, optional: File path to mesh file. Note that a error will occur if the file format is not as expected.
order_nodesbool, optional: Order Nodes if true. Process can be resource intensive though. Reccomended if using the mesh for an inversion.

Returns

meshclass: a <ResIPy> mesh class

resipy.meshTools.vtk_import_fmt4(file_path, order_nodes=True): Vtk importer for newer format (not fully validated)