coonfit.helper
==============

.. py:module:: coonfit.helper

.. autoapi-nested-parse::

   Utility functions for the coonfit regression workflow.

   This module provides supporting functions used during predictor validation and
   data quality assessment. It includes tools for detecting rank-deficient
   predictor matrices (which would cause the normal equations to be singular) and
   for counting the number of usable pixels within a boolean selector mask.



Functions
---------

.. autoapisummary::

   coonfit.helper.check_rank_deficiency
   coonfit.helper.usable_pixels_count
   coonfit.helper.usable_pixels_info


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

.. py:function:: check_rank_deficiency(array, return_by_issue_type = False)

   Check if matrix is rank deficient and identify problematic columns.

   Returns a dictionary with column indices (key) and issue description (value).
   An empty dictionary indicates that no rank deficiency was detected.

   :param array: Matrix to check for rank deficiency
   :type array: NDArray
   :param return_by_issue_type: If True, returns nested dictionary separating issues by type:
                                {"linear_dependent": [...], "all_zero": [...]}
   :type return_by_issue_type: bool, optional

   :returns: Problematic columns and their issues. Uses :func:`numpy.linalg.matrix_rank`
             to determine the rank of the array.
   :rtype: dict[int, str] or dict[str, list[int]]

   .. seealso::

      :func:`~coonfit.parallel.get_XT_X_dependency`
          Check predictors for linear dependency.


.. py:function:: usable_pixels_count(selector)

   Count the number of usable pixels determined by the selector.

   :param selector: Boolean array where True indicates a usable pixel and False
                    indicates a pixel to be excluded
   :type selector: NDArray

   :returns: Number of True values in the selector array (count of usable pixels).
             Uses :func:`numpy.unique` to count occurrences.
   :rtype: int

   .. seealso::

      :func:`usable_pixels_info`
          Print the fraction of usable pixels.

   .. rubric:: Examples

   >>> selector = np.array([True, True, False, True, False])
   >>> usable_pixels_count(selector)
   3


.. py:function:: usable_pixels_info(all_pixels, data_pixels)

   Print the fraction of usable pixels.

   :param all_pixels: Total number of pixels in the dataset
   :type all_pixels: int
   :param data_pixels: Number of pixels that contain usable data
   :type data_pixels: int

   .. seealso::

      :func:`usable_pixels_count`
          Count the number of usable pixels.

   .. rubric:: Examples

   >>> usable_pixels_info(1000, 750)
   Of all_pixels=1000 there are data_pixels=750, i.e. 75.0% are usable