Struct NDAxis
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
NumPy's axis argument as one C# type: a single axis (axis=1) or a tuple of axes
(axis=(0, 2), axis=(1,), axis=()). A function whose NumPy default is axis=None takes
NDAxis? axis = null, so null is NumPy's None, and the four spellings below convert implicitly:
np.all(a, 1); // axis=1
np.all(a, (0, 2)); // axis=(0, 2) - a C# tuple of two or three ints
np.all(a, new[] { 0, 2 }); // axis=(0, 2) - an int[]: NumPy's tuple of any length, () included
np.all(a, null); // axis=None - the default
np.all(a, new NDAxis(0, 2)); // axis=(0, 2) - the constructors build the same values explicitly
The value only HOLDS the axes, exactly as given: negative axes stay negative and nothing is range-checked until the function that receives it normalizes them against its operand (Normalize(int, string, bool)), so the error texts are the ones NumPy's function raises.
public readonly struct NDAxis : IEquatable<NDAxis>
- Implements
- Inherited Members
Remarks
A single axis and a one-element tuple are different values, as in Python (1 != (1,)): most functions
answer both alike (NumPy's normalize_axis_tuple turns an int into a 1-tuple), but a few read the
difference - an integer axis of a 0-d array may be 0 or -1 in a reduction (np.all(np.array(5), 0)) where the
tuple (0,) is an AxisError, and np.squeeze checks a tuple's repeats as it reads it. Use
IsTuple to tell them apart.
Footguns. default(NDAxis) and new NDAxis() are the EMPTY tuple () (no axis at all, like
new NDAxis(new int[0])), not axis 0 - a reduction over () reduces nothing. A null
int[] converts to a null NDAxis? (None), but to a non-nullable NDAxis it throws
ArgumentNullException: the null literal converts to NDAxis through the int[]
conversion, so flag ? null : someAxis is typed NDAxis and throws when flag is true - write
flag ? (NDAxis?)null : someAxis. A List<int> has no conversion: pass list.ToArray().
The array a tuple was built from is copied, so changing that array afterwards never changes the value.
Constructors
NDAxis(int)
A single axis: NumPy's axis=axis. The same value as the implicit conversion from int.
public NDAxis(int axis)
Parameters
axisintThe axis as given; a negative axis counts from the end and is resolved by the function that receives the value.
NDAxis(params int[])
A tuple of axes: NumPy's axis=(…), the order kept (new NDAxis(2, 0) is (2, 0)). With no
argument it is the empty tuple (); with exactly one int argument C# calls
NDAxis(int) instead (a single axis) - pass new[] { 1 } for the one-element tuple
(1,).
public NDAxis(params int[] axes)
Parameters
axesint[]The axes as given (negative ones count from the end; repeats are reported by the function that receives the value). The array is copied.
Exceptions
- ArgumentNullException
axesis null (a null array is None only through the conversion toNDAxis?).
NDAxis((int, int, int))
A tuple of three axes from a C# tuple: NumPy's axis=(a, b, c).
public NDAxis((int, int, int) axes)
Parameters
NDAxis((int, int))
A tuple of two axes from a C# tuple: NumPy's axis=(a, b).
public NDAxis((int, int) axes)
Parameters
Properties
Count
The number of axes: 1 for a single axis, the tuple's length otherwise (0 for ()).
public int Count { get; }
Property Value
IsTuple
True for a tuple of axes ((0, 2), (1,), (), and default(NDAxis)), false for a single
axis. The functions whose NumPy answer differs between 1 and (1,) read it (see the type's
remarks).
public bool IsTuple { get; }
Property Value
this[int]
The axis at index, as given (not normalized).
public int this[int index] { get; }
Parameters
indexint0 for a single axis; a position in the tuple otherwise.
Property Value
- int
The axis.
Exceptions
- IndexOutOfRangeException
indexis not in[0, Count).
Methods
Equals(NDAxis)
Whether two values hold the same axes in the same form: a single axis never equals a tuple, as
1 != (1,) in Python.
public bool Equals(NDAxis other)
Parameters
otherNDAxisThe other value.
Returns
- bool
True when both are single axes with the same value, or tuples with the same axes in the same order.
Equals(object)
Whether two values hold the same axes in the same form: a single axis never equals a tuple, as
1 != (1,) in Python.
public override bool Equals(object obj)
Parameters
objobjectThe other object.
Returns
- bool
True when both are single axes with the same value, or tuples with the same axes in the same order.
GetHashCode()
A hash consistent with Equals(NDAxis).
public override int GetHashCode()
Returns
- int
The hash of the form and the axes.
Normalize(int, string, bool)
NumPy's numpy.lib.array_utils.normalize_axis_tuple(axis, ndim, argname, allow_duplicate): every axis
wrapped into [0, ndim), in order, then the repeat check. A single axis is the one-element tuple, as NumPy
turns an int into one.
public int[] Normalize(int ndim, string argname = null, bool allowDuplicate = false)
Parameters
ndimintThe rank the axes address.
argnamestringThe argument name NumPy prints before the AxisError text and inside the repeat text (
"repeated axis in), or null for the plain texts.sourceargument"allowDuplicateboolWhen false (NumPy's default) a repeated axis raises.
Returns
- int[]
A new array of the normalized axes, in the given order.
Remarks
Not every NumPy function normalizes this way: a ufunc reduction (np.all, np.ptp, the sum
behind np.count_nonzero) reports a repeat as duplicate value in 'axis' and lets a 0-d operand
take the INTEGER axis 0 / -1, and np.squeeze checks each axis' range and repeat together, in order.
Those functions read the axes themselves.
Exceptions
- AxisError
An axis is outside
[-ndim, ndim)(the first one in order, reported as given), checked for every axis before any repeat.- ValueError
Two axes are the same after normalization and
allowDuplicateis false (repeated axis).
ToArray()
The axes as a new array, as given (not normalized): one element for a single axis, the tuple's elements otherwise. The array is the caller's to change.
public int[] ToArray()
Returns
ToString()
The value as Python prints the argument: 1, (0, 2), (1,) or ().
public override string ToString()
Returns
- string
The Python repr of the axis or the tuple.
Operators
operator ==(NDAxis, NDAxis)
Whether two values are equal (Equals(NDAxis)).
public static bool operator ==(NDAxis left, NDAxis right)
Parameters
Returns
- bool
True when they are equal.
implicit operator NDAxis(int)
A single axis: NumPy's axis=axis (the same value as NDAxis(int)).
public static implicit operator NDAxis(int axis)
Parameters
axisintThe axis as given.
Returns
- NDAxis
The single-axis value.
Remarks
C# lifts this conversion, so an int? converts to NDAxis? as well: a null int? is
None.
implicit operator NDAxis(int[])
A tuple of axes from an int array, for a non-nullable NDAxis parameter (the array is
copied).
public static implicit operator NDAxis(int[] axes)
Parameters
axesint[]The axes as given; an empty array is the empty tuple
().
Returns
- NDAxis
The tuple.
Exceptions
- ArgumentNullException
axesis null: a non-nullableNDAxishas no None. Convert toNDAxis?instead, where a null array is None.
implicit operator NDAxis?(int[])
A tuple of axes from an int array, for an NDAxis? parameter: a null array is None (the
meaning a null int[] axis had in the overloads this type replaced), any other array a tuple (copied).
public static implicit operator NDAxis?(int[] axes)
Parameters
axesint[]The axes, or null for None.
Returns
- NDAxis?
The tuple, or null.
implicit operator NDAxis((int, int, int))
A tuple of three axes from a C# tuple: (0, 1, 2) is NumPy's axis=(0, 1, 2).
public static implicit operator NDAxis((int, int, int) axes)
Parameters
Returns
- NDAxis
The tuple.
implicit operator NDAxis((int, int))
A tuple of two axes from a C# tuple: (0, 2) is NumPy's axis=(0, 2).
public static implicit operator NDAxis((int, int) axes)
Parameters
Returns
- NDAxis
The tuple.
operator !=(NDAxis, NDAxis)
Whether two values differ (Equals(NDAxis)).
public static bool operator !=(NDAxis left, NDAxis right)
Parameters
Returns
- bool
True when they differ.