dpg.core
========

.. py:module:: dpg.core


Attributes
----------

.. autoapisummary::

   dpg.core.HAS_OMEGACONF
   dpg.core.DEFAULT_DPG_CONFIG


Exceptions
----------

.. autoapisummary::

   dpg.core.DPGError


Classes
-------

.. autoapisummary::

   dpg.core.DecisionPredicateGraph


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

.. py:data:: HAS_OMEGACONF
   :value: True


.. py:data:: DEFAULT_DPG_CONFIG

.. py:exception:: DPGError

   Bases: :py:obj:`Exception`


   Base exception class for DPG-specific errors


.. py:class:: DecisionPredicateGraph(model: Any, feature_names: Iterable[str], target_names: Optional[Iterable[str]] = None, config_file: str = 'config.yaml', dpg_config: Optional[Dict[str, Any]] = None)

   .. py:attribute:: SUPPORTED_GRAPH_CONSTRUCTION_MODES

      Main class for converting tree-based ensemble models into interpretable graphs.

      Converts the internal decision paths of a tree-based ensemble (Random Forest,
      AdaBoost, Extra Trees, …) into a compact directed graph — the
      *Decision Predicate Graph* — that exposes which feature conditions the model
      uses, how often, and in what order.


   .. py:attribute:: model


   .. py:attribute:: feature_names


   .. py:attribute:: target_names
      :value: None



   .. py:attribute:: perc_var


   .. py:attribute:: decimal_threshold


   .. py:attribute:: n_jobs


   .. py:attribute:: graph_construction_mode


   .. py:attribute:: visualization_config


   .. py:method:: fit(X_train: Any) -> Any

      Main pipeline: Extract decision paths → Build graph → Generate visualization.

      :param X_train: Training data (n_samples, n_features)

      :returns: Visualizable graph object
      :rtype: graphviz.Digraph



   .. py:method:: tracing_ensemble(case_id: int, sample: Any) -> Generator[List[str], None, None]

      Extract decision path for a single sample (generator version).

      :param case_id: Sample identifier
      :param sample: Feature values (1D array)

      :Yields: *List[str]* -- Path segments as [prefix, decision/prediction]



   .. py:method:: tracing_ensemble_parallel(case_id: int, sample: Any) -> List[List[str]]

      Extract decision path for a single sample (list version for parallel workers).

      :param case_id: Sample identifier used to name each path prefix.
      :param sample: Feature values array, shape ``(n_features,)``.

      :returns: List of ``[prefix, event]`` pairs representing the full decision path
                across all trees in the ensemble.



   .. py:method:: filter_log(log: Any) -> Any

      Filter paths based on frequency threshold.

      :param log: DataFrame of extracted paths

      :returns: Filtered paths meeting perc_var threshold
      :rtype: pd.DataFrame



   .. py:method:: discover_dfg(log: Any) -> Dict[Tuple[str, str], int]

      Build directed frequency graph from path logs.

      :param log: DataFrame of decision paths

      :returns: Edge frequencies as {(source, target): count}
      :rtype: Dict[tuple, int]



   .. py:method:: discover_dfg_execution_trace(log: Any) -> Dict[Tuple[str, str], int]

      Build a directed frequency graph directly from the raw execution trace.

      If ``perc_var > 0``, infrequent edges are removed using a minimum edge
      count of ``total_cases * perc_var`` where ``total_cases`` is the number
      of unique case ids in the raw trace log.

      :param log: Raw DataFrame of decision paths

      :returns: Edge frequencies as {(source, target): count}
      :rtype: Dict[tuple, int]



   .. py:method:: generate_dot(dfg: Dict[Tuple[str, str], int]) -> Any

      Convert frequency graph to Graphviz format.

      :param dfg: Directed frequency graph

      :returns: Visualizable graph
      :rtype: graphviz.Digraph



   .. py:method:: to_networkx(graphviz_graph: Any) -> Tuple[Any, List[List[str]]]

      Convert Graphviz graph to NetworkX format.

      :param graphviz_graph: Input graph

      :returns: NetworkX graph and node metadata
      :rtype: Tuple[nx.DiGraph, List]