Binning and statistics

Spatial binning

SpatialBinning

SpatialBinning(property, bins, *, axes=2, reduction='mean')

A property of the atoms in bins of equal size along one, two or three box vectors: its mean, sum, sum per volume, minimum or maximum in each.

Parameters:

Name	Type	Description	Default
property	str	A column, a component such as "positions.z", or an expression over the columns.	required
bins	int32 or sequence of int32	The number of bins along each axis, or one number for all.	required
axes	int32, str or sequence of them	The box vectors binned along: 0, 1, 2 or x, y, z. Default z.	2
reduction	str	One of REDUCTIONS: "mean", "sum", "density" (the sum per ų of the bin), "min" or "max". Default mean.	'mean'

compute

compute(system)

The property of a system in bins.

Parameters:

Name	Type	Description	Default
system	System	The atoms. Along periodic vectors the atoms are wrapped into the box; along the others those outside it are left out.	required

Returns:

Type	Description
SpatialBinningResult	The values, the counts and the centers of the bins.

SpatialBinningResult dataclass

SpatialBinningResult(values, counts, centers)

Bases: Result

A property in bins along box vectors.

Attributes:

Name	Type	Description
values	ndarray	The float64 property reduced over the atoms of each bin: (n1[, n2[, n3]]) for one value per atom, with a last axis for its components; NaN for the mean, minimum and maximum of an empty bin.
counts	ndarray	(n1[, n2[, n3]]) int64 the number of atoms in each bin.
centers	tuple of numpy.ndarray	For each axis, (n,) float64 centers of its bins in Å along its box vector, from the origin of the box.

isosurface

isosurface(values, box, level)

The surface where a field on a grid over the box crosses a level.

Parameters:

Name	Type	Description	Default
values	array_like	(na, nb, nc) float64, the field at the centers of the cells of a grid that divides the box into na, nb and nc cells along its vectors a, b and c, such as the values of a SpatialBinning along all three.	required
box	Box	The box the grid divides.	required
level	float64	The value of the field on the surface.	required

Returns:

Type	Description
TriangleMesh	The triangles of the surface in the box, across its periodic boundaries, their normals pointing to lower values; it ends at the outermost centers along directions that are not periodic. Empty where the field does not cross the level.

Raises:

Type	Description
InvalidParameter	For values that are not a three-dimensional grid of finite numbers, or a level that is not finite.

Statistics

Histogram

Histogram(column, bins=50, range=None)

The histogram of the values of a column, as OVITO's histogram modifier.

Parameters:

Name	Type	Description	Default
column	str	A column of numbers, a component such as "positions.z" or an expression over the columns.	required
bins	int32	Number of bins. Default 50.	50
range	tuple of float64	Lowest and highest value of the bins; values outside are not counted. By default from the lowest to the highest finite value.	None

compute

compute(system, *, atoms=None)

The histogram of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
atoms	array_like	A boolean mask or indices of the atoms to count; all by default.	None

Returns:

Type	Description
HistogramResult	The counts in the bins. Without a range, the bins span the lowest to the highest finite value, or one unit above a single value.

HistogramResult dataclass

HistogramResult(center, edges, counts, frequency, density, nonfinite, name)

Bases: Result

The histogram of a column.

Attributes:

Name	Type	Description
center	ndarray	(bins,) float64 centers of the bins.
edges	ndarray	(bins + 1,) float64 edges of the bins.
counts	ndarray	(bins,) int64 number of values in each bin.
frequency	ndarray	(bins,) float64, the counts divided by the number of values counted.
density	ndarray	(bins,) float64, the frequency divided by the width of a bin.
nonfinite	int64	The number of values left out as NaN or infinite.
name	str	The column.

reduce

reduce(system, column, operation='mean', *, atoms=None)

One number from the values of a column, as OVITO's reduce property.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
column	str	A column of numbers, a component such as "positions.z" or an expression over the columns.	required
operation	str	One of OPERATIONS: "mean", "sum", "min", "max", "median", "variance" (of a sample), "std" (of a sample), "nonzero" (the number of values not zero), "argmin" or "argmax" (the index of the atom of the lowest or highest value). Default mean.	'mean'
atoms	array_like	A boolean mask or indices of the atoms to take; all by default.	None

Returns:

Type	Description
(float64, int64 or ndarray)	The number; for an array column, (k,) one per component. NaN values are left out; the mean of no values is NaN, their sum 0. argmin and argmax index the atoms of the system.

Raises:

Type	Description
InvalidParameter	For an unknown operation, a column that is not numbers, or argmin or argmax of no values.