geostats

Geostatistics in the PEST(++) realm

ExpVario

Bases: Vario2d

Exponential variogram derived type

Parameters:

Name	Type	Description	Default
contribution	float	sill of the variogram	required
a	`float`	(practical) range of correlation	required
anisotropy	`float`	Anisotropy ratio. Default is 1.0	1.0
bearing		(float, optional): angle in degrees East of North corresponding to anisotropy ellipse. Default is 0.0	required
name	`str`, optinoal	name of the variogram. Default is "var1"	'var1'

Example::

v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)

bearing_rads property

get the bearing of the Vario2d in radians

Returns:

Type	Description
	float: the Vario2d bearing in radians

rotation_coefs property

get the rotation coefficients in radians

Returns:

Type	Description
	[float]: the rotation coefficients implied by Vario2d.bearing

__str__()

get the str representation of Vario2d

Returns:

Type	Description
	str: string rep

covariance(pt0, pt1)

get the covariance between two points implied by Vario2d

Parameters:

Name	Type	Description	Default
pt0		([float]): first point x and y	required
pt1		([float]): second point x and y	required

Returns:

Type	Description
	float: covariance between pt0 and pt1

covariance_matrix(x, y, names=None, cov=None)

build a pyemu.Cov instance implied by Vario2d

Parameters:

Name	Type	Description	Default
x	[`float`]	x-coordinate locations	required
y	[`float`]	y-coordinate locations	required
names	[`str`]	names of locations. If None, cov must not be None	None
cov	`pyemu.Cov`	an existing Cov instance. Vario2d contribution is added to cov	None

Returns:

Type	Description
	pyemu.Cov: the covariance matrix for x, y implied by Vario2d

Note

either names or cov must not be None.

covariance_points(x0, y0, xother, yother)

get the covariance between base point (x0,y0) and other points xother,yother implied by Vario2d

Parameters:

Name	Type	Description	Default
x0	`float`	x-coordinate	required
y0	`float`	y-coordinate	required
xother	[`float`]	x-coordinates of other points	required
yother	[`float`]	y-coordinates of other points	required

Returns:

Type	Description
	numpy.ndarray: a 1-D array of covariance between point x0,y0 and the
	points contained in xother, yother. len(cov) = len(xother) =
	len(yother)

inv_h(h)

the inverse of the h_function. Used for plotting

Parameters:

Name	Type	Description	Default
h	`float`	the value of h_function to invert	required

Returns:

Type	Description
	float: the inverse of h

plot(**kwargs)

get a cheap plot of the Vario2d

Parameters:

Name	Type	Description	Default
**kwargs	`dict`	keyword arguments to use for plotting	{}

Returns:

Type	Description
	matplotlib.pyplot.axis

Note

optional arguments in kwargs include "ax" (existing matplotlib.pyplot.axis). Other kwargs are passed to matplotlib.pyplot.plot()

to_struct_file(f)

write the Vario2d to a PEST-style structure file

Parameters:

Name	Type	Description	Default
f	`str`	filename to write to. f can also be an open file handle.	required

GauVario

Bases: Vario2d

Gaussian variogram derived type

Parameters:

Name	Type	Description	Default
contribution	float	sill of the variogram	required
a	`float`	(practical) range of correlation	required
anisotropy	`float`	Anisotropy ratio. Default is 1.0	1.0
bearing		(float, optional): angle in degrees East of North corresponding to anisotropy ellipse. Default is 0.0	required
name	`str`, optinoal	name of the variogram. Default is "var1"	'var1'

Example::

v = pyemu.utils.geostats.GauVario(a=1000,contribution=1.0)

Note

the Gaussian variogram can be unstable (not invertible) for long ranges.

bearing_rads property

get the bearing of the Vario2d in radians

Returns:

Type	Description
	float: the Vario2d bearing in radians

rotation_coefs property

get the rotation coefficients in radians

Returns:

Type	Description
	[float]: the rotation coefficients implied by Vario2d.bearing

__str__()

get the str representation of Vario2d

Returns:

Type	Description
	str: string rep

covariance(pt0, pt1)

get the covariance between two points implied by Vario2d

Parameters:

Name	Type	Description	Default
pt0		([float]): first point x and y	required
pt1		([float]): second point x and y	required

Returns:

Type	Description
	float: covariance between pt0 and pt1

covariance_matrix(x, y, names=None, cov=None)

build a pyemu.Cov instance implied by Vario2d

Parameters:

Name	Type	Description	Default
x	[`float`]	x-coordinate locations	required
y	[`float`]	y-coordinate locations	required
names	[`str`]	names of locations. If None, cov must not be None	None
cov	`pyemu.Cov`	an existing Cov instance. Vario2d contribution is added to cov	None

Returns:

Type	Description
	pyemu.Cov: the covariance matrix for x, y implied by Vario2d

Note

either names or cov must not be None.

covariance_points(x0, y0, xother, yother)

get the covariance between base point (x0,y0) and other points xother,yother implied by Vario2d

Parameters:

Name	Type	Description	Default
x0	`float`	x-coordinate	required
y0	`float`	y-coordinate	required
xother	[`float`]	x-coordinates of other points	required
yother	[`float`]	y-coordinates of other points	required

Returns:

Type	Description
	numpy.ndarray: a 1-D array of covariance between point x0,y0 and the
	points contained in xother, yother. len(cov) = len(xother) =
	len(yother)

inv_h(h)

the inverse of the h_function. Used for plotting

Parameters:

Name	Type	Description	Default
h	`float`	the value of h_function to invert	required

Returns:

Type	Description
	float: the inverse of h

plot(**kwargs)

get a cheap plot of the Vario2d

Parameters:

Name	Type	Description	Default
**kwargs	`dict`	keyword arguments to use for plotting	{}

Returns:

Type	Description
	matplotlib.pyplot.axis

Note

optional arguments in kwargs include "ax" (existing matplotlib.pyplot.axis). Other kwargs are passed to matplotlib.pyplot.plot()

to_struct_file(f)

write the Vario2d to a PEST-style structure file

Parameters:

Name	Type	Description	Default
f	`str`	filename to write to. f can also be an open file handle.	required

GeoStruct

Bases: object

a geostatistical structure object that mimics the behavior of a PEST geostatistical structure. The object contains variogram instances and (optionally) nugget information.

Parameters:

Name	Type	Description	Default
nugget	`float` (optional)	nugget contribution. Default is 0.0	0.0
variograms		([pyemu.Vario2d] (optional)): variogram(s) associated with this GeoStruct instance. Default is empty list	required
name	`str` (optional)	name to assign the structure. Default is "struct1".	'struct1'
transform	`str` (optional)	the transformation to apply to the GeoStruct. Can be "none" or "log", depending on the transformation of the property being represented by the GeoStruct. Default is "none"	'none'

Example::

v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)
gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)
gs.plot()
# get a covariance matrix implied by the geostruct for three points
px = [0,1000,2000]
py = [0,0,0]
pnames ["p1","p2","p3"]
cov = gs.covariance_matrix(px,py,names=pnames)

nugget = float(nugget) instance-attribute

float: the nugget effect contribution

sill property

get the sill of the GeoStruct

Returns:

Type	Description
	float: the sill of the (nested) GeoStruct, including
	nugget and contribution from each variogram

transform = transform instance-attribute

str: the transformation of the GeoStruct. Can be 'log' or 'none'

variograms = variograms instance-attribute

[pyemu.utils.geostats.Vario2d]: a list of variogram instances

__str__()

the str representation of the GeoStruct

Returns:

Type	Description
	str: the string representation of the GeoStruct

covariance(pt0, pt1)

get the covariance between two points implied by the GeoStruct. This is used during the ordinary kriging process to get the RHS

Parameters:

Name	Type	Description	Default
pt0	[`float`]	xy-pair	required
pt1	[`float`]	xy-pair	required

Returns:

Type	Description
	float: the covariance between pt0 and pt1 implied
	by the GeoStruct

Example::

p1 = [0,0]
p2 = [1,1]
v = pyemu.geostats.ExpVario(a=0.1,contribution=1.0)
gs = pyemu.geostats.Geostruct(variograms=v)
c = gs.covariance(p1,p2)

covariance_matrix(x, y, names=None, cov=None)

build a pyemu.Cov instance from GeoStruct

Parameters:

Name	Type	Description	Default
x	[`floats`]	x-coordinate locations	required
y	[`float`]	y-coordinate locations	required
names	[`str`] (optional)	names of location. If None, cov must not be None. Default is None.	None
cov	`pyemu.Cov`	an existing Cov instance. The contribution of this GeoStruct is added to cov. If cov is None, names must not be None. Default is None	None

Returns:

Type	Description
	pyemu.Cov: the covariance matrix implied by this
	GeoStruct for the x,y pairs. cov has row and column
	names supplied by the names argument unless the "cov"
	argument was passed.

Note

either "names" or "cov" must be passed. If "cov" is passed, cov.shape must equal len(x) and len(y).

Example::

pp_df = pyemu.pp_utils.pp_file_to_dataframe("hkpp.dat")
cov = gs.covariance_matrix(pp_df.x,pp_df.y,pp_df.name)
cov.to_binary("cov.jcb")

covariance_points(x0, y0, xother, yother)

Get the covariance between point (x0,y0) and the points contained in xother, yother.

Parameters:

Name	Type	Description	Default
x0	`float`	x-coordinate	required
y0	`float`	y-coordinate	required
xother	[`float`]	x-coordinates of other points	required
yother	[`float`]	y-coordinates of other points	required

Returns:

Type	Description
	numpy.ndarray: a 1-D array of covariance between point x0,y0 and the
	points contained in xother, yother. len(cov) = len(xother) =
	len(yother)

Example::

x0,y0 = 1,1
xother = [2,3,4,5]
yother = [2,3,4,5]
v = pyemu.geostats.ExpVario(a=0.1,contribution=1.0)
gs = pyemu.geostats.Geostruct(variograms=v)
c = gs.covariance_points(x0,y0,xother,yother)

plot(**kwargs)

make a cheap plot of the GeoStruct

Parameters:

Name	Type	Description	Default
**kwargs		(dict) keyword arguments to use for plotting.	required

Returns: matplotlib.pyplot.axis: the axis with the GeoStruct plot

Note

optional arguments include "ax" (an existing axis), "individuals" (plot each variogram on a separate axis), "legend" (add a legend to the plot(s)). All other kwargs are passed to matplotlib.pyplot.plot()

Example::

v = pyemu.geostats.ExpVario(a=0.1,contribution=1.0)
gs = pyemu.geostats.Geostruct(variograms=v)
gs.plot()

same_as_other(other)

compared to geostructs for similar attributes

Parameters:

Name	Type	Description	Default
other	`pyemu.geostats.Geostruct`	the other one	required

Returns:

Name	Type	Description
same	`bool`	True is the other and self have the same characteristics

to_struct_file(f)

write a PEST-style structure file

Parameters:

Name	Type	Description	Default
f	`str`	file to write the GeoStruct information in to. Can also be an open file handle	required

OrdinaryKrigeOrg

Bases: object

Ordinary Kriging using Pandas and Numpy.

Parameters:

Name	Type	Description	Default
geostruct	`GeoStruct`	a pyemu.geostats.GeoStruct to use for the kriging	required
point_data	`pandas.DataFrame`	the conditioning points to use for kriging. point_data must contain columns "name", "x", "y".	required

Note

if point_data is an str, then it is assumed to be a pilot points file and is loaded as such using pyemu.pp_utils.pp_file_to_dataframe()

If zoned interpolation is used for grid-based interpolation, then point_data must also contain a "zone" column

Example::

import pyemu
v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)
gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)
pp_df = pyemu.pp_utils.pp_file_to_dataframe("hkpp.dat")
ok = pyemu.utils.geostats.OrdinaryKrige(gs,pp_df)

calc_factors(x, y, minpts_interp=1, maxpts_interp=20, search_radius=10000000000.0, verbose=False, pt_zone=None, forgive=False, num_threads=1, idx_vals=None, remove_negative_factors=True)

Calculate ordinary kriging factors (weights) for the points represented by arguments x and y

Parameters:

Name	Type	Description	Default
x	[`float`]	x-coordinates to calculate kriging factors for	required
y	([`float`]	y-coordinates to calculate kriging factors for	required
minpts_interp	`int`	minimum number of point_data entries to use for interpolation at a given x,y interplation point. interpolation points with less than minpts_interp point_data found will be skipped (assigned np.nan). Default is 1	1
maxpts_interp	`int`	maximum number of point_data entries to use for interpolation at a given x,y interpolation point. A larger maxpts_interp will yield "smoother" interplation, but using a large maxpts_interp will slow the (already) slow kriging solution process and may lead to memory errors. Default is 20.	20
search_radius	`float`	the size of the region around a given x,y interpolation point to search for point_data entries. Default is 1.0e+10	10000000000.0
verbose	`bool`	a flag to echo process to stdout during the interpolatino process. Default is False	False
pt_zone	int	Optional zone value to slice point_data for zoned factor calcs.	None
forgive	`bool`	flag to continue if inversion of the kriging matrix fails at one or more interpolation points. Inversion usually fails if the kriging matrix is singular, resulting from point_data entries closer than EPSILON distance. If True, warnings are issued for each failed inversion. If False, an exception is raised for failed matrix inversion.	False
num_threads	`int`	number of multiprocessing workers to use to try to speed up kriging in python. Default is 1.	1
idx_vals	iterable of `int`	optional index values to use in the interpolation dataframe. This is used to set the proper node number in the factors file for unstructured grids.	None
remove_negative_factors	`bool`	option to remove negative Kriging factors, following the method of Deutsch (1996) https://doi.org/10.1016/0098-3004(96)00005-2. Default is True	True

Returns: pandas.DataFrame: a dataframe with information summarizing the ordinary kriging process for each interpolation points

Note

this method calls either OrdinaryKrige.calc_factors_org() or OrdinaryKrige.calc_factors_mp() depending on the value of num_threads

Example::

v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)
gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)
pp_df = pyemu.pp_utils.pp_file_to_dataframe("hkpp.dat")
ok = pyemu.utils.geostats.OrdinaryKrige(gs,pp_df)
x = np.arange(100)
y = np.ones_like(x)
zone_array = y.copy()
zone_array[:zone_array.shape[0]/2] = 2
# only calc factors for the points in zone 1
ok.calc_factors(x,y,pt_zone=1)
ok.to_grid_factors_file("zone_1.fac",ncol=x.shape[0])

calc_factors_grid(spatial_reference, zone_array=None, minpts_interp=1, maxpts_interp=20, search_radius=10000000000.0, verbose=False, var_filename=None, forgive=False, num_threads=1)

calculate kriging factors (weights) for a structured grid.

Parameters:

Name	Type	Description	Default
`flopy.ModelGrid`)		a spatial reference that describes the orientation and spatial projection of the model grid. Needs attributes: [xcentergrid, ycentergrid, nrow, ncol, grid_type, and ncpl (only if grid type=='vertex')].	required
zone_array	`numpy.ndarray`	an integer array of zones to use for kriging. If not None, then point_data must also contain a "zone" column. point_data entries with a zone value not found in zone_array will be skipped. If None, then all point_data will (potentially) be used for interpolating each grid node. Default is None	None
minpts_interp	`int`	minimum number of point_data entries to use for interpolation at a given grid node. grid nodes with less than minpts_interp point_data found will be skipped (assigned np.nan). Default is 1	1
verbose		(bool): a flag to echo process to stdout during the interpolatino process. Default is False	required
var_filename	Path - like	a filename to save the kriging variance for each interpolated grid node. Default is None.	None
forgive	`bool`	flag to continue if inversion of the kriging matrix fails at one or more grid nodes. Inversion usually fails if the kriging matrix is singular, resulting from point_data entries closer than EPSILON distance. If True, warnings are issued for each failed inversion. If False, an exception is raised for failed matrix inversion.	False
num_threads	`int`	number of multiprocessing workers to use to try to speed up kriging in python. Default is 1.	1

Returns: pandas.DataFrame: a dataframe with information summarizing the ordinary kriging process for each grid node. Not returned if try_use_ppu is True.

Note

this method calls OrdinaryKrige.calc_factors() this method is the main entry point for grid-based kriging factor generation

Example::

import flopy
v = pyemu.utils.geostats.ExpVario(a=1000,contribution=1.0)
gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)
pp_df = pyemu.pp_utils.pp_file_to_dataframe("hkpp.dat")
ok = pyemu.utils.geostats.OrdinaryKrige(gs,pp_df)
m = flopy.modflow.Modflow.load("mymodel.nam")
df = ok.calc_factors_grid(m.sr,zone_array=m.bas6.ibound[0].array,
                          var_filename="ok_var.dat")
ok.to_grid_factor_file("factors.dat")

check_point_data_dist(rectify=False)

check for point_data entries that are closer than EPSILON distance - this will cause a singular kriging matrix.

Parameters:

Name	Type	Description	Default
rectify	`bool`	flag to fix the problems with point_data by dropping additional points that are closer than EPSILON distance. Default is False	False

Note

this method will issue warnings for points that are closer than EPSILON distance

to_grid_factors_file(filename, points_file='points.junk', zone_file='zone.junk', ncol=None)

write a PEST-style factors file. This file can be used with the fac2real() method to write an interpolated structured or unstructured array

Parameters:

Name	Type	Description	Default
filename	path - like	factor filename	required
points_file	`str`	points filename to add to the header of the factors file. This is not used by the fac2real() method. Default is "points.junk"	'points.junk'
zone_file	`str`	zone filename to add to the header of the factors file. This is not used by the fac2real() method. Default is "zone.junk"	'zone.junk'

Note

this method should be called after OrdinaryKrige.calc_factors_grid() for structured models or after OrdinaryKrige.calc_factors() for unstructured models.

OrdinaryKrigePPU

Bases: object

Ordinary Kriging using Pypestutils PPU for factor calculation.

Off-loading the much of the computational effort to Pypestutils.

__init__(geostruct, point_data, express=False, auto=False)

Initialize OrdinaryKrigePPU object.

Parameters:

Name	Type	Description	Default
geostruct None		Dummy argument to match OrdinaryKrige signature.	required
point_data	`pandas.DataFrame`	the conditioning points to use for kriging. point_data must contain columns "name", "x", "y". Optionally "zone".	required
auto	bool	if set to true, use pypestutil's auto krige function, which automatically estimates search radius and variogram parameters based on pilot point density	False

Note

if point_data is an str, then it is assumed to be a pilot points file and is loaded as such using pyemu.pp_utils.pp_file_to_dataframe()

calc_factors(targets, geostruct, fac_fname='factors.dat', zone_array=None, **kwargs)

PPU based calculation of interpolation factors.

Parameters:

Name	Type	Description	Default
targets	multiple	Object from which x and y coordinates can be extracted. This can be a flopy modelgrid object with (xcellcenters, and ycellcenters) attribs. Or it can be a pyemu spatial reference with (xcentergrid and ycentergrid) attribs. Or a DataFrame with ('x', 'y') columns. Or a {'node':(x,y)} dict. Note if type(targets)==dict, the keys will e sorted, zone array will be expected to be in the order of the sorted keys and the output will also be in that order.	required
geostruct	(Vario2d, Geostructure, dict or path - like)	If dict, should have keys 'corrlen' (required), 'aniso', 'bearing', 'vartype'. vartype is an integer with 1 for Spherical, 2 for Exponential (default) and 3 for Gaussian.	required
fac_fname	path - like	Filename to save binary factors file	'factors.dat'
zone_array	array - like		None
**kwargs	dict	Additional keyword args for passing to factor calculations. e.g.: 'minpts_interp', 'maxpts_interp', 'search_dist' and 'search_radius'	{}

Returns:

SpecSim2d

Bases: object

2-D unconditional spectral simulation for regular grids

Parameters:

Name	Type	Description	Default
delx	`numpy.ndarray`	a 1-D array of x-dimension cell centers (or leading/trailing edges). Only the distance between points is important	required
dely	`numpy.ndarray`	a 1-D array of y-dimension cell centers (or leading/trailing edges). Only the distance between points is important	required
geostruct	`pyemu.geostats.Geostruct`	geostatistical structure instance	required

Example::

v = pyemu.utils.geostats.ExpVario(a=100,contribution=1.0)
gs = pyemu.utils.geostats.GeoStruct(variograms=v,nugget=0.5)
delx,dely = np.ones(150), np.ones(50)
ss = pyemu.utils.geostats.SpecSim2d(delx,dely,gs)
arr = np.squeeze(ss.draw_arrays(num_reals=1))*.05 + .08
plt.imshow(arr)
plt.colorbar(shrink=.40)

draw_arrays(num_reals=1, mean_value=1.0, rng=None)

draw realizations

Parameters:

Name	Type	Description	Default
num_reals	`int`	number of realizations to generate	1
mean_value	`float`	the mean value of the realizations	1.0
rng	`numpy.random.RandomState`	random number generator if not using default from pyemu.en	None

Returns:

Type	Description
	numpy.ndarray: a 3-D array of realizations. Shape
	is (num_reals,self.dely.shape[0],self.delx.shape[0])

Note: log transformation is respected and the returned reals array is in linear space

draw_conditional(seed, obs_points, sg, base_values_file, local=True, factors_file=None, num_reals=1, mean_value=1.0, R_factor=1.0)

Generate a conditional, correlated random field using the Spec2dSim object, a set of observation points, and a factors file.

The conditional field is made by generating an unconditional correlated random
field that captures the covariance in the variogram and conditioning it by kriging
a second surface using the value of the random field as observations.
This second conditioning surface provides an estimate of uncertainty (kriging error)
away from the observation points. At the observation points, the kriged surface is
equal to (less nugget effects) the observation. The conditioned correlated field
is then generated using: T(x) = Z(x) + [S(x) − S∗(x)]
where T(x) is the conditioned simulation, Z(x) is a kriging estimator of the
unknown field, S(x) is an unconditioned random field with the same covariance
structure as the desired field, and S∗(x) is a kriging estimate of the unconditioned
random field using its values at the observation points (pilot points).
[S(x) − S∗(x)] is an estimate of the kriging error.

This approach makes T(x) match the observed values at the observation points
(x_a, y_z), T(a) = Z(a), and have a structure away from the observation points that
follows the variogram used to generate Z, S, and S∗.

Chiles, J-P, and Delfiner, P., Geostatistics- Modeling Spatial Uncertainty: Wiley,
    London, 695 p.

Parameters:

Name	Type	Description	Default
seed	`int`	integer used for random seed. If seed is used as a PEST parameter, then passing the same value for seed will yield the same conditioned random fields. This allows runs to be recreated given an ensemble of seeds.	required
obs_points	`str` or `dataframe`	locations for observation points. Either filename in pyemupilot point file format: ["name","x","y","zone","parval1"] ora dataframe with these columns. Note that parval1 is not used.	required
base_values_file	`str`	filename containing 2d array with the base parameter values from which the random field will depart (Z(x)) above. Values of Z(x) are used for conditioning, not parval1 in the observation point file.	required
factors_file	`str`	name of the factors file generated using the locations of the observation points and the target grid. If None this file will be generated and called conditional_factors.dat; but this is a slow step and should not generally be called for every simulation.	None
sg		flopy StructuredGrid object	required
local	`boolean`	whether coordinates in obs_points are in local (model) or map coordinates	True
num_reals	`int`	number of realizations to generate	1
mean_value	`float`	the mean value of the realizations	1.0
R_factor	`float`	a factor to scale the field, sometimes the variation from the geostruct parameters is larger or smaller than desired.	1.0

Returns:

Type	Description
	numpy.ndarray: a 3-D array of realizations. Shape is (num_reals, self.dely.shape[0], self.delx.shape[0])

Note: log transformation is respected and the returned reals array is in arithmetic space

grid_is_regular(delx, dely, tol=0.0001) staticmethod

check that a grid is regular using delx and dely vectors

Parameters:

Name	Type	Description	Default
delx		numpy.ndarray a 1-D array of x-dimension cell centers (or leading/trailing edges). Only the distance between points is important	required
dely		numpy.ndarray a 1-D array of y-dimension cell centers (or leading/trailing edges). Only the distance between points is important	required
tol		float (optional) tolerance to determine grid regularity. Default is 1.0e-4	required

Returns:

Type	Description
	bool: flag indicating if the grid defined by delx and dely is regular

grid_par_ensemble_helper(pst, gr_df, num_reals, sigma_range=6, logger=None, rng=None)

wrapper around SpecSim2d.draw() designed to support PstFromFlopy and PstFrom grid-based parameters

Parameters:

Name	Type	Description	Default
pst	`pyemu.Pst`	a control file instance	required
gr_df	`pandas.DataFrame`	a dataframe listing parval1, pargp, i, j for each grid based parameter	required
num_reals	`int`	number of realizations to generate	required
sigma_range	`float` (optional)	number of standard deviations implied by parameter bounds in control file. Default is 6	6
logger	`pyemu.Logger` (optional)	a logger instance for logging	None
rng	`numpy.random.RandomState` (optional)	random number generator if not using default from pyemu.en	None

Returns:

Type	Description
	pyemu.ParameterEnsemble: an untransformed parameter ensemble of
	realized grid-parameter values

Note

the method processes each unique pargp value in gr_df and resets the sill of self.geostruct by the maximum bounds-implied variance of each pargp. This method makes repeated calls to self.initialize() to deal with the geostruct changes.

initialize()

prepare for spectral simulation.

Note

initialize() prepares for simulation by undertaking the fast FFT on the wave number matrix and should be called if the SpecSim2d.geostruct is changed. This method is called by the constructor.

SphVario

Bases: Vario2d

Spherical variogram derived type

Parameters:

Name	Type	Description	Default
contribution	float	sill of the variogram	required
a	`float`	(practical) range of correlation	required
anisotropy	`float`	Anisotropy ratio. Default is 1.0	1.0
bearing		(float, optional): angle in degrees East of North corresponding to anisotropy ellipse. Default is 0.0	required
name	`str`, optinoal	name of the variogram. Default is "var1"	'var1'

Example::

 v = pyemu.utils.geostats.SphVario(a=1000,contribution=1.0)

bearing_rads property

get the bearing of the Vario2d in radians

Returns:

Type	Description
	float: the Vario2d bearing in radians

rotation_coefs property

get the rotation coefficients in radians

Returns:

Type	Description
	[float]: the rotation coefficients implied by Vario2d.bearing

__str__()

get the str representation of Vario2d

Returns:

Type	Description
	str: string rep

covariance(pt0, pt1)

get the covariance between two points implied by Vario2d

Parameters:

Name	Type	Description	Default
pt0		([float]): first point x and y	required
pt1		([float]): second point x and y	required

Returns:

Type	Description
	float: covariance between pt0 and pt1

covariance_matrix(x, y, names=None, cov=None)

build a pyemu.Cov instance implied by Vario2d

Parameters:

Name	Type	Description	Default
x	[`float`]	x-coordinate locations	required
y	[`float`]	y-coordinate locations	required
names	[`str`]	names of locations. If None, cov must not be None	None
cov	`pyemu.Cov`	an existing Cov instance. Vario2d contribution is added to cov	None

Returns:

Type	Description
	pyemu.Cov: the covariance matrix for x, y implied by Vario2d

Note

either names or cov must not be None.

covariance_points(x0, y0, xother, yother)

get the covariance between base point (x0,y0) and other points xother,yother implied by Vario2d

Parameters:

Name	Type	Description	Default
x0	`float`	x-coordinate	required
y0	`float`	y-coordinate	required
xother	[`float`]	x-coordinates of other points	required
yother	[`float`]	y-coordinates of other points	required

Returns:

Type	Description
	numpy.ndarray: a 1-D array of covariance between point x0,y0 and the
	points contained in xother, yother. len(cov) = len(xother) =
	len(yother)

inv_h(h)

the inverse of the h_function. Used for plotting

Parameters:

Name	Type	Description	Default
h	`float`	the value of h_function to invert	required

Returns:

Type	Description
	float: the inverse of h

plot(**kwargs)

get a cheap plot of the Vario2d

Parameters:

Name	Type	Description	Default
**kwargs	`dict`	keyword arguments to use for plotting	{}

Returns:

Type	Description
	matplotlib.pyplot.axis

Note

optional arguments in kwargs include "ax" (existing matplotlib.pyplot.axis). Other kwargs are passed to matplotlib.pyplot.plot()

to_struct_file(f)

write the Vario2d to a PEST-style structure file

Parameters:

Name	Type	Description	Default
f	`str`	filename to write to. f can also be an open file handle.	required

Vario2d

Bases: object

base class for 2-D variograms.

Parameters:

Name	Type	Description	Default
contribution	float	sill of the variogram	required
a	`float`	(practical) range of correlation	required
anisotropy	`float`	Anisotropy ratio. Default is 1.0	1.0
bearing		(float, optional): angle in degrees East of North corresponding to anisotropy ellipse. Default is 0.0	required
name	`str`, optinoal	name of the variogram. Default is "var1"	'var1'

Note

This base class should not be instantiated directly as it does not implement an h_function() method.

bearing_rads property

get the bearing of the Vario2d in radians

Returns:

Type	Description
	float: the Vario2d bearing in radians

rotation_coefs property

get the rotation coefficients in radians

Returns:

Type	Description
	[float]: the rotation coefficients implied by Vario2d.bearing

__str__()

get the str representation of Vario2d

Returns:

Type	Description
	str: string rep

covariance(pt0, pt1)

get the covariance between two points implied by Vario2d

Parameters:

Name	Type	Description	Default
pt0		([float]): first point x and y	required
pt1		([float]): second point x and y	required

Returns:

Type	Description
	float: covariance between pt0 and pt1

covariance_matrix(x, y, names=None, cov=None)

build a pyemu.Cov instance implied by Vario2d

Parameters:

Name	Type	Description	Default
x	[`float`]	x-coordinate locations	required
y	[`float`]	y-coordinate locations	required
names	[`str`]	names of locations. If None, cov must not be None	None
cov	`pyemu.Cov`	an existing Cov instance. Vario2d contribution is added to cov	None

Returns:

Type	Description
	pyemu.Cov: the covariance matrix for x, y implied by Vario2d

Note

either names or cov must not be None.

covariance_points(x0, y0, xother, yother)

get the covariance between base point (x0,y0) and other points xother,yother implied by Vario2d

Parameters:

Name	Type	Description	Default
x0	`float`	x-coordinate	required
y0	`float`	y-coordinate	required
xother	[`float`]	x-coordinates of other points	required
yother	[`float`]	y-coordinates of other points	required

Returns:

Type	Description
	numpy.ndarray: a 1-D array of covariance between point x0,y0 and the
	points contained in xother, yother. len(cov) = len(xother) =
	len(yother)

inv_h(h)

the inverse of the h_function. Used for plotting

Parameters:

Name	Type	Description	Default
h	`float`	the value of h_function to invert	required

Returns:

Type	Description
	float: the inverse of h

plot(**kwargs)

get a cheap plot of the Vario2d

Parameters:

Name	Type	Description	Default
**kwargs	`dict`	keyword arguments to use for plotting	{}

Returns:

Type	Description
	matplotlib.pyplot.axis

Note

optional arguments in kwargs include "ax" (existing matplotlib.pyplot.axis). Other kwargs are passed to matplotlib.pyplot.plot()

to_struct_file(f)

write the Vario2d to a PEST-style structure file

Parameters:

Name	Type	Description	Default
f	`str`	filename to write to. f can also be an open file handle.	required

fac2real(pp_file=None, factors_file='factors.dat', out_file=None, upper_lim=1e+30, lower_lim=-1e+30, fill_value=1e+30, try_ppu=True, shape=None, mpts=None, transform='none', fac_ftype=0)

A replication of the PEST fac2real utility.

For creating an array from previously calculated kriging factors (weights). Will attempt to use pypestutils implementation if available and try_ppu is True, otherwise falls back to built-in pyemu implementation.

Parameters:

Name	Type	Description	Default
pp_file	str or DataFrame	PEST-type pilot points file or DataFrame with at least 'name' and 'parval1' columns.	None
factors_file	path - like	PEST-style factors file	'factors.dat'
out_file	path - like	filename of array to write. If None, array is returned, else value of out_file is returned. Default is None.	None
upper_lim	`float`	maximum interpolated value in the array. Values greater than upper_lim are set to fill_value	1e+30
lower_lim	`float`	minimum interpolated value in the array. Values less than lower_lim are set to fill_value	-1e+30
fill_value	`float`	the value to assign array nodes that are not interpolated	1e+30
try_ppu	`bool`	try to use pypestutils function. Default is True. Note, this will likely fail is fac file was not set up through ppu methods, as currently defaulting to binary option for speed.	True

PPU Specific Args

shape (tuple of int or str): ppu specific argument giving shape of the output array. Required for ppu options. NOT USED IF try_ppu IS False. mpts: (int) ppu specific argument for number of target points for interp. If not passed this will be implied from 'shape'. NOT USED IF try_ppu IS False. transform: (str) ppu specific argument for the data transform for interp. 'none' and 'log' are supported. Default is 'none'. NOT USED IF try_ppu IS False. fac_ftype: (int) ppu specific argument for the factors file type. Default is 0 (binary). NOT USED IF try_ppu IS False.

Returns:

Type	Description
	numpy.ndarray: if out_file is None
	str: if out_file it not None

Example::

pyemu.utils.geostats.fac2real("hkpp.dat",out_file="hk_layer_1.ref")

gslib_2_dataframe(filename, attr_name=None, x_idx=0, y_idx=1)

function to read a GSLIB point data file into a pandas.DataFrame

Parameters:

Name	Type	Description	Default
filename	`str`	GSLIB file	required
attr_name	`str`	the column name in the dataframe for the attribute. If None, GSLIB file can have only 3 columns. attr_name must be in the GSLIB file header	None
x_idx	`int`	the index of the x-coordinate information in the GSLIB file. Default is 0 (first column)	0
y_idx	`int`	the index of the y-coordinate information in the GSLIB file. Default is 1 (second column)	1

Returns:

Type	Description
	pandas.DataFrame: a dataframe of info from the GSLIB file

Note

assigns generic point names ("pt0, pt1, etc)

Example::

df = pyemu.utiils.geostats.gslib_2_dataframe("prop.gslib",attr_name="hk")

load_sgems_exp_var(filename)

read an SGEM experimental variogram into a sequence of pandas.DataFrames

Parameters:

Name	Type	Description	Default
filename	`str`	an SGEMS experimental variogram XML file	required

Returns:

Type	Description
	[pandas.DataFrame]: a list of pandas.DataFrames of x, y, pairs for each
	division in the experimental variogram

org_fac2real(factors_file, pp_file=None, pp_data=None, fill_value=1e+30)

original pyemu implementation of fac2real Args: factors_file (str): filename of PEST-style factors file pp_file (str): filename of PEST-style pilot points file pp_data (pd.DataFrame): dataframe of pilot point data with at least 'name' and 'parval1' columns.

ppu_fac2real(source_vals, factor_filename, mpts, out_shape, ppulib=None, transform='none', fac_ftype='binary', krigtype='ordinary', noint=None)

Calculate array from pre-defined kriging factors using pypestutils

Parameters:

Name	Type	Description	Default
source_vals	ndarray	array of values for interpolating (e.g pilot point values):	required
factor_filename	str	filename of pre-built kriging factors	required
mpts	int	number of points to interpolate to.	required
out_shape	tuple	shape of output array. Used to reshape PPU results	required
ppulib	PestUtilsLib	Pre-instantiated pypestutils PestUtilsLib object. If None, a new instance will be created and cleaned up within this call.	None
transform	str	Interpolation of transformed values. Options are "none" and "log".	'none'
fac_ftype	str or int	factor_filename file type. Options are '0:binary' and '1:text'. Application to binary factor files is more efficient.	'binary'
krigtype	int or str	kriging type. Options are 'ordinary' or 1 for ordinary kriging, 'simple' or 0 for simple kriging.	'ordinary'
noint	float	Fallback interpolation value for locations where no interpolation is possible. If None, defaults to 1.0 for 'none' transform and 0.0 for 'log' transform.	None

Returns:

read_sgems_variogram_xml(xml_file, return_type=GeoStruct)

function to read an SGEMS-type variogram XML file into a GeoStruct

Parameters:

Name	Type	Description	Default
xml_file	`str`	SGEMS variogram XML file	required
return_type	`object`	the instance type to return. Default is GeoStruct	GeoStruct

Returns:

Name	Type	Description
gs		GeoStruct

Example::

gs = pyemu.utils.geostats.read_sgems_variogram_xml("sgems.xml")

read_struct_file(struct_file, return_type=GeoStruct)

read an existing PEST-type structure file into a GeoStruct instance

Parameters:

Name	Type	Description	Default
struct_file	`str`	existing pest-type structure file	required
return_type	`object`	the instance type to return. Default is GeoStruct	GeoStruct

Returns:

Type	Description
	[pyemu.GeoStruct]: list of GeoStruct instances. If
	only one GeoStruct is in the file, then a GeoStruct is returned

Example::

gs = pyemu.utils.geostats.reads_struct_file("struct.dat")