rwskit.numpy
============

.. py:module:: rwskit.numpy

.. autoapi-nested-parse::

   Numpy utilities.



Attributes
----------

.. autoapisummary::

   rwskit.numpy.log
   rwskit.numpy.CompleteCheckType


Functions
---------

.. autoapisummary::

   rwskit.numpy.get_dtype
   rwskit.numpy.is_structured
   rwskit.numpy.is_complete
   rwskit.numpy.finite_cases
   rwskit.numpy.group_by


Module Contents
---------------

.. py:data:: log

.. py:data:: CompleteCheckType

   The valid values for the ``check_type`` parameter of :meth:`is_complete`.

.. py:function:: get_dtype(obj: Optional[Any]) -> Optional[numpy.dtype]

   Return a dtype that can be used to represent an arbitrary object.

   For objects that are already numpy arrays or scalars, the dtype from that
   object is returned. For other python objects, a set of heuristics are used.
   If the object is iterable, the method will try to determine the type of
   object

   If the dtype can't be determined, either because the input object was
   ``None``, or it is a collection that does not contain any non-null
   values, then the method will return ``None``.

   :param obj: An object.
   :type obj: Any

   :returns: A dtype that can be used to represent an arbitrary object, or ``None``
             if the input object is ``None``.
   :rtype: numpy.dtype, optional


.. py:function:: is_structured(array: numpy.ndarray) -> bool

   Checks if a numpy array is a structured array or not.

   :param array: The array to check.
   :type array: np.ndarray

   :returns: ``True`` if the array is a structured array, ``False`` otherwise.
   :rtype: bool


.. py:function:: is_complete(array: numpy.ndarray, check_type: CompleteCheckType = 'finite') -> bool

   An array is complete if all its numeric values are finite and all other
   values are not ``None``.

   .. note::
       For arrays with ``dtype=np.object_``, the method only checks to make sure
       no value in the array is ``None``.

   :param check_type: Determines how completeness is defined.

                      nan
                          Requires that no values are ``np.NaN`` or ``None``.
                      finite
                          In addition to the criteria for ``nan`` all values must also be
                          finite (i.e., not ``np.inf`` or ``-np.inf``).
   :type check_type: {"finite", "nan"}
   :param array: The array to check.
   :type array: np.ndarray

   :returns: ``True`` if the array is complete, ``False`` otherwise.
   :rtype: bool


.. py:function:: finite_cases(array: numpy.ndarray) -> numpy.ndarray

   Return only the rows whose values are finite and not ``None``.

   :param array: The input array with possibly invalid values.
   :type array: np.ndarray

   :returns: An array with only non-null finite values.
   :rtype: np.ndarray


.. py:function:: group_by(array: numpy.ndarray, column: str | int) -> list[numpy.ndarray]

   Group an ``array`` by the values in the given ``column``. If ``array`` is
   as structured array, then ``column`` should be the name of one of the
   fields, otherwise it should be the index of the column you want to use.

   :param array: The array to group.
   :type array: np.ndarray
   :param column: If ``array`` is structured then ``column`` should be the name of the
                  column to group by. Otherwise, it should be the index of the column.
   :type column: str | int

   :returns: Returns the group as a list of arrays.
   :rtype: list