jpt.learning.dependency
=======================

.. py:module:: jpt.learning.dependency

.. autoapi-nested-parse::

   Dependency discovery for JPT learning.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/jpt/learning/dependency/base/index
   /autoapi/jpt/learning/dependency/xi/index


Classes
-------

.. autoapisummary::

   jpt.learning.dependency.DependencyDiscovery
   jpt.learning.dependency.XiDependencyDiscovery


Package Contents
----------------

.. py:class:: DependencyDiscovery

   Bases: :py:obj:`abc.ABC`


   Abstract base class for dependency discovery.

   Subclasses implement a strategy for determining
   which target variables depend on which features,
   given the training data. The result is used by
   the JPT learning algorithm to restrict impurity
   computation to dependent variable pairs.

   Implementations must be serializable via
   ``to_json()``/``from_json()`` so that the
   discovery strategy is preserved when the JPT
   model is saved and loaded.


   .. py:attribute:: _REGISTRY
      :type:  dict[str, type[DependencyDiscovery]]


   .. py:method:: __init_subclass__(**kwargs: Any) -> None
      :classmethod:


      Auto-register subclasses for
      deserialization.



   .. py:method:: __call__(data: numpy.ndarray, features: list[jpt.variables.Variable], targets: list[jpt.variables.Variable], variables: list[jpt.variables.Variable]) -> dict[jpt.variables.Variable, list[jpt.variables.Variable]]
      :abstractmethod:


      Discover dependencies from data.

      :param data:      preprocessed data array
                        (n_samples x n_variables)
      :param features:  list of feature Variables
      :param targets:   list of target Variables
      :param variables: list of all Variables
                        (defines column order)
      :returns:         dict mapping each feature
                        Variable to a list of
                        dependent target Variables



   .. py:method:: to_json() -> dict[str, Any]
      :abstractmethod:


      Serialize the strategy configuration.

      Must include a ``'type'`` key with the class
      name for deserialization dispatch.

      :returns: JSON-serializable dict



   .. py:method:: from_json(data: dict[str, Any]) -> DependencyDiscovery | None
      :classmethod:


      Deserialize a strategy from JSON.

      Dispatches to the appropriate subclass based
      on the ``'type'`` key.

      :param data: dict from ``to_json()``
      :returns:    DependencyDiscovery instance



.. py:class:: XiDependencyDiscovery(alpha: float = 0.05)

   Bases: :py:obj:`jpt.learning.dependency.base.DependencyDiscovery`


   Dependency discovery via Chatterjee's xi.

   Computes the xi correlation between all
   feature-target pairs and retains only those
   where the correlation is statistically
   significant under the asymptotic null
   distribution of xi.

   Under H0 (independence with continuous Y),
   sqrt(n) * xi ~ N(0, 2/5).

   :param alpha: significance level for the
                 independence test


   .. py:attribute:: alpha
      :type:  float
      :value: 0.05



   .. py:method:: __call__(data: numpy.ndarray, features: list[jpt.variables.Variable], targets: list[jpt.variables.Variable], variables: list[jpt.variables.Variable]) -> dict[jpt.variables.Variable, list[jpt.variables.Variable]]

      Discover dependencies via xi correlation.

      :param data:      data array (n x d)
      :param features:  list of feature Variables
      :param targets:   list of target Variables
      :param variables: list of all Variables
      :returns:         dict mapping features to
                        their dependent targets



   .. py:method:: to_json() -> dict[str, Any]

      Serialize configuration.

      :returns: JSON-serializable dict



   .. py:method:: from_json(data: dict[str, Any]) -> XiDependencyDiscovery
      :classmethod:


      Restore from JSON.

      :param data: dict from ``to_json()``
      :returns:    XiDependencyDiscovery instance