Utilities module

The utils module offers the following utility functions:

Function	Description
get_version()	Returns version of araucaria.
check_objattrs()	Check type and attributes of an object.
check_xrange()	Range values for an array.
index_xrange()	Index of values in given range for an array.
index_dups()	Index of duplicate values in an array.
index_nans()	Index of NaN values in an array.
index_nearest()	Index of nearest value in an array.
interp_yvals()	Returns interpolated values for 1-D function.
read_fdicts()	Reads file with multiple dictionaries.

araucaria.utils.get_version(dependencies=False)

Returns installed version of araucaria.

Parameters

dependencies (bool) – Condition to additionally get version of dependencies. The default is False.

Return type

str

Returns

Printable string with version of araucaria.

Examples

>>> from araucaria.utils import get_version
>>> print(get_version()) 
Araucaria version   : ...

araucaria.utils.check_objattrs(obj, objtype, attrlist=None, exceptions=False)

Check type and attributes of an object.

Parameters

• obj (object) – Object to check.

• objtype (TypeVar) – Type for the object.

• attrlist (Optional[list]) – List with names of attributes to check.

• exceptions (bool) – Condition to raise exceptions if attributes are not in the object. The default is False.

Return type

List[bool]

Returns

List with booleans for each attribute of the object.

Raises

TypeError – If obj is not an instance of objtype.

Examples

>>> from araucaria import Group
>>> from araucaria.utils import check_objattrs
>>> group   = Group(**{'energy': [1,2,3,4], 'mu': [2,2,3,1]})
>>> # checking class type
>>> check_objattrs(group, Group)
True

>>> # checking class type and attributes
>>> alist   = ['energy', 'mu', 'mu_ref']
>>> check_objattrs(group, Group, attrlist = alist)
[True, True, False]

araucaria.utils.check_xrange(x_range, x, refval=None)

Returns range values inside an array.

Parameters

• x_range (list) – List with min and max values. Supports inf values.

• x (ndarray) – Array with values.

• refval (Optional[float]) – If given, x_range is assumed to contain values relative to refval. If None, x_range is assumed to contain absolute values.

Return type

list

Returns

New range values inside the array.

Examples

>>> from numpy import inf, linspace
>>> from araucaria.utils import check_xrange
>>> k_range = [-inf,inf]
>>> k       = linspace(0,15)
>>> krange = check_xrange(k_range, k)
>>> print(krange)
[0.0, 15.0]

>>> # using a reference value
>>> e_range = [-inf, -50]
>>> energy  = linspace(8900, 9100)
>>> e0      = 8979
>>> erange  = check_xrange(e_range, energy, refval=e0)
>>> print(erange)
[-79.0, -50]

araucaria.utils.index_xrange(x_range, x, refval=None)

Returns indexes of range values inside an array.

Parameters

• x_range (list) – List with real min and max values.

• x (ndarray) – Array with values.

• refval (Optional[float]) – If given, x_range is assumed to contain values relative to refval. If None, x_range is assumed to contain absolute values.

Return type

ndarray

Returns

Array with indexes of range values inside the array.

Examples

>>> from numpy import arange, inf
>>> from araucaria.utils import index_xrange
>>> k_range = [4, 8]
>>> k       = arange(0,16)
>>> index   = index_xrange(k_range, k)
>>> k[index]
array([4, 5, 6, 7, 8])

>>> # using a reference value
>>> e_range = [-inf, -50]
>>> energy  = arange(8900, 9100)
>>> e0      = 8979
>>> index   = index_xrange(e_range, energy, refval=e0)
>>> energy[index][0], energy[index][-1]
(8900, 8929)

araucaria.utils.index_dups(data, tol=0.0001)

Index of duplicate values.

Parameters

• data (ndarray) – Array to search for duplicates.

• tol (float) – Tolerance value (the detault is 1e-4).

Return type

ndarray

Returns

Index array with the location of duplicates.

Notes

A value in data is considered a duplicate if the difference with respect to the previous value is strictly lower than the given tol value.

If the dimension of data is larger than 1 the array will be flattened by indexing the elements in row-major (i.e. C-style).

Examples

index_dups() is useful to remove duplicates and ensure monotonicity of a 1-D array.

>>> from numpy import array, delete
>>> from araucaria.utils import index_dups
>>> energy = array([9000, 9000.1, 9005, 9005.1, 9008])
>>> index  = index_dups(energy, tol=0.5)
>>> print(index)
[1 3]

>>> # duplicactes
>>> print(energy[index])
[9000.1 9005.1]

>>> # removing duplicates
>>> from numpy import delete
>>> new_energy = delete(energy,index,0)
>>> print(new_energy)
[9000. 9005. 9008.]

araucaria.utils.index_nans(data, axis=0)

Index of NaN values in an array.

Parameters

• data (ndarray) – Array to search for NaN values.

• axis (int) – Axis along which NaN values will be searched. The detault is 0.

Returns

Index array with NaN values in the given axis.

Raises

IndexError – If axis is greater than the dimension of data.

Examples

index_nans() is useful to remove NaN values from arrays.

>>> from numpy import arange, nan, delete
>>> from araucaria.utils import index_nans
>>> data      = arange(20, dtype=float).reshape(5,4)
>>> data[1,2] = nan; data[3,1] = nan
>>> print(data)
[[ 0.  1.  2.  3.]
 [ 4.  5. nan  7.]
 [ 8.  9. 10. 11.]
 [12. nan 14. 15.]
 [16. 17. 18. 19.]]

>>> # removing NaN values from rows
>>> rindex = index_nans(data, 0)
>>> print(rindex)
[[1]
 [3]]
>>> print(delete(data, rindex, 0))
[[ 0.  1.  2.  3.]
 [ 8.  9. 10. 11.]
 [16. 17. 18. 19.]]

>>> # removing NaN values from columns
>>> cindex = index_nans(data, 1)
>>> print(cindex)
[[1]
 [2]]
>>> print(delete(data, cindex, 1))
[[ 0.  3.]
 [ 4.  7.]
 [ 8. 11.]
 [12. 15.]
 [16. 19.]]

araucaria.utils.index_nearest(data, val, kind='nearest')

Index of nearest value in an array.

Parameters

• data (ndarray) – Array to search for nearest value.

• val (float) – Search value. It supports inf.

• kind (str) – Either ‘lower’, ‘nearest’ or ‘higher’. The default is ‘nearest’. See Notes for details.

Return type

float

Returns

Index of nearest value in the array.

Raises

ValueError – If kind is not recognized.

Notes

The kind parameter controls the returned index:

• If kind='lower' the returned index will be of a value strictly lower than val, or 0 if val if lower than the minimum value of data.

• If kind='nearest' the returned index will be of the nearest value with respect to val.

• If kind='higher' the returned index will be of a value strictly higher than val, or -1 if val is higher than the maximum value of data.

Examples

>>> from numpy import linspace
>>> from araucaria.utils import index_nearest
>>> energy = linspace(8900, 9000, 6)
>>> val    = 8965
>>> # find nearest value
>>> index  = index_nearest(energy, val)
>>> print(index, energy[index], val)
3 8960.0 8965

>>> # find strictly lower nearest value
>>> index  = index_nearest(energy, val, kind='lower')
>>> print(index, energy[index], val)
3 8960.0 8965

>>> # find strictly higher nearest value
>>> index  = index_nearest(energy, val, kind='higher')
>>> print(index, energy[index], val)
4 8980.0 8965

araucaria.utils.interp_yvals(x, y, xnew, kind='cubic')

Returns interpolated values for a 1-D function.

Parameters

• x (ndarray) – Array with original domain.

• y (ndarray) – Array with original values of function f(x)=y.

• xnew (ndarray) – Array with new domain.

• kind (str) – Type of interpolation. See interp1d class for valid types. Default is ‘cubic’.

Return type

ndarray

Returns

Array with interpolated values.

Example

>>> from numpy import linspace
>>> from araucaria.utils import interp_yvals
>>> x  = linspace(0,10)
>>> y  = x**2
>>> xp = x[0:10]
>>> yp = interp_yvals(x,y,xp)
>>> print(len(yp))
10

araucaria.utils.read_fdicts(fpath)

Reads file with multiple dictionaries

Parameters

fpath (Path) – File path.

Return type

List[dict]

Returns

List with dictionaries.

Example

>>> from os import remove
>>> from araucaria.utils import read_fdicts
>>> fpath ='file.txt'
>>> data  = "{'ener': [1,2,3], 'mu': [1,2,3]}"
>>> # create file with dictionary data
>>> with open(fpath, 'w') as f:
...     fw = f.write(data)
>>> # reading file with dictionary
>>> dicts = read_fdicts(fpath)
>>> remove(fpath)
>>> for d in dicts:
...     print(type(d), d)
<class 'dict'> {'ener': [1, 2, 3], 'mu': [1, 2, 3]}