Soil profiles

class groundhog.general.soilprofile.SoilProfile(*args, **kwargs)[source]

A SoilProfile object is a Pandas dataframe with specific functionality for geotechnical calculations. There is a column syntax requirement in which the columns with the top and bottom depth need to be defined for each layer. By default ‘Depth from [m]’ and ‘Depth to [m]’ are expected but this can be customised.

__init__(*args, **kwargs)[source]

Overrides the init method of a dataframe to check the correctness of the layering and to set the depth column names.

applyfunction(function, resultkey, outputkey, parametermapping={}, **kwargs)[source]

Applies a groundhog function to a soil profile. The function is applied to each row of the soilprofile. The result is stored in a column with name output. resultkey determines which key of the function output dictionary is used as the result.

The parameters of the function are mapped to columns of the soil profile using the parametermapping dictionary. The keys of this dictionary are the function arguments, the values are the corresponding columns of the soilprofile. For parameters with linear variation, this method only needs to be applied once and the soil parameter name (without from or to) needs to be supplied in the parametermapping dictionary.

  • function – Function to be applied

  • resultkey – Column name for the result (for parameters with linear variation, two result columns are created)

  • outputkey – The key of the function output dictionary to be used for the result

  • parametermapping – Dictionary mapping parameters of the function to column names

  • applyatcenter – Boolean determining whether the function needs to be applied at the center of the layer for a linearly varying parameter. A single output column will then be returned (default=False).

  • kwargs – Additional keyword arguments of the function which are not mapped to soil profile columns


calculate_center(layercentercol='Depth center [m]')[source]

Adds a column with the layer center depth to the soil profile :param layercentercol: Name of the column with the layer center :return: Adds a column with the layer center

calculate_layerthickness(layerthicknesscol='Layer thickness [m]')[source]

Adds a column with the layer thickness to the soil profile :param layerthicknesscol: Name of the column with the layer thickness :return: Adds a column with the layer thickness

calculate_overburden(waterlevel=0, waterunitweight=10, totalunitweightcolumn='Total unit weight [kN/m3]', effectiveunitweightcolumn='Effective unit weight [kN/m3]', waterunitweightcolumn='Water unit weight [kN/m3]', totalverticalstresscolumn='Total vertical stress [kPa]', effectiveverticalstresscolumn='Effective vertical stress [kPa]', hydrostaticpressurecolumn='Hydrostatic pressure [kPa]')[source]

Calculates the overburden pressure (total and effective) for a SoilProfile object. The SoilProfile object needs to contain a column with the total unit weight. By default, this is Total unit weight [kN/m3]. If the water level does not correspond with a layer interface, an additional layer interface is created. Total and effective unit weights are calculated for each layer and the method depth_integration is used to calculate the total vertical stress, effective vertical stress and hydrostatic pressure.

Note that vertical stress calculations in other units are possible, but the water unit weight then needs to be specified in consistent units.

  • waterlevel – Water level [m] (default 0m)

  • waterunitweight – Unit weight of the pore water [kN/m3] (default=10kN/m3)

  • totalunitweightcolumn – Column name containing total unit weights (default=’Total unit weight [kN/m3]’

  • waterunitweightcolumn – Output column with the effective unit weight (default=’Effective unit weight [kN/m3]’)

  • waterunitweightcolumn – Output column with the water unit weight (default=’Water unit weight [kN/m3]’)

  • totalverticalstresscolumn – Total vertical stress column name (default=’Total vertical stress [kPa]’)

  • effectiveverticalstresscolumn – Effective vertical stress column name (default=’Effective vertical stress [kPa]’)

  • hydrostaticpressurecolumn – Hydrostatic pressure column name (default=’Hydrostatic pressure [kPa]’)


Adds the column names from totalverticalstresscolumn, effectiveverticalstresscolumn and hydrostaticpressurecolumn to the SoilProfile object

calculate_parameter_center(parameter, suffix='center')[source]

Calculates the value of a soil parameter at the center. The soil parameter needs to be a linearly varying numerical soil parameter. :param parameter: Numerical soil parameter for which the value at the center needs to be computed. :param suffix: Suffix to use instead of from or to :return: Adds an extra column with from or to in the column name replaced by the chosen suffix


Check if a soil parameter varies linearly or not. :return: Boolean determining whether a soil parameter has a linear variation or not


Check if the SoilProfile meets the requirements for calculations


Inverts the sign of the depth from and depth to column. This function is useful when the profiles needs to be examined relative to LAT

convert_to_constant(parameter, rule='mean')[source]

Converts a linearly varying soil parameter to a parameter with constant value. :param parameter: Soil parameter to convert. Specify Total unit weight [kN/m3] if the SoilProfile contains columns Total unit weight from [kN/m3] and Total unit weight to [kN/m3]. :param rule: Select from ['min', 'mean', 'max'] to convert the linear variation to a constant value (default=’mean’) :return: Creates a column for the soil parameter with constant value and removes the column with the linear variation

cut_profile(top_depth, bottom_depth)[source]

Returns a deep copy of the SoilProfile between the specified bounds :param top_depth: Top depth for cutting :param bottom_depth: Bottom depth for cutting :return: Deep copy of the SoilProfile between the specified bounds

depth_integration(parameter, outputparameter, start_value=0)[source]

Integrate a certain parameter vs depth (e.g. unit weight to obtain vertical stress) Note: This routine is only implemented for parameters with a constant value in the layer. :param parameter: Parameter to be integrated :param outputparameter: Name of the output parameter (with units) :param start_value: Value at the top of the profile (default=0) :return: Adds a column to the SoilProfile object for the integrated parameter


Inserts a layer transition in the soil profile at a specific depth The profile layer is simply split and the properties of the given layer are assigned to the new layers above and below the transition. For linearly varying parameters, an interpolation is performed.

layer_transitions(include_top=False, include_bottom=False)[source]

Returns a Numpy array with the layer transition depths. Use the booleans include_top and include_bottom to in/exclude the top and bottom of the profile

map_soilprofile(nodalcoords, target_depthkey='z [m]', invert_sign=False, offset=0)[source]

Maps the soilprofile to a grid. The depth coordinates to the grid are specified in a list or Numpy array (nodalcoords). The depth coordinates should be strictly ascending (no duplicates) and the minimum and maximum should be contained inside the soil profile bounds. All soil parameters are interpolated onto this grid. :param nodalcoords: List or Numpy array with the nodal coordinates of the grid :param target_depthkey: Name of the depth key in the resulting dataframe :param invert_sign: Boolean determining whether to invert the sign after interpolation :param offset: Offset by which the depth is shifted (added to the depth after sign conversion) :return: Returns a dataframe with the full grid with soil parameters

property max_depth

Returns the maximum depth of the soil profile

merge_layers(layer_ids, keep='top')[source]

Merges two layers. Depending on the keep keyword, the top or bottom properties are retained for the merged layer

  • layer_ids – List with the 2 IDs of the layers to be merged

  • keep – String determining whether to retain the parameters of the top or bottom layer for the merged layer (select ‘top’ or ‘bottom’)


Reduces the number of layers of the SoilProfile object

property min_depth

Returns the minimum depth of the soil profile


Returns a list of numerical soil parameters available in the soil profile. Numerical soil parameters have units between square brackets. Soil parameters with linear variations are returned as a single soil parameter when the boolean condense_linear is set to True :return: Returns a list with the numerical soil parameters in the SoilProfile

plot_profile(parameters, soiltypecolumn='Soil type', **kwargs)[source]

Generates a Plotly plot of the soil parameters vs depth. The panel on which the parameter is plotted is determined by how the parameters are passed to the function.

parameters=(('qc [MPa]',), ('Dr [%]',)) will plot cone resistance in panel 1 and relative density in panel 2

parameters=(('qc [MPa]', 'qt [MPa]'), ('Dr [%]')) will plot cone resistance and total cone resistance in panel 1 and relative density in panel 2

A column wihh the soil type is expected for the plotting of the log

  • parameters – List of parameters tuples for plotting

  • kwargs – Additional keyword arguments for the plot_with_log function in the general.plotting module


Plotly plot with mini-log and parameter values


Removes a soil parameter from the dataframe :param parameter: Soil parameter to remove. For linear variations, simple use the expression parameter [unit]. The routine takes care of removing both the ‘to’ and ‘from’ columns :return: Removes the requested soil parameter from the SoilProfile objec

selection_soilparameter(parameter, depths, values, rule='mean', linearvariation=False)[source]

Function for automatic selection of a soil parameters in the layers of a soil profile based an a list of provided values. The selection can either be done for a constant value in the layer or a linear variation over the layer. Selection of a minimum, mean or average trend can be performed using the rule keyword

  • parameter – Name of the parameter being selected (including unit in square brackets)

  • depths – Depths at which a measurement is available (list or Numpy array)

  • values – Values corresponding to the given depths (list or Numpy array)

  • rule – Which rule to use for the selection (select from min, mean and max

  • linearvariation – Boolean determining whether a linear variation needs to happen over the layer or not


Adds one (constant value) or two (linear variation) columns to the dataframe

set_position(easting, northing, elevation, srid=4326, datum='mLAT')[source]

Sets the position of a soil profile top in a given coordinate system.

By default, srid 4326 is used which means easting is longitude and northing is latitude.

The elevation is referenced to a chart datum for which mLAT (Lowest Astronomical Tide) is the default.

  • easting – X-coordinate of the CPT position

  • northing – Y-coordinate of the CPT position

  • elevation – Elevation of the CPT position

  • srid – SRID of the coordinate system (see

  • datum – Chart datum used for the elevation


Sets the corresponding attributes of the `PCPTProcessing` object


Shifts all layer coordinates downward or upward, depending on the sign of the given offset. The offset is added to the given coordinates


Returns a list of soil parameters available in the soil profile. Soil parameters with linear variations are returned as a single soil parameter when the boolean condense_linear is set to True :return: Returns a list of the soil parameters in the SoilProfile


Returns two lists (depths and corresponding parameter values) for plotting of a soil parameter vs depth. The routine first checks whether a valid parameter is provided. The lists are formatted such that variations at a layer interface are adequately plotted. :param parameter: A valid soil parameter with units :return: Two lists (depths and corresponding parameter values)


Returns a list of string soil parameters available in the soil profile. String soil parameters have no square brackets. :return: Returns a list with the string soil parameters in the SoilProfile