1094843954

Build Type

github

Committed by GitHub

Commit Message

<a href="https://github.com/GeoStat-Framework/GSTools/commit/<a class=hub.com/GeoStat-Framework/GSTools/commit/b11fe888bc5d7b4e2e5fad0e51ab195c213f2ac4">b11fe888b<a href="https://github.com/GeoStat-Framework/GSTools/commit/b11fe888bc5d7b4e2e5fad0e51ab195c213f2ac4">">Merge </a><a class="double-link" href="https://github.com/GeoStat-Framework/GSTools/commit/<a class="double-link" href="https://github.com/GeoStat-Framework/GSTools/commit/3923da04e8806e7b0aded58b7c67cb96f24cfa4c">3923da04e</a>">3923da04e</a><a href="https://github.com/GeoStat-Framework/GSTools/commit/b11fe888bc5d7b4e2e5fad0e51ab195c213f2ac4"> into 21c97fc74">21c97fc74</a>

Pull Request Pull Request #197: Refactor: transform submodule; Field storage control; CondSRF optimization

Run Details

435 of 435 new or added lines in 20 files covered. (100.0%)

2758 of 2955 relevant lines covered (93.33%)

11.2 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

95.4

/gstools/transform/array.py

# -*- coding: utf-8 -*-
"""
GStools subpackage providing array transformations.

.. currentmodule:: gstools.transform.array

The following functions are provided

Transformations
^^^^^^^^^^^^^^^

.. autosummary::
   array_discrete
   array_boxcox
   array_zinnharvey
   array_force_moments
   array_to_lognormal
   array_to_uniform
   array_to_arcsin
   array_to_uquad
"""
# pylint: disable=C0103, C0123, R0911
from warnings import warn
import numpy as np
from scipy.special import erf, erfinv

__all__ = [
    "array_discrete",
    "array_boxcox",
    "array_zinnharvey",
    "array_force_moments",
    "array_to_lognormal",
    "array_to_uniform",
    "array_to_arcsin",
    "array_to_uquad",
]


def array_discrete(
    field, values, thresholds="arithmetic", mean=None, var=None
):
    """
    Discrete transformation.

    After this transformation, the field has only `len(values)` discrete
    values.

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    values : :any:`numpy.ndarray`
        The discrete values the field will take
    thresholds : :class:`str` or :any:`numpy.ndarray`, optional
        the thresholds, where the value classes are separated
        possible values are:
        * "arithmetic": the mean of the 2 neighbouring values
        * "equal": devide the field into equal parts
        * an array of explicitly given thresholds
        Default: "arithmetic"
    mean : :class:`float`or :any:`None`
        Mean of the field for "equal" thresholds. Default: np.mean(field)
    var : :class:`float`or :any:`None`
        Variance of the field for "equal" thresholds. Default: np.var(field)

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    if thresholds == "arithmetic":
        # just in case, sort the values
        values = np.sort(values)
        thresholds = (values[1:] + values[:-1]) / 2
    elif thresholds == "equal":
        mean = np.mean(field) if mean is None else float(mean)
        var = np.var(field) if var is None else float(var)
        values = np.asarray(values)
        n = len(values)
        p = np.arange(1, n) / n  # n-1 equal subdivisions of [0, 1]
        rescale = np.sqrt(var * 2)
        # use quantile of the normal distribution to get equal ratios
        thresholds = mean + rescale * erfinv(2 * p - 1)
    else:
        if len(values) != len(thresholds) + 1:
            raise ValueError(
                "discrete transformation: len(values) != len(thresholds) + 1"
            )
        values = np.asarray(values)
        thresholds = np.asarray(thresholds)
    # check thresholds
    if not np.all(thresholds[:-1] < thresholds[1:]):
        raise ValueError(
            "discrete transformation: thresholds need to be ascending"
        )
    # use a separate result so the intermediate results are not affected
    result = np.empty_like(field)
    # handle edge cases
    result[field <= thresholds[0]] = values[0]
    result[field > thresholds[-1]] = values[-1]
    for i, value in enumerate(values[1:-1]):
        result[
            np.logical_and(thresholds[i] < field, field <= thresholds[i + 1])
        ] = value
    return result


def array_boxcox(field, lmbda=1, shift=0):
    """
    (Inverse) Box-Cox transformation to denormalize data.

    After this transformation, the again Box-Cox transformed field is normal
    distributed.

    See: https://en.wikipedia.org/wiki/Power_transform#Box%E2%80%93Cox_transformation

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    lmbda : :class:`float`, optional
        The lambda parameter of the Box-Cox transformation.
        For ``lmbda=0`` one obtains the log-normal transformation.
        Default: ``1``
    shift : :class:`float`, optional
        The shift parameter from the two-parametric Box-Cox transformation.
        The field will be shifted by that value before transformation.
        Default: ``0``
    """
    field = np.asarray(field)
    result = field + shift
    if np.isclose(lmbda, 0):
        array_to_lognormal(result)
    if np.min(result) < -1 / lmbda:
        warn("Box-Cox: Some values will be cut off!")
    return (np.maximum(lmbda * result + 1, 0)) ** (1 / lmbda)


def array_zinnharvey(field, conn="high", mean=None, var=None):
    """
    Zinn and Harvey transformation to connect low or high values.

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    conn : :class:`str`, optional
        Desired connectivity. Either "low" or "high".
        Default: "high"
    mean : :class:`float` or :any:`None`, optional
        Mean of the given field. If None is given, the mean will be calculated.
        Default: :any:`None`
    var : :class:`float` or :any:`None`, optional
        Variance of the given field.
        If None is given, the variance will be calculated.
        Default: :any:`None`

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    mean = np.mean(field) if mean is None else float(mean)
    var = np.var(field) if var is None else float(var)
    result = np.abs((field - mean) / np.sqrt(var))
    result = np.sqrt(2) * erfinv(2 * erf(result / np.sqrt(2)) - 1)
    if conn == "high":
        result = -result
    return result * np.sqrt(var) + mean


def array_force_moments(field, mean=0, var=1):
    """
    Force moments of a normal distributed field.

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    mean : :class:`float`, optional
        Desired mean of the field.
        Default: 0
    var : :class:`float` or :any:`None`, optional
        Desired variance of the field.
        Default: 1

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    var_in = np.var(field)
    mean_in = np.mean(field)
    rescale = np.sqrt(var / var_in)
    return rescale * (field - mean_in) + mean


def array_to_lognormal(field):
    """
    Transform normal distribution to log-normal distribution.

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    return np.exp(field)


def array_to_uniform(field, mean=None, var=None):
    """
    Transform normal distribution to uniform distribution on [0, 1].

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    mean : :class:`float` or :any:`None`, optional
        Mean of the given field. If None is given, the mean will be calculated.
        Default: :any:`None`
    var : :class:`float` or :any:`None`, optional
        Variance of the given field.
        If None is given, the variance will be calculated.
        Default: :any:`None`

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    mean = np.mean(field) if mean is None else float(mean)
    var = np.var(field) if var is None else float(var)
    return 0.5 * (1 + erf((field - mean) / np.sqrt(2 * var)))


def array_to_arcsin(field, mean=None, var=None, a=None, b=None):
    """
    Transform normal distribution to arcsin distribution.

    See: https://en.wikipedia.org/wiki/Arcsine_distribution

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    mean : :class:`float` or :any:`None`, optional
        Mean of the given field. If None is given, the mean will be calculated.
        Default: :any:`None`
    var : :class:`float` or :any:`None`, optional
        Variance of the given field.
        If None is given, the mean will be calculated.
        Default: :any:`None`
    a : :class:`float`, optional
        Parameter a of the arcsin distribution (lower bound).
        Default: keep mean and variance
    b : :class:`float`, optional
        Parameter b of the arcsin distribution (upper bound).
        Default: keep mean and variance

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    mean = np.mean(field) if mean is None else float(mean)
    var = np.var(field) if var is None else float(var)
    a = mean - np.sqrt(2.0 * var) if a is None else float(a)
    b = mean + np.sqrt(2.0 * var) if b is None else float(b)
    return _uniform_to_arcsin(array_to_uniform(field, mean, var), a, b)


def array_to_uquad(field, mean=None, var=None, a=None, b=None):
    """
    Transform normal distribution to U-quadratic distribution.

    See: https://en.wikipedia.org/wiki/U-quadratic_distribution

    Parameters
    ----------
    field : :class:`numpy.ndarray`
        Normal distributed values.
    mean : :class:`float` or :any:`None`, optional
        Mean of the given field. If None is given, the mean will be calculated.
        Default: :any:`None`
    var : :class:`float` or :any:`None`, optional
        Variance of the given field.
        If None is given, the variance will be calculated.
        Default: :any:`None`
    a : :class:`float`, optional
        Parameter a of the U-quadratic distribution (lower bound).
        Default: keep mean and variance
    b : :class:`float`, optional
        Parameter b of the U-quadratic distribution (upper bound).
        Default: keep mean and variance

    Returns
    -------
    :class:`numpy.ndarray`
        Transformed field.
    """
    field = np.asarray(field)
    mean = np.mean(field) if mean is None else float(mean)
    var = np.var(field) if var is None else float(var)
    a = mean - np.sqrt(5.0 / 3.0 * var) if a is None else float(a)
    b = mean + np.sqrt(5.0 / 3.0 * var) if b is None else float(b)
    return _uniform_to_uquad(array_to_uniform(field, mean, var), a, b)


def _uniform_to_arcsin(field, a=0, b=1):
    """
    PPF of your desired distribution.

    The PPF is the inverse of the CDF and is used to sample a distribution
    from uniform distributed values on [0, 1]

    in this case: the arcsin distribution
    See: https://en.wikipedia.org/wiki/Arcsine_distribution
    """
    field = np.asarray(field)
    return (b - a) * np.sin(np.pi * 0.5 * field) ** 2 + a


def _uniform_to_uquad(field, a=0, b=1):
    """
    PPF of your desired distribution.

    The PPF is the inverse of the CDF and is used to sample a distribution
    from uniform distributed values on [0, 1]

    in this case: the U-quadratic distribution
    See: https://en.wikipedia.org/wiki/U-quadratic_distribution
    """
    field = np.asarray(field)
    al = 12 / (b - a) ** 3
    be = (a + b) / 2
    ga = (a - b) ** 3 / 8
    y_raw = 3 * field / al + ga
    result = np.zeros_like(y_raw)
    result[y_raw > 0] = y_raw[y_raw > 0] ** (1 / 3)
    result[y_raw < 0] = -((-y_raw[y_raw < 0]) ** (1 / 3))
    return result + be

1	# -- coding: utf-8 --
2	"""	12✔
3	GStools subpackage providing array transformations.
4
5	.. currentmodule:: gstools.transform.array
6
7	The following functions are provided
8
9	Transformations
10	^^^^^^^^^^^^^^^
11
12	.. autosummary::
13	array_discrete
14	array_boxcox
15	array_zinnharvey
16	array_force_moments
17	array_to_lognormal
18	array_to_uniform
19	array_to_arcsin
20	array_to_uquad
21	"""
22	# pylint: disable=C0103, C0123, R0911
23	from warnings import warn	12✔
24	import numpy as np	12✔
25	from scipy.special import erf, erfinv	12✔
26
27	__all__ = [	12✔
28	"array_discrete",
29	"array_boxcox",
30	"array_zinnharvey",
31	"array_force_moments",
32	"array_to_lognormal",
33	"array_to_uniform",
34	"array_to_arcsin",
35	"array_to_uquad",
36	]
37
38
39	def array_discrete(	12✔
40	field, values, thresholds="arithmetic", mean=None, var=None
41	):
42	"""
43	Discrete transformation.
44
45	After this transformation, the field has only `len(values)` discrete
46	values.
47
48	Parameters
49	----------
50	field : :class:`numpy.ndarray`
51	Normal distributed values.
52	values : :any:`numpy.ndarray`
53	The discrete values the field will take
54	thresholds : :class:`str` or :any:`numpy.ndarray`, optional
55	the thresholds, where the value classes are separated
56	possible values are:
57	* "arithmetic": the mean of the 2 neighbouring values
58	* "equal": devide the field into equal parts
59	* an array of explicitly given thresholds
60	Default: "arithmetic"
61	mean : :class:`float`or :any:`None`
62	Mean of the field for "equal" thresholds. Default: np.mean(field)
63	var : :class:`float`or :any:`None`
64	Variance of the field for "equal" thresholds. Default: np.var(field)
65
66	Returns
67	-------
68	:class:`numpy.ndarray`
69	Transformed field.
70	"""
71	field = np.asarray(field)	12✔
72	if thresholds == "arithmetic":	12✔
73	# just in case, sort the values
74	values = np.sort(values)	12✔
75	thresholds = (values[1:] + values[:-1]) / 2	12✔
76	elif thresholds == "equal":	12✔
77	mean = np.mean(field) if mean is None else float(mean)	12✔
78	var = np.var(field) if var is None else float(var)	12✔
79	values = np.asarray(values)	12✔
80	n = len(values)	12✔
81	p = np.arange(1, n) / n # n-1 equal subdivisions of [0, 1]	12✔
82	rescale = np.sqrt(var * 2)	12✔
83	# use quantile of the normal distribution to get equal ratios
84	thresholds = mean + rescale * erfinv(2 * p - 1)	12✔
85	else:
86	if len(values) != len(thresholds) + 1:	12✔
87	raise ValueError(	×
88	"discrete transformation: len(values) != len(thresholds) + 1"
89	)
90	values = np.asarray(values)	12✔
91	thresholds = np.asarray(thresholds)	12✔
92	# check thresholds
93	if not np.all(thresholds[:-1] < thresholds[1:]):	12✔
94	raise ValueError(	×
95	"discrete transformation: thresholds need to be ascending"
96	)
97	# use a separate result so the intermediate results are not affected
98	result = np.empty_like(field)	12✔
99	# handle edge cases
100	result[field <= thresholds[0]] = values[0]	12✔
101	result[field > thresholds[-1]] = values[-1]	12✔
102	for i, value in enumerate(values[1:-1]):	12✔
103	result[	12✔
104	np.logical_and(thresholds[i] < field, field <= thresholds[i + 1])
105	] = value
106	return result	12✔
107
108
109	def array_boxcox(field, lmbda=1, shift=0):	12✔
110	"""
111	(Inverse) Box-Cox transformation to denormalize data.
112
113	After this transformation, the again Box-Cox transformed field is normal
114	distributed.
115
116	See: https://en.wikipedia.org/wiki/Power_transform#Box%E2%80%93Cox_transformation
117
118	Parameters
119	----------
120	field : :class:`numpy.ndarray`
121	Normal distributed values.
122	lmbda : :class:`float`, optional
123	The lambda parameter of the Box-Cox transformation.
124	For ``lmbda=0`` one obtains the log-normal transformation.
125	Default: ``1``
126	shift : :class:`float`, optional
127	The shift parameter from the two-parametric Box-Cox transformation.
128	The field will be shifted by that value before transformation.
129	Default: ``0``
130	"""
131	field = np.asarray(field)	12✔
132	result = field + shift	12✔
133	if np.isclose(lmbda, 0):	12✔
134	array_to_lognormal(result)	×
135	if np.min(result) < -1 / lmbda:	12✔
136	warn("Box-Cox: Some values will be cut off!")	×
137	return (np.maximum(lmbda * result + 1, 0)) ** (1 / lmbda)	12✔
138
139
140	def array_zinnharvey(field, conn="high", mean=None, var=None):	12✔
141	"""
142	Zinn and Harvey transformation to connect low or high values.
143
144	Parameters
145	----------
146	field : :class:`numpy.ndarray`
147	Normal distributed values.
148	conn : :class:`str`, optional
149	Desired connectivity. Either "low" or "high".
150	Default: "high"
151	mean : :class:`float` or :any:`None`, optional
152	Mean of the given field. If None is given, the mean will be calculated.
153	Default: :any:`None`
154	var : :class:`float` or :any:`None`, optional
155	Variance of the given field.
156	If None is given, the variance will be calculated.
157	Default: :any:`None`
158
159	Returns
160	-------
161	:class:`numpy.ndarray`
162	Transformed field.
163	"""
164	field = np.asarray(field)	12✔
165	mean = np.mean(field) if mean is None else float(mean)	12✔
166	var = np.var(field) if var is None else float(var)	12✔
167	result = np.abs((field - mean) / np.sqrt(var))	12✔
168	result = np.sqrt(2) * erfinv(2 * erf(result / np.sqrt(2)) - 1)	12✔
169	if conn == "high":	12✔
170	result = -result	12✔
171	return result * np.sqrt(var) + mean	12✔
172
173
174	def array_force_moments(field, mean=0, var=1):	12✔
175	"""
176	Force moments of a normal distributed field.
177
178	Parameters
179	----------
180	field : :class:`numpy.ndarray`
181	Normal distributed values.
182	mean : :class:`float`, optional
183	Desired mean of the field.
184	Default: 0
185	var : :class:`float` or :any:`None`, optional
186	Desired variance of the field.
187	Default: 1
188
189	Returns
190	-------
191	:class:`numpy.ndarray`
192	Transformed field.
193	"""
194	field = np.asarray(field)	12✔
195	var_in = np.var(field)	12✔
196	mean_in = np.mean(field)	12✔
197	rescale = np.sqrt(var / var_in)	12✔
198	return rescale * (field - mean_in) + mean	12✔
199
200
201	def array_to_lognormal(field):	12✔
202	"""
203	Transform normal distribution to log-normal distribution.
204
205	Parameters
206	----------
207	field : :class:`numpy.ndarray`
208	Normal distributed values.
209
210	Returns
211	-------
212	:class:`numpy.ndarray`
213	Transformed field.
214	"""
215	return np.exp(field)	12✔
216
217
218	def array_to_uniform(field, mean=None, var=None):	12✔
219	"""
220	Transform normal distribution to uniform distribution on [0, 1].
221
222	Parameters
223	----------
224	field : :class:`numpy.ndarray`
225	Normal distributed values.
226	mean : :class:`float` or :any:`None`, optional
227	Mean of the given field. If None is given, the mean will be calculated.
228	Default: :any:`None`
229	var : :class:`float` or :any:`None`, optional
230	Variance of the given field.
231	If None is given, the variance will be calculated.
232	Default: :any:`None`
233
234	Returns
235	-------
236	:class:`numpy.ndarray`
237	Transformed field.
238	"""
239	field = np.asarray(field)	12✔
240	mean = np.mean(field) if mean is None else float(mean)	12✔
241	var = np.var(field) if var is None else float(var)	12✔
242	return 0.5 * (1 + erf((field - mean) / np.sqrt(2 * var)))	12✔
243
244
245	def array_to_arcsin(field, mean=None, var=None, a=None, b=None):	12✔
246	"""
247	Transform normal distribution to arcsin distribution.
248
249	See: https://en.wikipedia.org/wiki/Arcsine_distribution
250
251	Parameters
252	----------
253	field : :class:`numpy.ndarray`
254	Normal distributed values.
255	mean : :class:`float` or :any:`None`, optional
256	Mean of the given field. If None is given, the mean will be calculated.
257	Default: :any:`None`
258	var : :class:`float` or :any:`None`, optional
259	Variance of the given field.
260	If None is given, the mean will be calculated.
261	Default: :any:`None`
262	a : :class:`float`, optional
263	Parameter a of the arcsin distribution (lower bound).
264	Default: keep mean and variance
265	b : :class:`float`, optional
266	Parameter b of the arcsin distribution (upper bound).
267	Default: keep mean and variance
268
269	Returns
270	-------
271	:class:`numpy.ndarray`
272	Transformed field.
273	"""
274	field = np.asarray(field)	12✔
275	mean = np.mean(field) if mean is None else float(mean)	12✔
276	var = np.var(field) if var is None else float(var)	12✔
277	a = mean - np.sqrt(2.0 * var) if a is None else float(a)	12✔
278	b = mean + np.sqrt(2.0 * var) if b is None else float(b)	12✔
279	return _uniform_to_arcsin(array_to_uniform(field, mean, var), a, b)	12✔
280
281
282	def array_to_uquad(field, mean=None, var=None, a=None, b=None):	12✔
283	"""
284	Transform normal distribution to U-quadratic distribution.
285
286	See: https://en.wikipedia.org/wiki/U-quadratic_distribution
287
288	Parameters
289	----------
290	field : :class:`numpy.ndarray`
291	Normal distributed values.
292	mean : :class:`float` or :any:`None`, optional
293	Mean of the given field. If None is given, the mean will be calculated.
294	Default: :any:`None`
295	var : :class:`float` or :any:`None`, optional
296	Variance of the given field.
297	If None is given, the variance will be calculated.
298	Default: :any:`None`
299	a : :class:`float`, optional
300	Parameter a of the U-quadratic distribution (lower bound).
301	Default: keep mean and variance
302	b : :class:`float`, optional
303	Parameter b of the U-quadratic distribution (upper bound).
304	Default: keep mean and variance
305
306	Returns
307	-------
308	:class:`numpy.ndarray`
309	Transformed field.
310	"""
311	field = np.asarray(field)	12✔
312	mean = np.mean(field) if mean is None else float(mean)	12✔
313	var = np.var(field) if var is None else float(var)	12✔
314	a = mean - np.sqrt(5.0 / 3.0 * var) if a is None else float(a)	12✔
315	b = mean + np.sqrt(5.0 / 3.0 * var) if b is None else float(b)	12✔
316	return _uniform_to_uquad(array_to_uniform(field, mean, var), a, b)	12✔
317
318
319	def _uniform_to_arcsin(field, a=0, b=1):	12✔
320	"""
321	PPF of your desired distribution.
322
323	The PPF is the inverse of the CDF and is used to sample a distribution
324	from uniform distributed values on [0, 1]
325
326	in this case: the arcsin distribution
327	See: https://en.wikipedia.org/wiki/Arcsine_distribution
328	"""
329	field = np.asarray(field)	12✔
330	return (b - a) * np.sin(np.pi * 0.5 * field) ** 2 + a	12✔
331
332
333	def _uniform_to_uquad(field, a=0, b=1):	12✔
334	"""
335	PPF of your desired distribution.
336
337	The PPF is the inverse of the CDF and is used to sample a distribution
338	from uniform distributed values on [0, 1]
339
340	in this case: the U-quadratic distribution
341	See: https://en.wikipedia.org/wiki/U-quadratic_distribution
342	"""
343	field = np.asarray(field)	12✔
344	al = 12 / (b - a) ** 3	12✔
345	be = (a + b) / 2	12✔
346	ga = (a - b) ** 3 / 8	12✔
347	y_raw = 3 * field / al + ga	12✔
348	result = np.zeros_like(y_raw)	12✔
349	result[y_raw > 0] = y_raw[y_raw > 0] ** (1 / 3)	12✔
350	result[y_raw < 0] = -((-y_raw[y_raw < 0]) ** (1 / 3))	12✔
351	return result + be	12✔

GeoStat-Framework / GSTools / 1094843954

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous