:py:mod:`causal_testing.surrogate.causal_surrogate_assisted`
============================================================

.. py:module:: causal_testing.surrogate.causal_surrogate_assisted

.. autoapi-nested-parse::

   Module containing classes to define and run causal surrogate assisted test cases



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

Classes
~~~~~~~

.. autoapisummary::

   causal_testing.surrogate.causal_surrogate_assisted.SimulationResult
   causal_testing.surrogate.causal_surrogate_assisted.SearchAlgorithm
   causal_testing.surrogate.causal_surrogate_assisted.Simulator
   causal_testing.surrogate.causal_surrogate_assisted.CausalSurrogateAssistedTestCase




Attributes
~~~~~~~~~~

.. autoapisummary::

   causal_testing.surrogate.causal_surrogate_assisted.logger


.. py:data:: logger

   

.. py:class:: SimulationResult


   Data class holding the data and result metadata of a simulation

   .. py:attribute:: data
      :type: dict

      

   .. py:attribute:: fault
      :type: bool

      

   .. py:attribute:: relationship
      :type: str

      

   .. py:method:: to_dataframe() -> pandas.DataFrame

      Convert the simulation result data to a pandas DataFrame



.. py:class:: SearchAlgorithm


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

   Class to be inherited with the search algorithm consisting of a search function and the fitness function of the
   space to be searched

   .. py:method:: search(surrogate_models: list[causal_testing.estimation.cubic_spline_estimator.CubicSplineRegressionEstimator], scenario: causal_testing.specification.scenario.Scenario) -> list
      :abstractmethod:

      Function which implements a search routine which searches for the optimal fitness value for the specified
      scenario
      :param surrogate_models: The surrogate models to be searched
      :param scenario:  The modelling scenario



.. py:class:: Simulator


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

   Class to be inherited with Simulator specific functions to start, shutdown and run the simulation with the give
   config file

   .. py:method:: startup(**kwargs)
      :abstractmethod:

      Function that when run, initialises and opens the Simulator


   .. py:method:: shutdown(**kwargs)
      :abstractmethod:

      Function to safely exit and shutdown the Simulator


   .. py:method:: run_with_config(configuration: dict) -> SimulationResult
      :abstractmethod:

      Run the simulator with the given configuration and return the results in the structure of a
      SimulationResult
      :param configuration: The configuration required to initialise the Simulation
      :return: Simulation results in the structure of the SimulationResult data class



.. py:class:: CausalSurrogateAssistedTestCase(scenario: causal_testing.specification.scenario.Scenario, causal_dag: causal_testing.specification.causal_dag.CausalDAG, search_algorithm: SearchAlgorithm, simulator: Simulator)


   A class representing a single causal surrogate assisted test case.

   .. py:method:: execute(df: pandas.DataFrame, max_executions: int = 200, custom_data_aggregator: Callable[[dict, dict], dict] = None)

      For this specific test case, a search algorithm is used to find the most contradictory point in the input
      space which is, therefore, most likely to indicate incorrect behaviour. This cadidate test case is run against
      the simulator, checked for faults and the result returned.
      :param df: An dataframe which contains data relevant to the specified scenario
      :param max_executions: Maximum number of simulator executions before exiting the search
      :param custom_data_aggregator:
      :return: tuple containing SimulationResult or str, execution number and dataframe


   .. py:method:: generate_surrogates(df: pandas.DataFrame) -> list[causal_testing.estimation.cubic_spline_estimator.CubicSplineRegressionEstimator]

      Generate a surrogate model for each edge of the DAG that specifies it is included in the DAG metadata.
      :param df: An dataframe which contains data relevant to the specified scenario
      :return: A list of surrogate models