Merge branch 'main' into dafni-dev

Author: f-allian

.gitignore

@@ -55,6 +55,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/build/
+docs/source/autoapi
 
 # v/docs/build/scode
 .vscode/
@@ -63,4 +64,4 @@ docs/build/
 temp/
 
 # log files
-*.log
+*.log

CITATION.cff

@@ -0,0 +1,78 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Foster
+  given-names: Michael
+  orcid: "https://orcid.org/0000-0001-8233-9873"
+- family-names: Clark
+  given-names: Andrew
+  orcid: "https://orcid.org/0000-0002-6830-0566"
+- family-names: Wild
+  given-names: Christopher
+  orcid: "https://orcid.org/0009-0009-1195-1497"
+- family-names: Allian
+  given-names: Farhad
+  orcid: "https://orcid.org/0000-0002-4569-0370"
+- family-names: Turner
+  given-names: Robert
+  orcid: "https://orcid.org/0000-0002-1353-1404"
+- family-names: Somers
+  given-names: Richard
+  orcid: "https://orcid.org/0009-0009-1195-1497"
+- family-names: Latimer
+  given-names: Nicholas
+  orcid: "https://orcid.org/0000-0001-5304-5585"
+- family-names: Walkinshaw
+  given-names: Neil
+  orcid: "https://orcid.org/0000-0003-2134-6548"
+- family-names: Hierons
+  given-names: Robert M.
+  orcid: "https://orcid.org/0000-0003-2134-6548"
+contact:
+- family-names: Foster
+  given-names: Michael
+  orcid: "https://orcid.org/0000-0001-8233-9873"
+doi: 10.15131/shef.data.28539398.v1
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Foster
+    given-names: Michael
+    orcid: "https://orcid.org/0000-0001-8233-9873"
+  - family-names: Clark
+    given-names: Andrew
+    orcid: "https://orcid.org/0000-0002-6830-0566"
+  - family-names: Wild
+    given-names: Christopher
+    orcid: "https://orcid.org/0009-0009-1195-1497"
+  - family-names: Allian
+    given-names: Farhad
+    orcid: "https://orcid.org/0000-0002-4569-0370"
+  - family-names: Turner
+    given-names: Robert
+    orcid: "https://orcid.org/0000-0002-1353-1404"
+  - family-names: Somers
+    given-names: Richard
+    orcid: "https://orcid.org/0009-0009-1195-1497"
+  - family-names: Latimer
+    given-names: Nicholas
+    orcid: "https://orcid.org/0000-0001-5304-5585"
+  - family-names: Walkinshaw
+    given-names: Neil
+    orcid: "https://orcid.org/0000-0003-2134-6548"
+  - family-names: Hierons
+    given-names: Robert M.
+    orcid: "https://orcid.org/0000-0003-2134-6548"
+  date-published: 2025-03-06
+  doi: 10.21105/joss.07739
+  issn: 2475-9066
+  issue: 107
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 7739
+  title: The Causal Testing Framework
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.07739"
+  volume: 10
+title: The Causal Testing Framework

README.md

@@ -8,8 +8,9 @@
 [![Documentation Status](https://readthedocs.org/projects/causal-testing-framework/badge/?version=latest)](https://causal-testing-framework.readthedocs.io/en/latest/?badge=latest)
 ![Dynamic TOML Badge](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FCITCOM-project%2FCausalTestingFramework%2Fmain%2Fpyproject.toml&query=%24.project%5B'requires-python'%5D&label=python)
 ![PyPI - Version](https://img.shields.io/pypi/v/causal-testing-framework)
-[![DOI](https://t.ly/FCT1B)](https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516)
 ![GitHub Licens[schematic.tex](images%2Fschematic.tex)e](https://img.shields.io/github/license/CITCOM-project/CausalTestingFramework)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.07739/status.svg)](https://doi.org/10.21105/joss.07739)
+[![DOI](https://img.shields.io/badge/doi-10.26180/5c6e1160b8d8a-blue.svg?style=flat&labelColor=whitesmoke&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAB8AAAAfCAYAAAAfrhY5AAAJsklEQVR42qWXd1DTaRrHf%2BiB2Hdt5zhrAUKz4IKEYu9IGiGFFJJQ0gkJCAKiWFDWBRdFhCQUF3UVdeVcRQEBxUI3yY9iEnQHb3bdW1fPubnyz%2F11M7lvEHfOQee2ZOYzPyDv%2B3yf9%2Fk95YX4fx%2BltfUt08GcFEuPR4U9hDDZ%2FVngIlhb%2FSiI6InkTgLzgDcgfvtnovhH4BzoVlrbwr55QnhCtBW4QHXnFrZbPBaQoBh4%2FSYH2EnpBEtqcDMVzB93wA%2F8AFwa23XFGcc8CkT3mxz%2BfXWtq9T9IQlLIXYEuHojudb%2BCM7Hgdq8ydi%2FAHiBXyY%2BLjwFlAEnS6Jnar%2FvnQVhvdzasad0eKvWZKe8hvDB2ofLZ%2FZEcWsh%2BhyIuyO5Bxs2iZIE4nRv7NWAb0EO8AC%2FWPxjYAWuOEX2MSXZVgPxzmRL3xKz3ScGpx6p6QnOx4mDIFqO0w6Q4fEhO5IzwxlSwyD2FYHzwAW%2BAZ4fEsf74gCumykwNHskLM7taQxLYjjIyy8MUtraGhTWdkfhkFJqtvuVl%2F9l2ZquDfEyrH8B0W06nnpH3JtIyRGpH1iJ6SfxDIHjRXHJmdQjLpfHeN54gnfFx4W9QRnovx%2FN20aXZeTD2J84hn3%2BqoF2Tqr14VqTPUCIcP%2B5%2Fly4qC%2BUL3sYxSvNj1NwsVYPsWdMUfomsdkYm3Tj0nbV0N1wRKwFe1MgKACDIBdMAhPE%2FwicwNWxll8Ag40w%2BFfhibJkGHmutjYeQ8gVlaN%2BjO51nDysa9TwNUFMqaGbKdRJZFfOJSp6mkRKsv0rRIpEVWjAvyFkxNOEpwvcAVPfEe%2Bl8ojeNTx3nXLBcWRrYGxSRjDEk0VlpxYrbe1ZmaQ5xuT0u3r%2B2qe5j0J5uytiZPGsRL2Jm32AldpxPUNJ3jmmsN4x62z1cXrbedXBQf2yvIFCeZrtyicZZG2U2nrrBJzYorI2EXLrvTfCSB43s41PKEvbZDEfQby6L4JTj%2FfIwam%2B4%2BwucBu%2BDgNK05Nle1rSt9HvR%2FKPC4U6LTfvUIaip1mjIa8fPzykii23h2eanT57zQ7fsyYH5QjywwlooAUcAdOh5QumgTHx6aAO7%2FL52eaQNEShrxfhL6albEDmfhGflrsT4tps8gTHNOJbeDeBlt0WJWDHSgxs6cW6lQqyg1FpD5ZVDfhn1HYFF1y4Eiaqa18pQf3zzYMBhcanlBjYfgWNayAf%2FASOgklu8bmgD7hADrk4cRlOL7NSOewEcbqSmaivT33QuFdHXj5sdvjlN5yMDrAECmdgDWG2L8P%2BAKLs9ZLZ7dJda%2BB4Xl84t7QvnKfvpXJv9obz2KgK8dXyqISyV0sXGZ0U47hOA%2FAiigbEMECJxC9aoKp86re5O5prxOlHkcksutSQJzxZRlPZmrOKhsQBF5zEZKybUC0vVjG8PqOnhOq46qyDTDnj5gZBriWCk4DvXrudQnXQmnXblebhAC2cCB6zIbM4PYgGl0elPSgIf3iFEA21aLdHYLHUQuVkpgi02SxFdrG862Y8ymYGMvXDzUmiX8DS5vKZyZlGmsSgQqfLub5RyLNS4zfDiZc9Edzh%2FtCE%2BX8j9k%2FqWB071rcZyMImne1SLkL4GRw4UPHMV3jjwEYpPG5uW5fAEot0aTSJnsGAwHJi2nvF1Y5OIqWziVCQd5NT7t6Q8guOSpgS%2Fa1dSRn8JGGaCD3BPXDyQRG4Bqhu8XrgAp0yy8DMSvvyVXDgJcJTcr1wQ2BvFKf65jqhvmxXUuDpGBlRvV36XvGjQzLi8KAKT2lYOnmxQPGorURSV0NhyTIuIyqOmKTMhQ%2BieEsgOgpc4KBbfDM4B3SIgFljvfHF6cef7qpyLBXAiQcXvg5l3Iunp%2FWv4dH6qFziO%2BL9PbrimQ9RY6MQphEfGUpOmma7KkGzuS8sPUFnCtIYcKCaI9EXo4HlQLgGrBjbiK5EqMj2AKWt9QWcIFMtnVvQVDQV9lXJJqdPVtUQpbh6gCI2Ov1nvZts7yYdsnvRgxiWFOtNJcOMVLn1vgptVi6qrNiFOfEjHCDB3J%2BHDLqUB77YgQGwX%2Fb1eYna3hGKdlqJKIyiE4nSbV8VFgxmxR4b5mVkkeUhMgs5YTi4ja2XZ009xJRHdkfwMi%2BfocaancuO7h%2FMlcLOa0V%2FSw6Dq47CumRQAKhgbOP8t%2BMTjuxjJGhXCY6XpmDDFqWlVYbQ1aDJ5Cptdw4oLbf3Ck%2BdWkVP0LpH7s9XLPXI%2FQX8ws%2Bj2In63IcRvOOo%2BTTjiN%2BlssfRsanW%2B3REVKoavBOAPTXABW4AL7e4NygHdpAKBscmlDh9Jysp4wxbnUNna3L3xBvyE1jyrGIkUHaqQMuxhHElV6oj1picvgL1QEuS5PyZTEaivqh5vUCKJqOuIgPFGESns8kyFk7%2FDxyima3cYxi%2FYOQCj%2F%2B9Ms2Ll%2Bhn4FmKnl7JkGXQGDKDAz9rUGL1TIlBpuJr9Be2JjK6qPzyDg495UxXYF7JY1qKimw9jWjF0iV6DRIqE%2B%2FeWG0J2ofmZTk0mLYVd4GLiFCOoKR0Cg727tWq981InYynvCuKW43aXgEjofVbxIqrm0VL76zlH3gQzWP3R3Bv9oXxclrlO7VVtgBRpSP4hMFWJ8BrUSBCJXC07l40X4jWuvtc42ofNCxtlX2JH6bdeojXgTh5TxOBKEyY5wvBE%2BACh8BtOPNPkApjoxi5h%2B%2FFMQQNpWvZaMH7MKFu5Ax8HoCQdmGkJrtnOiLHwD3uS5y8%2F2xTSDrE%2F4PT1yqtt6vGe8ldMBVMEPd6KwqiYECHDlfbvzphcWP%2BJiZuL5swoWQYlS%2Br7Yu5mNUiGD2retxBi9fl6RDGn4Ti9B1oyYy%2BMP5G87D%2FCpRlvdnuy0PY6RC8BzTA40NXqckQ9TaOUDywkYsudxJzPgyDoAWn%2BB6nEFbaVxxC6UXjJiuDkW9TWq7uRBOJocky9iMfUhGpv%2FdQuVVIuGjYqACbXf8aa%2BPeYNIHZsM7l4s5gAQuUAzRUoT51hnH3EWofXf2vkD5HJJ33vwE%2FaEWp36GHr6GpMaH4AAPuqM5eabH%2FhfG9zcCz4nN6cPinuAw6IHwtvyB%2FdO1toZciBaPh25U0ducR2PI3Zl7mokyLWKkSnEDOg1x5fCsJE9EKhH7HwFNhWMGMS7%2BqxyYsbHHRUDUH4I%2FAheQY7wujJNnFUH4KdCju83riuQeHU9WEqNzjsJFuF%2FdTDAZ%2FK7%2F1WaAU%2BAWymT59pVMT4g2AxcwNa0XEBDdBDpAPvgDIH73R25teeuAF5ime2Ul0OUIiG4GpSAEJeYW9wDTf43wfwHgHLKJoPznkwAAAABJRU5ErkJggg%3D%3D)](http://doi.org/10.15131/shef.data.24427516.v2)
 
 Causal testing is a causal inference-driven framework for functional black-box testing. This framework utilises
 graphical causal inference (CI) techniques for the specification and functional testing of software from a black-box

causal_testing/main.py

@@ -281,17 +281,36 @@ def create_causal_test(self, test: dict, base_test: BaseTestCase) -> CausalTestC
         if estimator_class is None:
             raise ValueError(f"Unknown estimator: {test['estimator']}")
 
+        # Handle combined queries (global and test-specific)
+        test_query = test.get("query")
+        combined_query = None
+
+        if self.query and test_query:
+            combined_query = f"({self.query}) and ({test_query})"
+            logger.info(
+                f"Combining global query '{self.query}' with test-specific query "
+                f"'{test_query}' for test '{test['name']}'"
+            )
+        elif test_query:
+            combined_query = test_query
+            logger.info(f"Using test-specific query for '{test['name']}': {test_query}")
+        elif self.query:
+            combined_query = self.query
+            logger.info(f"Using global query for '{test['name']}': {self.query}")
+
+        filtered_df = self.data.query(combined_query) if combined_query else self.data
+
         # Create the estimator with correct parameters
         estimator = estimator_class(
             base_test_case=base_test,
             treatment_value=test.get("treatment_value"),
             control_value=test.get("control_value"),
             adjustment_set=test.get("adjustment_set", self.causal_specification.causal_dag.identification(base_test)),
-            df=self.data,
+            df=filtered_df,
             effect_modifiers=None,
             formula=test.get("formula"),
             alpha=test.get("alpha", 0.05),
-            query="",
+            query=combined_query,
         )
 
         # Get effect type and create expected effect
@@ -424,7 +443,7 @@ def save_results(self, results: List[CausalTestResult]) -> None:
                 "effect": test_config.get("effect", "direct"),
                 "treatment_variable": test_config["treatment_variable"],
                 "expected_effect": test_config["expected_effect"],
-                "formula": test_config.get("formula"),
+                "formula": result.estimator.formula if hasattr(result.estimator, "formula") else None,
                 "alpha": test_config.get("alpha", 0.05),
                 "skip": test_config.get("skip", False),
                 "passed": test_passed,

docs/source/modules/causal_specification.rst

@@ -14,6 +14,9 @@ Causal Specification
 - A causal specification is simply the combination of these components: a series of requirements for the scenario-under-test and a causal DAG representing causality
   amongst the inputs and outputs. We will discuss these in more detail below.
 
+- Collectively, the components of the causal specification provide both contextual information in the form of constraints and requirements, as well as causal information in the form of a causal DAG.
+  Later on, these components will be used to design statistical experiments that can answer causal questions about the scenario-under-test, such as `Does opening a window impair the viruses ability to spread?`
+
 Scenario Requirements
 ---------------------
 
@@ -30,14 +33,18 @@ Causal DAG
 ----------
 
 In order to apply CI techniques, we need to capture causality amongst the inputs and outputs in the scenario-under-test.
-Therefore, for each scenario, the user must define a causal DAG. While there is generally no guidance/algorithm that can be followed to create a causal DAG,
-there are a couple of requirements that should be satisfied.
+Therefore, for each scenario, the user must define a causal DAG.
+As an example, consider the DAG shown below for the Poisson line process, which can be found in our `examples` directory.
+Here, the model has three inputs: `width`, `height`, and `intensity`.
+These inputs control the number of lines (`num_lines_abs`) and polygons (`num_shapes_abs`) that are drawn, which then feed into the numbers of lines (`num_lines_unit`) and polygons (`num_shapes_unit`) per unit area.
+Note though that the `num_lines_abs` does not have a direct causal effect on `num_shapes_unit`, since the number of polygons per unit area is defined entirely by the total number of polygons and the area of the sampling window.
+
+.. literalinclude:: ../../../examples/poisson-line-process/dag.dot
+   :language: graphviz
+   :caption: Example Causal DAG for the Poisson line process example.
 
+Unfortunately, there is no universally applicable guidance or an algorithm that can be followed to create a causal DAG, there are three general requirements that should be satisfied.
 
 #. The DAG must contain all inputs and outputs involved in the scenario-under-test.
 #. If there are any other variables which are not directly involved but are expected to have a causal relationship with the variables in the scenario-under-test, these should also be added to the graph. For example, the size of the room might be partially caused by the simulated location (house styles, average wealth etc.), in which case location should be added to the DAG with an edge to room size and any other variables it is deemed to influence.
 #. If in doubt, add an edge. It is a stronger assumption to exclude an edge (X and Y are independent) than to include one (X has some potentially negligiable causal effect on Y).
-
--  Collectively, the components of the causal specification provide both contextual information in the form of constraints and requirements,
-   as well as causal information in the form of a causal DAG. Later on, these components will be used to design statistical experiments that
-   can answer causal questions about the scenario-under-test, such as `Does opening a window impair the viruses ability to spread?`

paper/paper.md

@@ -25,7 +25,7 @@ authors:
     orcid: 0000-0002-1353-1404
     affiliation: 1
   - name: Richard Somers
-    orcid: 0009-0009-1195-1497
+    orcid: 0000-0002-1101-9722
     affiliation: 1
   - name: Nicholas Latimer
     orcid: 0000-0001-5304-5585
@@ -34,7 +34,7 @@ authors:
     orcid: 0000-0003-2134-6548
     affiliation: 1
   - name: Robert M. Hierons
-    orcid: 0000-0003-2134-6548
+    orcid: 0000-0002-4771-1446
     affiliation: 1
 affiliations:
  - name: University of Sheffield, UK

tests/main_tests/test_main.py

@@ -144,6 +144,67 @@ def test_ctf(self):
 
         self.assertEqual(tests_passed, [True])
 
+    def test_global_query(self):
+        framework = CausalTestingFramework(self.paths)
+        framework.setup()
+
+        query_framework = CausalTestingFramework(self.paths, query="test_input > 0")
+        query_framework.setup()
+
+        self.assertTrue(len(query_framework.data) > 0)
+        self.assertTrue((query_framework.data["test_input"] > 0).all())
+
+        with open(self.test_config_path, "r", encoding="utf-8") as f:
+            test_configs = json.load(f)
+
+        test_config = test_configs["tests"][0].copy()
+        if "query" in test_config:
+            del test_config["query"]
+
+        base_test = query_framework.create_base_test(test_config)
+        causal_test = query_framework.create_causal_test(test_config, base_test)
+
+        self.assertTrue((causal_test.estimator.df["test_input"] > 0).all())
+
+        query_framework.create_variables()
+        query_framework.create_scenario_and_specification()
+
+        self.assertIsNotNone(query_framework.scenario)
+        self.assertIsNotNone(query_framework.causal_specification)
+
+    def test_test_specific_query(self):
+        framework = CausalTestingFramework(self.paths)
+        framework.setup()
+
+        with open(self.test_config_path, "r", encoding="utf-8") as f:
+            test_configs = json.load(f)
+
+        test_config = test_configs["tests"][0].copy()
+        test_config["query"] = "test_input > 0"
+
+        base_test = framework.create_base_test(test_config)
+        causal_test = framework.create_causal_test(test_config, base_test)
+
+        self.assertTrue(len(causal_test.estimator.df) > 0)
+        self.assertTrue((causal_test.estimator.df["test_input"] > 0).all())
+
+    def test_combined_queries(self):
+        global_framework = CausalTestingFramework(self.paths, query="test_input > 0")
+        global_framework.setup()
+
+        with open(self.test_config_path, "r", encoding="utf-8") as f:
+            test_configs = json.load(f)
+
+        test_config = test_configs["tests"][0].copy()
+        test_config["query"] = "test_output > 0"
+
+        base_test = global_framework.create_base_test(test_config)
+        causal_test = global_framework.create_causal_test(test_config, base_test)
+
+        self.assertTrue(len(causal_test.estimator.df) > 0)
+        self.assertTrue((causal_test.estimator.df["test_input"] > 0).all())
+        self.assertTrue((causal_test.estimator.df["test_output"] > 0).all())
+
     def test_parse_args(self):
         with unittest.mock.patch(
             "sys.argv",

tests/resources/data/tests.json

@@ -5,6 +5,7 @@
     "estimator": "LinearRegressionEstimator",
     "estimate_type": "coefficient",
     "effect_modifiers": [],
+    "query": "test_input > 0",
     "expected_effect": {"test_output": "NoEffect"},
     "skip": false
   },
@@ -14,6 +15,7 @@
     "estimator": "LinearRegressionEstimator",
     "estimate_type": "coefficient",
     "effect_modifiers": [],
+    "query": "test_input <= 5",
     "expected_effect": {"test_output": "NoEffect"},
     "skip": true
   }]