pygeostat Configuration¶

Various utilities to configure the behaviour of pygeostat functions and to save project-specific defaults across files or between sessions.

gsParams¶

class pygeostat.GsParams.GsParams(*args, **kwargs)¶

A dictionary object for defining pygeostat default parameters, which is intended to add convenience to modeling workflows where common parameters must otherwise be repeated in function calls. An instance of this object is initialized as gsParams when pygeostat is imported. Default parameters are implemented as thoughtfully as possible, but may be modified by users once to suit their requirements. Keyword arguments for functions override any gsParams defaults for the function call itself, without modifying the defaults themselves.

Examples of modifying plotting parameters include:

>>> gs.gsParams['plotting.xname'] = 'Easting'
>>> gs.gsParams['plotting.lagname'] = 'h'
>>> gs.gsParams['plotting.unit'] = 'm'

Examples of data parameters include:

>>> gs.gsParams['data.dh'] = 'WellID'
>>> gs.gsParams['data.griddef'] = pygeostat.GridDef()
>>> gs.gsParams['data.x'] = 'Easting'

The object performs validation on any modificaitons to the dictionary. If users are confused about the application of any defaults, a describe function allows for individual parameters (e.g., gsParams.describe(‘plotting.xname’) or the entire dictionary (e.g., gsParams.describe() to be printed to the console.

Attributation to Matplotlib:

The template for the gsParams class is inspired by adapted from the Matplotlib rcParams class and related functionality, as it provides a template for the approach to setting defaults to a Python instance. Refer to the header of gsParams.py for a full attributation and license of Matplotlib.

Code author: Ryan M. Barnett 2018-03-18

Find All¶

GsParams.find_all(pattern)¶: Return the subset of this GsParams dictionary whose keys match, using re.search(), the given pattern.

Note

Changes to the returned dictionary are not propagated to the parent GsParams dictionary.

Restore Defaults¶

GsParams.restore_defaults()¶: Restore the original dictionary defaults to the current session

Describe¶

GsParams.describe(key=None)¶

Print a description of an individual parameter in gsParams, as specified by its dictionary key. If key is None, print all parameter descriptions.

Parameters:	key (str) – dictionary key within gsParams

Save¶

GsParams.save(filename)¶: Save the current gsParam configuration to the given file

Load¶

GsParams.load(filename)¶: Load the gsParam configuration from the given file

Reset System Default¶

static GsParams.reset_systemdefault()¶: Overwrite the system defaults stored in %USER%/.gsParams with the default parameters of GsParams

Set System Default¶

GsParams.set_systemdefault()¶: Write the current configuration in self to the system defaults in %USER%/.gsParams

Get System Default¶

GsParams.get_systemdefault(confirm_autoload=False)¶

Get the gsParams stored in the system defaults in %USER%/.gsParams. confirm_autoload is passed only on the very first call on module init.

Parameters:	confirm_autoload (bool) – if `True`, and the gsParam `config.autoload.gsparams` stored in the loaded file is also True, then the stored defaults are loaded. Else, nothing

gsParam Descriptions¶

Config¶

config.verbose¶

Expected Type: bool, Default: True

If true, mentions when the gsParams are updated automatically when pygeostat is loaded. Useful for interactive sessions

config.autoload.gsparams¶

Expected Type: bool, Default: False

If True the gsParams configurations found in %USER%/.gsParams are parsed and loaded when pygeostat loads

config.autoload.gsplotstyle¶

Expected Type: bool, Default: False

If True the gsPlotStyle configurations found in %USER%/.gsParams are parsed and loaded when pygeostat loads

config.nprocess¶

Expected Type: int, None, Default: 4

The number of parallel processes to run functions that provide that functionality

config.getpar¶

Expected Type: bool, Default: False

If True, getpar=True when calling pygeostat.Program() with getpar=None

Plotting¶

plotting.unit¶

Expected Type: string, None, Default: "m"

The unit (str) that appears in spatial/map/variogram plots e.g., m or ft. Use None if no unit should be displayed.

plotting.xname¶

Expected Type: string, None, Default: "Easting"

Name (str) that is used for the x coordinate label for map/cross-section plots, e.g., Easting or X

plotting.yname¶

Expected Type: string, None, Default: "Northing"

Name (str) that is used for the y coordinate label for map/cross-section plots, e.g., Northing or Y

plotting.zname¶

Expected Type: string, None, Default: "Elevation"

Name (str) that is used for the z coordinate label for map/cross-section plots, e.g., Elevation or Z

plotting.xabbrev¶

Expected Type: string, None, Default: "E"

Abbreviated name (str) that is used for the x coordinate label for map/cross-section plots, e.g., Easting or X

plotting.yabbrev¶

Expected Type: string, None, Default: "N"

Abbreviated name (str) that is used for the y coordinate label for map/cross-section plots, e.g., Northing or Y

plotting.zabbrev¶

Expected Type: string, None, Default: "Elev"

Abbreviated name (str) that is used for the z coordinate label for map/cross-section plots, e.g., Elevation or Z

plotting.gammasize¶

Expected Type: float, Default: 3.0

The size of gamma symbols in variogram plots are Matplotlib.rcParams[“font.size”] multiplied with this value.

plotting.lagname¶

Expected Type: string, None, Default: "Lag Distance"

Name (str) to use on the x-axis of variogram plots, e.g., Lag or h

plotting.rotateticks¶

Expected Type: list, None, Default: [0, 0]

If None, the pygeostat tickoverlap attempts to optimize tick, label angles to minimize overlap in the absence of a kwarg., If [xangle, yangle] (e.g., [0, 0], then these angles are used in the absence of a kwarg.

plotting.grid¶

Expected Type: bool, Default: False

If True, a grid is plotted in pygeostat ploting function unless, overridden by the associated kwarg

plotting.axis_xy¶

Expected Type: bool, Default: False

Converts plotting axes to GSLIB-style visibility (only left and bottom visible) if axis_xy is True. See plotting.axis_xy_spatial for the default setting of functions such as pixelplt and locmap.

plotting.axis_xy_spatial¶

Expected Type: bool, Default: False

axis_xy setting that is specific to spatial plotting functions such as locmap and pixelplt. Provided since many users prefer axis_xy to be applied to all plots (via plotting.axis_xy) other than spatial plots.

plotting.stat_fontsize¶

Expected Type: float, None, Default: None

Font size of statistics in pygeosat plots. If None, then the font size matches rcParams[font.size]. If a fraction, then the font size is rcParams[font.size]*stat_fontsize. If greater than or equal to 1, then stat_fontsize is the font size.

plotting.stat_ha¶

Expected Type: string, Default: "right"

The horizontal alignment of statistics in plots, which should be one of “right”, “left” or “center”

plotting.roundstats¶

Expected Type: bool, Default: True

Display a set number of significant figures (False) or digits (True) for statistics in plots.

plotting.sigfigs¶

Expected Type: int, Default: 2

Significant figures (roundstats=False) or digits (roundstats=True) for statistics in plots.

plotting.cmap¶

Expected Type: string, Default: "viridis"

Matplotlib colormap object or a registered Matplotlib colormap, which is used for continuous variables

plotting.cmap_cat¶

Expected Type: dict, string, Default: "tab20"

Matplotlib colormap object or a registered Matplotlib colormap, which is used for categorical variables

plotting.assumecat¶

Expected Type: int, Default: 11

When executing plotting functions, data is assumed to be categorical for the purposes of selecting colormaps, if less than this number of unique values are found

plotting.histplt.facecolor¶

Expected Type: color, Default: .9

Color of the histogram faces for the histplt function.

plotting.histplt.edgecolor¶

Expected Type: color, Default: k

Color of the histogram edges for the histplt function.

plotting.histplt.edgeweight¶

Expected Type: float, None, Default: None

lw of the histogram edges for the histplt function.

plotting.histplt.cdfcolor¶

Expected Type: color, Default: .5

Color of the CDF for the histplt function.

plotting.histplt.histbins¶

Expected Type: int, None, Default: 15

Number of bins for a histogram (not CDF) calculation.

plotting.histplt.stat_blk¶

Expected Type: list, string, Default: "all"

Default stat_blk setting, which is either a string code, such as all or minimal, or a list of valid statistic names

plotting.histplt.stat_xy¶

Expected Type: list, Default: (0.95, 0.95)

Location of the histogram stats location as a tuple of (xloc, yloc), where the locations should be between 0 and 1.

plotting.histplt.stat_xy_cdf¶

Expected Type: list, Default: (0.95, 0.05)

Location of the CDF stats location as a tuple of (xloc, yloc), where the locations should be 0 to 1.

plotting.histpltsim.refclr¶

Expected Type: color, Default: C3

Color of the reference CDF

plotting.histpltsim.simclr¶

Expected Type: color, Default: 0.2

Color of the realization CDFs

plotting.histpltsim.alpha¶

Expected Type: float, None, Default: 0.5

Transparency of the realizations CDFs

plotting.locmap.s¶

Expected Type: float, None, Default: None

Size of scatter in locmap (and pixelplt), which is based on Matplotlib.rcParams if None

plotting.locmap.c¶

Expected Type: color, Default: .4

Color of scatter in locmap (and pixelplt), which is a valid Matplotlib color specifier

plotting.scatplt.s¶

Expected Type: float, None, Default: None

Size of scatter in scatplt, which is based on Matplotlib.rcParams if None

plotting.scatplt.c¶

Expected Type: kde, color, Default: kde

Color of scatter in scatplt, which is either a valid Matplotlib color specifier, or the “KDE” string. KDE leads to calculation of the kernel density estimate at each scatter location

plotting.scatplt.cmap¶

Expected Type: string, Default: "viridis"

Matplotlib colormap object or a registered Matplotlib colormap which overrides plotting.cmap

plotting.scatplt.alpha¶

Expected Type: float, None, Default: 1.0

Alpha transparency of scatter in scatplt, which should be between 0 and 1.

plotting.scatplt.stat_blk¶

Expected Type: list, string, Default: "pearson"

Statistics that are plotted in scatplt, which should be either “all” or a list that may contains the strings: [“count”, “pearson”, “spearmanr”]

plotting.scatplt.stat_xy¶

Expected Type: list, Default: (0.95, 0.05)

A 2-list that provides the x/y location of the statistics block

plotting.varplt.color¶

Expected Type: color, Default: .5

Color for varplt

plotting.varplt.ms¶

Expected Type: float, Default: 2.0

Marker size for varplt (e.g. experimental dot size)

plotting.varpltsim.refclr¶

Expected Type: color, Default: C3

Color of the reference variogram

plotting.varpltsim.simclr¶

Expected Type: color, Default: 0.2

Color of the realization variograms

plotting.varpltsim.alpha¶

Expected Type: float, None, Default: 0.5

Transparency of the realizations variograms

plotting.vplot.colors¶

Expected Type: list, string, Default: ['C0', 'C1', 'C2']

Colors of the major, minor and vertical direction variograms, which is used by the Variogram.plot function. May be a 3-list, or a color pallete in gs.avail_palettes

Data¶

data.tmin¶

Expected Type: float, None, Default: -998.0

Values less than this number (float or int) are assigned NaN on import by all io read functions, e.g., -98 or -998. Using -1.0e21 or False disables this functionality.

data.null¶

Expected Type: float, None, Default: -999.0

NaN values are assigned this number (float or int) by io write functions (excluding write_vtk), e.g., -99, -999, or -999.0. Using None disables the functionality, but will likely lead to issues in the case of subsequent GSLIB operations.

data.null_vtk¶

Expected Type: float, None, Default: False

NaN values are assigned this number (float or int) by the write_vtk function, e.g., -99, -999, or -999.0. Using None disables the functionality, which is recommended since NaN values are handled by Paraview.

data.griddef¶

Expected Type: griddef, None, Default: None

When initializing a DataFile, this will be used as DataFile.GridDef if GridDef.count() matches DataFile.shape[0]. A pygeostat.GridDef object or valid gridstr/gridarr may be used for intitialization.

data.nreal¶

Expected Type: int, None, Default: None

The number of realizations for modeling (once implemented) and model checking (Variogram.varsim, histpltsim, etc.) routines.