Merge pull request #198 from CITCOM-project/json_optional_data_path

Json optional data path

Author: christopher-wild

causal_testing/json_front/json_class.py

@@ -81,6 +81,11 @@ def setup(self, scenario: Scenario):
         # Populate the data
         if self.input_paths.data_paths:
             self.data = pd.concat([pd.read_csv(data_file, header=0) for data_file in self.input_paths.data_paths])
+        if len(self.data) == 0:
+            raise ValueError(
+                "No data found, either provide a path to a file containing data or manually populate the .data "
+                "attribute with a dataframe before calling .setup()"
+            )
         self._populate_metas()
 
     def _create_abstract_test_case(self, test, mutates, effects):

causal_testing/specification/metamorphic_relation.py

@@ -253,7 +253,7 @@ def generate_metamorphic_relations(dag: CausalDAG) -> list[MetamorphicRelation]:
     return metamorphic_relations
 
 
-if __name__ == "__main__": # pragma: no cover
+if __name__ == "__main__":  # pragma: no cover
     logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)
     parser = argparse.ArgumentParser(
         description="A script for generating metamorphic relations to test the causal relationships in a given DAG."

docs/source/frontends/json_front_end.rst

@@ -3,24 +3,38 @@ JSON Frontend
 The JSON frontend allows Causal Tests and parameters to be specified in JSON to allow for tests to be quickly written
 whilst retaining the flexibility of the Causal Testing Framework (CTF).
 
+basic workflow
+--------------
+The basic workflow of using the JSON frontend is as follows:
+
+#. Specify your test cases in the JSON format (more details below)
+#. Create your DAG in a dot file
+#. Initialise the JsonUtility class in python with a path of where you want the outputs saved
+#. Set the paths pointing the Json class to your json file, dag file and optionally your data file (see data section below) using the :func:`causal_testing.json_front.json_class.JsonUtility.set_paths` method
+#. Run the :func:`causal_testing.json_front.json_class.JsonUtility.setup` method providing your scenario
+#. Run the :func:`causal_testing.json_front.json_class.JsonUtility.run_json_tests` method, which will execute the test cases provided by the JSON file.
+
+Example Walkthrough
+-------------------
 An example is provided in `examples/poisson` which will be walked through in this README to better understand
 the framework
 
 run_causal_tests.py
--------------------
+*******************
 `examples/poisson/run_causal_tests.py <https://github.com/CITCOM-project/CausalTestingFramework/blob/main/examples/poisson/run_causal_tests.py>`_
 contains python code written by the user to implement scenario specific features
 such as:
-1. Custom Estimators
-2. Causal Variable specification
-3. Causal test case outcomes
-4. Meta constraint functions
-5. Mapping JSON distributions, effects, and estimators to python objects
+
+#. Custom Estimators
+#. Causal Variable specification
+#. Causal test case outcomes
+#. Meta constraint functions
+#. Mapping JSON distributions, effects, and estimators to python objects
 
 Use case specific information is also declared here such as the paths to the relevant files needed for the tests.
 
 causal_tests.json
------------------
+*****************
 `examples/poisson/causal_tests.json <https://github.c#om/CITCOM-project/CausalTestingFramework/blob/main/examples/poisson/causal_tests.json>`_ contains python code written by the user to implement scenario specific features
 is the JSON file that allows for the easy specification of multiple causal tests. Tests can be specified two ways; firstly by specifying a mutation lke in the example tests with the following structure:
 Each test requires:
@@ -45,7 +59,9 @@ The second method of specifying a test is to specify the test in a concrete form
 #. skip
 
 Run Commands
-------------
+************
+This example uses the Argparse utility built into the JSON frontend, which allows the frontend to be run from a commandline interface as shown here.
+
 To run the JSON frontend example from the root directory of the project, use::
 
     python examples\poisson\run_causal_tests.py --data_path="examples\poisson\data.csv" --dag_path="examples\poisson\dag.dot" --json_path="examples\poisson\causal_tests.json
@@ -59,4 +75,17 @@ Secondly a log file is produced, by default a file called `json_frontend.log` is
 
 The behaviour of where the log file is produced and named can be altered with the --log_path argument::
 
-    python examples\poisson\run_causal_tests.py -f --data_path="examples\poisson\data.csv" --dag_path="examples\poisson\dag.dot" --json_path="examples\poisson\causal_tests.json --log_path="example_directory\logname.log"
+    python examples\poisson\run_causal_tests.py -f --data_path="examples\poisson\data.csv" --dag_path="examples\poisson\dag.dot" --json_path="examples\poisson\causal_tests.json --log_path="example_directory\logname.log"
+
+
+Runtime Data
+----------
+
+There are currently 2 methods to inputting your runtime data into the JSON frontend:
+
+#. Providing one or more file paths to `.csv` files containing your data
+#. Setting a dataframe to the .data attribute of the JsonUtility instance, this must be done before the setup method is called.
+
+
+
+

tests/json_front_tests/test_json_class.py

@@ -3,7 +3,6 @@
 from statistics import StatisticsError
 import scipy
 
-
 from causal_testing.testing.estimators import LinearRegressionEstimator
 from causal_testing.testing.causal_test_outcome import NoEffect, Positive
 from tests.test_helpers import remove_temp_dir_if_existent
@@ -99,7 +98,7 @@ def test_f_flag(self):
         effects = {"NoEffect": NoEffect()}
         mutates = {
             "Increase": lambda x: self.json_class.scenario.treatment_variables[x].z3
-            > self.json_class.scenario.variables[x].z3
+                                  > self.json_class.scenario.variables[x].z3
         }
         estimators = {"LinearRegressionEstimator": LinearRegressionEstimator}
         with self.assertRaises(StatisticsError):
@@ -148,7 +147,7 @@ def test_run_json_tests_from_json(self):
         effects = {"NoEffect": NoEffect()}
         mutates = {
             "Increase": lambda x: self.json_class.scenario.treatment_variables[x].z3
-            > self.json_class.scenario.variables[x].z3
+                                  > self.json_class.scenario.variables[x].z3
         }
         estimators = {"LinearRegressionEstimator": LinearRegressionEstimator}
 
@@ -178,7 +177,7 @@ def test_generate_tests_from_json_no_dist(self):
         effects = {"NoEffect": NoEffect()}
         mutates = {
             "Increase": lambda x: self.json_class.scenario.treatment_variables[x].z3
-            > self.json_class.scenario.variables[x].z3
+                                  > self.json_class.scenario.variables[x].z3
         }
         estimators = {"LinearRegressionEstimator": LinearRegressionEstimator}
 
@@ -208,7 +207,7 @@ def test_formula_in_json_test(self):
         effects = {"Positive": Positive()}
         mutates = {
             "Increase": lambda x: self.json_class.scenario.treatment_variables[x].z3
-            > self.json_class.scenario.variables[x].z3
+                                  > self.json_class.scenario.variables[x].z3
         }
         estimators = {"LinearRegressionEstimator": LinearRegressionEstimator}
 
@@ -241,6 +240,26 @@ def test_run_concrete_json_testcase(self):
             temp_out = reader.readlines()
         self.assertIn("FAILED", temp_out[-1])
 
+    def test_no_data_provided(self):
+        example_test = {
+            "tests": [
+                {
+                    "name": "test1",
+                    "mutations": {"test_input": "Increase"},
+                    "estimator": "LinearRegressionEstimator",
+                    "estimate_type": "ate",
+                    "effect_modifiers": [],
+                    "expected_effect": {"test_output": "NoEffect"},
+                    "skip": False,
+                }
+            ]
+        }
+        json_class = JsonUtility("temp_out.txt", True)
+        json_class.set_paths(self.json_path, self.dag_path)
+
+        with self.assertRaises(ValueError):
+            json_class.setup(self.scenario)
+
     def tearDown(self) -> None:
         remove_temp_dir_if_existent()