1052 lines
29 KiB
ReStructuredText
1052 lines
29 KiB
ReStructuredText
None
|
||
Numpy functions
|
||
===============
|
||
|
||
This section of the manual discusses those functions that were adapted
|
||
from ``numpy``.
|
||
|
||
1. `numpy.argmax <#argmax>`__
|
||
2. `numpy.argmin <#argmin>`__
|
||
3. `numpy.argsort <#argsort>`__
|
||
4. `numpy.clip <#clip>`__
|
||
5. `numpy.convolve <#convolve>`__
|
||
6. `numpy.diff <#diff>`__
|
||
7. `numpy.equal <#equal>`__
|
||
8. `numpy.flip <#flip>`__
|
||
9. `numpy.interp <#interp>`__
|
||
10. `numpy.max <#max>`__
|
||
11. `numpy.maximum <#maximum>`__
|
||
12. `numpy.mean <#mean>`__
|
||
13. `numpy.median <#median>`__
|
||
14. `numpy.min <#min>`__
|
||
15. `numpy.minimum <#minimum>`__
|
||
16. `numpy.not_equal <#not_equal>`__
|
||
17. `numpy.polyfit <#polyfit>`__
|
||
18. `numpy.polyval <#polyval>`__
|
||
19. `numpy.roll <#roll>`__
|
||
20. `numpy.sort <#sort>`__
|
||
21. `numpy.std <#std>`__
|
||
22. `numpy.sum <#sum>`__
|
||
23. `numpy.trapz <#trapz>`__
|
||
|
||
argmax
|
||
------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.argmax.html
|
||
|
||
See `numpy.max <#max>`__.
|
||
|
||
argmin
|
||
------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.argmin.html
|
||
|
||
See `numpy.max <#max>`__.
|
||
|
||
argsort
|
||
-------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.argsort.html
|
||
|
||
Similarly to `sort <#sort>`__, ``argsort`` takes a positional, and a
|
||
keyword argument, and returns an unsigned short index array of type
|
||
``ndarray`` with the same dimensions as the input, or, if ``axis=None``,
|
||
as a row vector with length equal to the number of elements in the input
|
||
(i.e., the flattened array). The indices in the output sort the input in
|
||
ascending order. The routine in ``argsort`` is the same as in ``sort``,
|
||
therefore, the comments on computational expenses (time and RAM) also
|
||
apply. In particular, since no copy of the original data is required,
|
||
virtually no RAM beyond the output array is used.
|
||
|
||
Since the underlying container of the output array is of type
|
||
``uint16_t``, neither of the output dimensions should be larger than
|
||
65535. If that happens to be the case, the function will bail out with a
|
||
``ValueError``.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([[1, 12, 3, 0], [5, 3, 4, 1], [9, 11, 1, 8], [7, 10, 0, 1]], dtype=np.float)
|
||
print('\na:\n', a)
|
||
b = np.argsort(a, axis=0)
|
||
print('\na sorted along vertical axis:\n', b)
|
||
|
||
c = np.argsort(a, axis=1)
|
||
print('\na sorted along horizontal axis:\n', c)
|
||
|
||
c = np.argsort(a, axis=None)
|
||
print('\nflattened a sorted:\n', c)
|
||
|
||
.. parsed-literal::
|
||
|
||
|
||
a:
|
||
array([[1.0, 12.0, 3.0, 0.0],
|
||
[5.0, 3.0, 4.0, 1.0],
|
||
[9.0, 11.0, 1.0, 8.0],
|
||
[7.0, 10.0, 0.0, 1.0]], dtype=float64)
|
||
|
||
a sorted along vertical axis:
|
||
array([[0, 1, 3, 0],
|
||
[1, 3, 2, 1],
|
||
[3, 2, 0, 3],
|
||
[2, 0, 1, 2]], dtype=uint16)
|
||
|
||
a sorted along horizontal axis:
|
||
array([[3, 0, 2, 1],
|
||
[3, 1, 2, 0],
|
||
[2, 3, 0, 1],
|
||
[2, 3, 0, 1]], dtype=uint16)
|
||
|
||
Traceback (most recent call last):
|
||
File "/dev/shm/micropython.py", line 12, in <module>
|
||
NotImplementedError: argsort is not implemented for flattened arrays
|
||
|
||
|
||
|
||
Since during the sorting, only the indices are shuffled, ``argsort``
|
||
does not modify the input array, as one can verify this by the following
|
||
example:
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([0, 5, 1, 3, 2, 4], dtype=np.uint8)
|
||
print('\na:\n', a)
|
||
b = np.argsort(a, axis=0)
|
||
print('\nsorting indices:\n', b)
|
||
print('\nthe original array:\n', a)
|
||
|
||
.. parsed-literal::
|
||
|
||
|
||
a:
|
||
array([0, 5, 1, 3, 2, 4], dtype=uint8)
|
||
|
||
sorting indices:
|
||
array([0, 2, 4, 3, 5, 1], dtype=uint16)
|
||
|
||
the original array:
|
||
array([0, 5, 1, 3, 2, 4], dtype=uint8)
|
||
|
||
|
||
|
||
|
||
clip
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.clip.html
|
||
|
||
Clips an array, i.e., values that are outside of an interval are clipped
|
||
to the interval edges. The function is equivalent to
|
||
``maximum(a_min, minimum(a, a_max))`` broadcasting takes place exactly
|
||
as in `minimum <#minimum>`__. If the arrays are of different ``dtype``,
|
||
the output is upcast as in `Binary operators <#Binary-operators>`__.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array(range(9), dtype=np.uint8)
|
||
print('a:\t\t', a)
|
||
print('clipped:\t', np.clip(a, 3, 7))
|
||
|
||
b = 3 * np.ones(len(a), dtype=np.float)
|
||
print('\na:\t\t', a)
|
||
print('b:\t\t', b)
|
||
print('clipped:\t', np.clip(a, b, 7))
|
||
|
||
.. parsed-literal::
|
||
|
||
a: array([0, 1, 2, 3, 4, 5, 6, 7, 8], dtype=uint8)
|
||
clipped: array([3, 3, 3, 3, 4, 5, 6, 7, 7], dtype=uint8)
|
||
|
||
a: array([0, 1, 2, 3, 4, 5, 6, 7, 8], dtype=uint8)
|
||
b: array([3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0], dtype=float64)
|
||
clipped: array([3.0, 3.0, 3.0, 3.0, 4.0, 5.0, 6.0, 7.0, 7.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
convolve
|
||
--------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.convolve.html
|
||
|
||
Returns the discrete, linear convolution of two one-dimensional arrays.
|
||
|
||
Only the ``full`` mode is supported, and the ``mode`` named parameter is
|
||
not accepted. Note that all other modes can be had by slicing a ``full``
|
||
result.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
x = np.array((1, 2, 3))
|
||
y = np.array((1, 10, 100, 1000))
|
||
|
||
print(np.convolve(x, y))
|
||
|
||
.. parsed-literal::
|
||
|
||
array([1.0, 12.0, 123.0, 1230.0, 2300.0, 3000.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
diff
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.diff.html
|
||
|
||
The ``diff`` function returns the numerical derivative of the forward
|
||
scheme, or more accurately, the differences of an ``ndarray`` along a
|
||
given axis. The order of derivative can be stipulated with the ``n``
|
||
keyword argument, which should be between 0, and 9. Default is 1. If
|
||
higher order derivatives are required, they can be gotten by repeated
|
||
calls to the function. The ``axis`` keyword argument should be -1 (last
|
||
axis, in ``ulab`` equivalent to the second axis, and this also happens
|
||
to be the default value), 0, or 1.
|
||
|
||
Beyond the output array, the function requires only a couple of bytes of
|
||
extra RAM for the differentiation stencil. (The stencil is an ``int8``
|
||
array, one byte longer than ``n``. This also explains, why the highest
|
||
order is 9: the coefficients of a ninth-order stencil all fit in signed
|
||
bytes, while 10 would require ``int16``.) Note that as usual in
|
||
numerical differentiation (and also in ``numpy``), the length of the
|
||
respective axis will be reduced by ``n`` after the operation. If ``n``
|
||
is larger than, or equal to the length of the axis, an empty array will
|
||
be returned.
|
||
|
||
**WARNING**: the ``diff`` function does not implement the ``prepend``
|
||
and ``append`` keywords that can be found in ``numpy``.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array(range(9), dtype=np.uint8)
|
||
a[3] = 10
|
||
print('a:\n', a)
|
||
|
||
print('\nfirst derivative:\n', np.diff(a, n=1))
|
||
print('\nsecond derivative:\n', np.diff(a, n=2))
|
||
|
||
c = np.array([[1, 2, 3, 4], [4, 3, 2, 1], [1, 4, 9, 16], [0, 0, 0, 0]])
|
||
print('\nc:\n', c)
|
||
print('\nfirst derivative, first axis:\n', np.diff(c, axis=0))
|
||
print('\nfirst derivative, second axis:\n', np.diff(c, axis=1))
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([0, 1, 2, 10, 4, 5, 6, 7, 8], dtype=uint8)
|
||
|
||
first derivative:
|
||
array([1, 1, 8, 250, 1, 1, 1, 1], dtype=uint8)
|
||
|
||
second derivative:
|
||
array([0, 249, 14, 249, 0, 0, 0], dtype=uint8)
|
||
|
||
c:
|
||
array([[1.0, 2.0, 3.0, 4.0],
|
||
[4.0, 3.0, 2.0, 1.0],
|
||
[1.0, 4.0, 9.0, 16.0],
|
||
[0.0, 0.0, 0.0, 0.0]], dtype=float64)
|
||
|
||
first derivative, first axis:
|
||
array([[3.0, 1.0, -1.0, -3.0],
|
||
[-3.0, 1.0, 7.0, 15.0],
|
||
[-1.0, -4.0, -9.0, -16.0]], dtype=float64)
|
||
|
||
first derivative, second axis:
|
||
array([[1.0, 1.0, 1.0],
|
||
[-1.0, -1.0, -1.0],
|
||
[3.0, 5.0, 7.0],
|
||
[0.0, 0.0, 0.0]], dtype=float64)
|
||
|
||
|
||
|
||
|
||
equal
|
||
-----
|
||
|
||
``numpy``:
|
||
https://numpy.org/doc/stable/reference/generated/numpy.equal.html
|
||
|
||
``numpy``:
|
||
https://numpy.org/doc/stable/reference/generated/numpy.not_equal.html
|
||
|
||
In ``micropython``, equality of arrays or scalars can be established by
|
||
utilising the ``==``, ``!=``, ``<``, ``>``, ``<=``, or ``=>`` binary
|
||
operators. In ``circuitpython``, ``==`` and ``!=`` will produce
|
||
unexpected results. In order to avoid this discrepancy, and to maintain
|
||
compatibility with ``numpy``, ``ulab`` implements the ``equal`` and
|
||
``not_equal`` operators that return the same results, irrespective of
|
||
the ``python`` implementation.
|
||
|
||
These two functions take two ``ndarray``\ s, or scalars as their
|
||
arguments. No keyword arguments are implemented.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array(range(9))
|
||
b = np.zeros(9)
|
||
|
||
print('a: ', a)
|
||
print('b: ', b)
|
||
print('\na == b: ', np.equal(a, b))
|
||
print('a != b: ', np.not_equal(a, b))
|
||
|
||
# comparison with scalars
|
||
print('a == 2: ', np.equal(a, 2))
|
||
|
||
.. parsed-literal::
|
||
|
||
a: array([0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], dtype=float64)
|
||
b: array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], dtype=float64)
|
||
|
||
a == b: array([True, False, False, False, False, False, False, False, False], dtype=bool)
|
||
a != b: array([False, True, True, True, True, True, True, True, True], dtype=bool)
|
||
a == 2: array([False, False, True, False, False, False, False, False, False], dtype=bool)
|
||
|
||
|
||
|
||
|
||
flip
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.flip.html
|
||
|
||
The ``flip`` function takes one positional, an ``ndarray``, and one
|
||
keyword argument, ``axis = None``, and reverses the order of elements
|
||
along the given axis. If the keyword argument is ``None``, the matrix’
|
||
entries are flipped along all axes. ``flip`` returns a new copy of the
|
||
array.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([1, 2, 3, 4, 5])
|
||
print("a: \t", a)
|
||
print("a flipped:\t", np.flip(a))
|
||
|
||
a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=np.uint8)
|
||
print("\na flipped horizontally\n", np.flip(a, axis=1))
|
||
print("\na flipped vertically\n", np.flip(a, axis=0))
|
||
print("\na flipped horizontally+vertically\n", np.flip(a))
|
||
|
||
.. parsed-literal::
|
||
|
||
a: array([1.0, 2.0, 3.0, 4.0, 5.0], dtype=float64)
|
||
a flipped: array([5.0, 4.0, 3.0, 2.0, 1.0], dtype=float64)
|
||
|
||
a flipped horizontally
|
||
array([[3, 2, 1],
|
||
[6, 5, 4],
|
||
[9, 8, 7]], dtype=uint8)
|
||
|
||
a flipped vertically
|
||
array([[7, 8, 9],
|
||
[4, 5, 6],
|
||
[1, 2, 3]], dtype=uint8)
|
||
|
||
a flipped horizontally+vertically
|
||
array([9, 8, 7, 6, 5, 4, 3, 2, 1], dtype=uint8)
|
||
|
||
|
||
|
||
|
||
interp
|
||
------
|
||
|
||
``numpy``: https://docs.scipy.org/doc/numpy/numpy.interp
|
||
|
||
The ``interp`` function returns the linearly interpolated values of a
|
||
one-dimensional numerical array. It requires three positional
|
||
arguments,\ ``x``, at which the interpolated values are evaluated,
|
||
``xp``, the array of the independent data variable, and ``fp``, the
|
||
array of the dependent values of the data. ``xp`` must be a
|
||
monotonically increasing sequence of numbers.
|
||
|
||
Two keyword arguments, ``left``, and ``right`` can also be supplied;
|
||
these determine the return values, if ``x < xp[0]``, and ``x > xp[-1]``,
|
||
respectively. If these arguments are not supplied, ``left``, and
|
||
``right`` default to ``fp[0]``, and ``fp[-1]``, respectively.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
x = np.array([1, 2, 3, 4, 5]) - 0.2
|
||
xp = np.array([1, 2, 3, 4])
|
||
fp = np.array([1, 2, 3, 5])
|
||
|
||
print(x)
|
||
print(np.interp(x, xp, fp))
|
||
print(np.interp(x, xp, fp, left=0.0))
|
||
print(np.interp(x, xp, fp, right=10.0))
|
||
|
||
.. parsed-literal::
|
||
|
||
array([0.8, 1.8, 2.8, 3.8, 4.8], dtype=float64)
|
||
array([1.0, 1.8, 2.8, 4.6, 5.0], dtype=float64)
|
||
array([0.0, 1.8, 2.8, 4.6, 5.0], dtype=float64)
|
||
array([1.0, 1.8, 2.8, 4.6, 10.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
mean
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
|
||
|
||
If the axis keyword is not specified, it assumes the default value of
|
||
``None``, and returns the result of the computation for the flattened
|
||
array. Otherwise, the calculation is along the given axis.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
|
||
print('a: \n', a)
|
||
print('mean, flat: ', np.mean(a))
|
||
print('mean, horizontal: ', np.mean(a, axis=1))
|
||
print('mean, vertical: ', np.mean(a, axis=0))
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([[1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0],
|
||
[7.0, 8.0, 9.0]], dtype=float64)
|
||
mean, flat: 5.0
|
||
mean, horizontal: array([2.0, 5.0, 8.0], dtype=float64)
|
||
mean, vertical: array([4.0, 5.0, 6.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
max
|
||
---
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.max.html
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.argmax.html
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.min.html
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.argmin.html
|
||
|
||
**WARNING:** Difference to ``numpy``: the ``out`` keyword argument is
|
||
not implemented.
|
||
|
||
These functions follow the same pattern, and work with generic
|
||
iterables, and ``ndarray``\ s. ``min``, and ``max`` return the minimum
|
||
or maximum of a sequence. If the input array is two-dimensional, the
|
||
``axis`` keyword argument can be supplied, in which case the
|
||
minimum/maximum along the given axis will be returned. If ``axis=None``
|
||
(this is also the default value), the minimum/maximum of the flattened
|
||
array will be determined.
|
||
|
||
``argmin/argmax`` return the position (index) of the minimum/maximum in
|
||
the sequence.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([1, 2, 0, 1, 10])
|
||
print('a:', a)
|
||
print('min of a:', np.min(a))
|
||
print('argmin of a:', np.argmin(a))
|
||
|
||
b = np.array([[1, 2, 0], [1, 10, -1]])
|
||
print('\nb:\n', b)
|
||
print('min of b (flattened):', np.min(b))
|
||
print('min of b (axis=0):', np.min(b, axis=0))
|
||
print('min of b (axis=1):', np.min(b, axis=1))
|
||
|
||
.. parsed-literal::
|
||
|
||
a: array([1.0, 2.0, 0.0, 1.0, 10.0], dtype=float64)
|
||
min of a: 0.0
|
||
argmin of a: 2
|
||
|
||
b:
|
||
array([[1.0, 2.0, 0.0],
|
||
[1.0, 10.0, -1.0]], dtype=float64)
|
||
min of b (flattened): -1.0
|
||
min of b (axis=0): array([1.0, 2.0, -1.0], dtype=float64)
|
||
min of b (axis=1): array([0.0, -1.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
median
|
||
------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.median.html
|
||
|
||
The function computes the median along the specified axis, and returns
|
||
the median of the array elements. If the ``axis`` keyword argument is
|
||
``None``, the arrays is flattened first. The ``dtype`` of the results is
|
||
always float.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array(range(12), dtype=np.int8).reshape((3, 4))
|
||
print('a:\n', a)
|
||
print('\nmedian of the flattened array: ', np.median(a))
|
||
print('\nmedian along the vertical axis: ', np.median(a, axis=0))
|
||
print('\nmedian along the horizontal axis: ', np.median(a, axis=1))
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([[0, 1, 2, 3],
|
||
[4, 5, 6, 7],
|
||
[8, 9, 10, 11]], dtype=int8)
|
||
|
||
median of the flattened array: 5.5
|
||
|
||
median along the vertical axis: array([4.0, 5.0, 6.0, 7.0], dtype=float64)
|
||
|
||
median along the horizontal axis: array([1.5, 5.5, 9.5], dtype=float64)
|
||
|
||
|
||
|
||
|
||
min
|
||
---
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.min.html
|
||
|
||
See `numpy.max <#max>`__.
|
||
|
||
.. code::
|
||
|
||
# code to be run in CPython
|
||
|
||
|
||
minimum
|
||
-------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.minimum.html
|
||
|
||
Returns the minimum of two arrays, or two scalars, or an array, and a
|
||
scalar. If the arrays are of different ``dtype``, the output is upcast
|
||
as in `Binary operators <#Binary-operators>`__. If both inputs are
|
||
scalars, a scalar is returned. Only positional arguments are
|
||
implemented.
|
||
|
||
maximum
|
||
-------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.maximum.html
|
||
|
||
Returns the maximum of two arrays, or two scalars, or an array, and a
|
||
scalar. If the arrays are of different ``dtype``, the output is upcast
|
||
as in `Binary operators <#Binary-operators>`__. If both inputs are
|
||
scalars, a scalar is returned. Only positional arguments are
|
||
implemented.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([1, 2, 3, 4, 5], dtype=np.uint8)
|
||
b = np.array([5, 4, 3, 2, 1], dtype=np.float)
|
||
print('minimum of a, and b:')
|
||
print(np.minimum(a, b))
|
||
|
||
print('\nmaximum of a, and b:')
|
||
print(np.maximum(a, b))
|
||
|
||
print('\nmaximum of 1, and 5.5:')
|
||
print(np.maximum(1, 5.5))
|
||
|
||
.. parsed-literal::
|
||
|
||
minimum of a, and b:
|
||
array([1.0, 2.0, 3.0, 2.0, 1.0], dtype=float64)
|
||
|
||
maximum of a, and b:
|
||
array([5.0, 4.0, 3.0, 4.0, 5.0], dtype=float64)
|
||
|
||
maximum of 1, and 5.5:
|
||
5.5
|
||
|
||
|
||
|
||
|
||
not_equal
|
||
---------
|
||
|
||
See `numpy.equal <#equal>`__.
|
||
|
||
polyfit
|
||
-------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.polyfit.html
|
||
|
||
polyfit takes two, or three arguments. The last one is the degree of the
|
||
polynomial that will be fitted, the last but one is an array or iterable
|
||
with the ``y`` (dependent) values, and the first one, an array or
|
||
iterable with the ``x`` (independent) values, can be dropped. If that is
|
||
the case, ``x`` will be generated in the function as ``range(len(y))``.
|
||
|
||
If the lengths of ``x``, and ``y`` are not the same, the function raises
|
||
a ``ValueError``.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
x = np.array([0, 1, 2, 3, 4, 5, 6])
|
||
y = np.array([9, 4, 1, 0, 1, 4, 9])
|
||
print('independent values:\t', x)
|
||
print('dependent values:\t', y)
|
||
print('fitted values:\t\t', np.polyfit(x, y, 2))
|
||
|
||
# the same with missing x
|
||
print('\ndependent values:\t', y)
|
||
print('fitted values:\t\t', np.polyfit(y, 2))
|
||
|
||
.. parsed-literal::
|
||
|
||
independent values: array([0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0], dtype=float64)
|
||
dependent values: array([9.0, 4.0, 1.0, 0.0, 1.0, 4.0, 9.0], dtype=float64)
|
||
fitted values: array([1.0, -6.0, 9.000000000000004], dtype=float64)
|
||
|
||
dependent values: array([9.0, 4.0, 1.0, 0.0, 1.0, 4.0, 9.0], dtype=float64)
|
||
fitted values: array([1.0, -6.0, 9.000000000000004], dtype=float64)
|
||
|
||
|
||
|
||
|
||
Execution time
|
||
~~~~~~~~~~~~~~
|
||
|
||
``polyfit`` is based on the inversion of a matrix (there is more on the
|
||
background in https://en.wikipedia.org/wiki/Polynomial_regression), and
|
||
it requires the intermediate storage of ``2*N*(deg+1)`` floats, where
|
||
``N`` is the number of entries in the input array, and ``deg`` is the
|
||
fit’s degree. The additional computation costs of the matrix inversion
|
||
discussed in `linalg.inv <#inv>`__ also apply. The example from above
|
||
needs around 150 microseconds to return:
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
@timeit
|
||
def time_polyfit(x, y, n):
|
||
return np.polyfit(x, y, n)
|
||
|
||
x = np.array([0, 1, 2, 3, 4, 5, 6])
|
||
y = np.array([9, 4, 1, 0, 1, 4, 9])
|
||
|
||
time_polyfit(x, y, 2)
|
||
|
||
.. parsed-literal::
|
||
|
||
execution time: 153 us
|
||
|
||
|
||
polyval
|
||
-------
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.polyval.html
|
||
|
||
``polyval`` takes two arguments, both arrays or generic ``micropython``
|
||
iterables returning scalars.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
p = [1, 1, 1, 0]
|
||
x = [0, 1, 2, 3, 4]
|
||
print('coefficients: ', p)
|
||
print('independent values: ', x)
|
||
print('\nvalues of p(x): ', np.polyval(p, x))
|
||
|
||
# the same works with one-dimensional ndarrays
|
||
a = np.array(x)
|
||
print('\nndarray (a): ', a)
|
||
print('value of p(a): ', np.polyval(p, a))
|
||
|
||
.. parsed-literal::
|
||
|
||
coefficients: [1, 1, 1, 0]
|
||
independent values: [0, 1, 2, 3, 4]
|
||
|
||
values of p(x): array([0.0, 3.0, 14.0, 39.0, 84.0], dtype=float64)
|
||
|
||
ndarray (a): array([0.0, 1.0, 2.0, 3.0, 4.0], dtype=float64)
|
||
value of p(a): array([0.0, 3.0, 14.0, 39.0, 84.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
roll
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.roll.html
|
||
|
||
The roll function shifts the content of a vector by the positions given
|
||
as the second argument. If the ``axis`` keyword is supplied, the shift
|
||
is applied to the given axis.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([1, 2, 3, 4, 5, 6, 7, 8])
|
||
print("a:\t\t\t", a)
|
||
|
||
a = np.roll(a, 2)
|
||
print("a rolled to the left:\t", a)
|
||
|
||
# this should be the original vector
|
||
a = np.roll(a, -2)
|
||
print("a rolled to the right:\t", a)
|
||
|
||
.. parsed-literal::
|
||
|
||
a: array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], dtype=float64)
|
||
a rolled to the left: array([7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0], dtype=float64)
|
||
a rolled to the right: array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
Rolling works with matrices, too. If the ``axis`` keyword is 0, the
|
||
matrix is rolled along its vertical axis, otherwise, horizontally.
|
||
|
||
Horizontal rolls are faster, because they require fewer steps, and
|
||
larger memory chunks are copied, however, they also require more RAM:
|
||
basically the whole row must be stored internally. Most expensive are
|
||
the ``None`` keyword values, because with ``axis = None``, the array is
|
||
flattened first, hence the row’s length is the size of the whole matrix.
|
||
|
||
Vertical rolls require two internal copies of single columns.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array(range(12)).reshape((3, 4))
|
||
print("a:\n", a)
|
||
a = np.roll(a, 2, axis=0)
|
||
print("\na rolled up:\n", a)
|
||
|
||
a = np.array(range(12)).reshape((3, 4))
|
||
print("a:\n", a)
|
||
a = np.roll(a, -1, axis=1)
|
||
print("\na rolled to the left:\n", a)
|
||
|
||
a = np.array(range(12)).reshape((3, 4))
|
||
print("a:\n", a)
|
||
a = np.roll(a, 1, axis=None)
|
||
print("\na rolled with None:\n", a)
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([[0.0, 1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0, 7.0],
|
||
[8.0, 9.0, 10.0, 11.0]], dtype=float64)
|
||
|
||
a rolled up:
|
||
array([[4.0, 5.0, 6.0, 7.0],
|
||
[8.0, 9.0, 10.0, 11.0],
|
||
[0.0, 1.0, 2.0, 3.0]], dtype=float64)
|
||
a:
|
||
array([[0.0, 1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0, 7.0],
|
||
[8.0, 9.0, 10.0, 11.0]], dtype=float64)
|
||
|
||
a rolled to the left:
|
||
array([[1.0, 2.0, 3.0, 0.0],
|
||
[5.0, 6.0, 7.0, 4.0],
|
||
[9.0, 10.0, 11.0, 8.0]], dtype=float64)
|
||
a:
|
||
array([[0.0, 1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0, 7.0],
|
||
[8.0, 9.0, 10.0, 11.0]], dtype=float64)
|
||
|
||
a rolled with None:
|
||
array([[11.0, 0.0, 1.0, 2.0],
|
||
[3.0, 4.0, 5.0, 6.0],
|
||
[7.0, 8.0, 9.0, 10.0]], dtype=float64)
|
||
|
||
|
||
|
||
|
||
sort
|
||
----
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.sort.html
|
||
|
||
The sort function takes an ndarray, and sorts its elements in ascending
|
||
order along the specified axis using a heap sort algorithm. As opposed
|
||
to the ``.sort()`` method discussed earlier, this function creates a
|
||
copy of its input before sorting, and at the end, returns this copy.
|
||
Sorting takes place in place, without auxiliary storage. The ``axis``
|
||
keyword argument takes on the possible values of -1 (the last axis, in
|
||
``ulab`` equivalent to the second axis, and this also happens to be the
|
||
default value), 0, 1, or ``None``. The first three cases are identical
|
||
to those in `diff <#diff>`__, while the last one flattens the array
|
||
before sorting.
|
||
|
||
If descending order is required, the result can simply be ``flip``\ ped,
|
||
see `flip <#flip>`__.
|
||
|
||
**WARNING:** ``numpy`` defines the ``kind``, and ``order`` keyword
|
||
arguments that are not implemented here. The function in ``ulab`` always
|
||
uses heap sort, and since ``ulab`` does not have the concept of data
|
||
fields, the ``order`` keyword argument would have no meaning.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([[1, 12, 3, 0], [5, 3, 4, 1], [9, 11, 1, 8], [7, 10, 0, 1]], dtype=np.float)
|
||
print('\na:\n', a)
|
||
b = np.sort(a, axis=0)
|
||
print('\na sorted along vertical axis:\n', b)
|
||
|
||
c = np.sort(a, axis=1)
|
||
print('\na sorted along horizontal axis:\n', c)
|
||
|
||
c = np.sort(a, axis=None)
|
||
print('\nflattened a sorted:\n', c)
|
||
|
||
.. parsed-literal::
|
||
|
||
|
||
a:
|
||
array([[1.0, 12.0, 3.0, 0.0],
|
||
[5.0, 3.0, 4.0, 1.0],
|
||
[9.0, 11.0, 1.0, 8.0],
|
||
[7.0, 10.0, 0.0, 1.0]], dtype=float64)
|
||
|
||
a sorted along vertical axis:
|
||
array([[1.0, 3.0, 0.0, 0.0],
|
||
[5.0, 10.0, 1.0, 1.0],
|
||
[7.0, 11.0, 3.0, 1.0],
|
||
[9.0, 12.0, 4.0, 8.0]], dtype=float64)
|
||
|
||
a sorted along horizontal axis:
|
||
array([[0.0, 1.0, 3.0, 12.0],
|
||
[1.0, 3.0, 4.0, 5.0],
|
||
[1.0, 8.0, 9.0, 11.0],
|
||
[0.0, 1.0, 7.0, 10.0]], dtype=float64)
|
||
|
||
flattened a sorted:
|
||
array([0.0, 0.0, 1.0, ..., 10.0, 11.0, 12.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
Heap sort requires :math:`\sim N\log N` operations, and notably, the
|
||
worst case costs only 20% more time than the average. In order to get an
|
||
order-of-magnitude estimate, we will take the sine of 1000 uniformly
|
||
spaced numbers between 0, and two pi, and sort them:
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
import ulab as np
|
||
from ulab import vector
|
||
from ulab import numerical
|
||
|
||
@timeit
|
||
def sort_time(array):
|
||
return numerical.sort(array)
|
||
|
||
b = vector.sin(np.linspace(0, 6.28, num=1000))
|
||
print('b: ', b)
|
||
sort_time(b)
|
||
print('\nb sorted:\n', b)
|
||
std
|
||
---
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.std.html
|
||
|
||
If the axis keyword is not specified, it assumes the default value of
|
||
``None``, and returns the result of the computation for the flattened
|
||
array. Otherwise, the calculation is along the given axis.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
|
||
print('a: \n', a)
|
||
print('sum, flat array: ', np.std(a))
|
||
print('std, vertical: ', np.std(a, axis=0))
|
||
print('std, horizonal: ', np.std(a, axis=1))
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([[1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0],
|
||
[7.0, 8.0, 9.0]], dtype=float64)
|
||
sum, flat array: 2.581988897471611
|
||
std, vertical: array([2.449489742783178, 2.449489742783178, 2.449489742783178], dtype=float64)
|
||
std, horizonal: array([0.8164965809277261, 0.8164965809277261, 0.8164965809277261], dtype=float64)
|
||
|
||
|
||
|
||
|
||
sum
|
||
---
|
||
|
||
``numpy``:
|
||
https://docs.scipy.org/doc/numpy/reference/generated/numpy.sum.html
|
||
|
||
If the axis keyword is not specified, it assumes the default value of
|
||
``None``, and returns the result of the computation for the flattened
|
||
array. Otherwise, the calculation is along the given axis.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
|
||
print('a: \n', a)
|
||
|
||
print('sum, flat array: ', np.sum(a))
|
||
print('sum, horizontal: ', np.sum(a, axis=1))
|
||
print('std, vertical: ', np.sum(a, axis=0))
|
||
|
||
.. parsed-literal::
|
||
|
||
a:
|
||
array([[1.0, 2.0, 3.0],
|
||
[4.0, 5.0, 6.0],
|
||
[7.0, 8.0, 9.0]], dtype=float64)
|
||
sum, flat array: 45.0
|
||
sum, horizontal: array([6.0, 15.0, 24.0], dtype=float64)
|
||
std, vertical: array([12.0, 15.0, 18.0], dtype=float64)
|
||
|
||
|
||
|
||
|
||
trapz
|
||
-----
|
||
|
||
``numpy``:
|
||
https://numpy.org/doc/stable/reference/generated/numpy.trapz.html
|
||
|
||
The function takes one or two one-dimensional ``ndarray``\ s, and
|
||
integrates the dependent values (``y``) using the trapezoidal rule. If
|
||
the independent variable (``x``) is given, that is taken as the sample
|
||
points corresponding to ``y``.
|
||
|
||
.. code::
|
||
|
||
# code to be run in micropython
|
||
|
||
from ulab import numpy as np
|
||
|
||
x = np.linspace(0, 9, num=10)
|
||
y = x*x
|
||
|
||
print('x: ', x)
|
||
print('y: ', y)
|
||
print('============================')
|
||
print('integral of y: ', np.trapz(y))
|
||
print('integral of y at x: ', np.trapz(y, x=x))
|
||
|
||
.. parsed-literal::
|
||
|
||
x: array([0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0], dtype=float64)
|
||
y: array([0.0, 1.0, 4.0, 9.0, 16.0, 25.0, 36.0, 49.0, 64.0, 81.0], dtype=float64)
|
||
============================
|
||
integral of y: 244.5
|
||
integral of y at x: 244.5
|
||
|
||
|
||
|
||
|
||
.. code::
|
||
|
||
# code to be run in CPython
|
||
|