Merge remote-tracking branch 'origin/main' into dafni-dev

# Conflicts:
#	dafni/src/main_dafni.py

Author: f-allian

.github/workflows/ci-tests-drafts.yaml

@@ -30,7 +30,7 @@ jobs:
       run: |
         pytest --cov=causal_testing --cov-report=xml
     - name: "Upload coverage to Codecov"
-      uses: codecov/codecov-action@v2
+      uses: codecov/codecov-action@v5
       with:
         fail_ci_if_error: true
         token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/ci-tests.yaml

@@ -36,7 +36,7 @@ jobs:
       run: |
         pytest --cov=causal_testing --cov-report=xml
     - name: "Upload coverage to Codecov"
-      uses: codecov/codecov-action@v2
+      uses: codecov/codecov-action@v5
       with:
         fail_ci_if_error: true
         token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/joss.yaml

@@ -0,0 +1,29 @@
+name: JOSS article compilation
+on:
+  push:
+    paths:
+      - paper/**
+      - images/schematic.png
+      - .github/workflows/draft-pdf.yml
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

.github/workflows/lint-format.yaml

@@ -25,7 +25,7 @@ jobs:
 
       - name: Archive production artifacts
         if: ${{ success() }} || ${{ failure() }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: MegaLinter reports
           path: |

README.md

@@ -52,23 +52,46 @@ pip install . # For core API only
 pip install -e . # For editable install, useful for development work
 ```
 For more information on how to use the Causal Testing Framework, please refer to our [documentation](https://causal-testing-framework.readthedocs.io/en/latest/?badge=latest).  
+
+>[!NOTE]
+>We recommend you use a 64 bit OS (standard in most modern machines) as we have had reports of the installation crashing on some 32 bit Debian installations.
+
+## Usage
+>[!NOTE]
+> Example usage can be found in the `examples` directory.
+
+1. To run the causal testing framework, you need some runtime data from your system, some causal test cases, and a causal DAG that specifies the expected causal relationships between the variables in your runtime data (and any other relevant variables that are _not_ recorded in the data but are known to be relevant).
+
+2. If you do not already have causal test cases, you can convert your causal DAG to causal tests by running the following command.
+
+```
+python causal_testing/testing/metamorphic_relation.py --dag_path $PATH_TO_DAG --output_path $PATH_TO_TESTS
+```
+
+3. You can now execute your tests by running the following command.
+```
+python -m causal_testing --dag_path $PATH_TO_DAG --data_paths $PATH_TO_DATA --test_config $PATH_TO_TESTS --output $OUTPUT
+```
+The results will be saved for inspection in a JSON file located at `$OUTPUT`.
+In the future, we hope to add a visualisation tool to assist with this.
+
 ## How to Cite
 If you use our framework in your work, please cite the following:
 
-``This research has used version X.Y.Z (software citation) of the 
+``This research has used version X.Y.Z (software citation) of the
 Causal Testing Framework (paper citation).``
 
-The paper citation should be the Causal Testing Framework [paper](https://dl.acm.org/doi/10.1145/3607184), 
+The paper citation should be the Causal Testing Framework [paper](https://dl.acm.org/doi/10.1145/3607184),
 and the software citation should contain the specific Figshare [DOI](https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516) of the version used in your work.
 
 
 
 <details>
   <summary><b>BibTeX Citations</b></summary>
-  
+
   <details>
     <summary>Paper</summary>
-    
+
     ```
     @ARTICLE{Clark_etal_2023,
     author = {Clark, Andrew G. and Foster, Michael and Prifling, Benedikt and Walkinshaw, Neil and Hierons, Robert M.
@@ -85,10 +108,10 @@ and the software citation should contain the specific Figshare [DOI](https://ord
     ```
 
   </details>
-  
+
   <details>
     <summary>Software (example)</summary>
-    
+
     ```
     @ARTICLE{Wild2023,
     author = {Foster, Michael and Clark, Andrew G. and Somers, Richard and Wild, Christopher and Allian, Farhad and Hierons, Robert M. and Wagg, David and Walkinshaw, Neil},
@@ -110,15 +133,15 @@ To contribute to our work, please ensure the following:
 1. [Fork the repository](https://help.github.com/articles/fork-a-repo/) into your own GitHub account, and [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it to your local machine.
 2. [Create a new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) in your forked repository. Give this branch an appropriate name, and create commits that describe the changes.
 3. [Push your changes](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) to your new branch in your remote fork, compare with `CausalTestingFramework/main`, and ensure any conflicts are resolved.
-4. Create a draft [pull request](https://docs.github.com/en/get-started/quickstart/hello-world#opening-a-pull-request) from your branch, and ensure you have [linked](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) it to any relevant issues in your description. 
+4. Create a draft [pull request](https://docs.github.com/en/get-started/quickstart/hello-world#opening-a-pull-request) from your branch, and ensure you have [linked](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) it to any relevant issues in your description.
 
 We use the [unittest]() module to develop our tests and the [pytest](https://pytest.org/en/latest/) framework as our test discovery, [pylint](https://pypi.org/project/pylint/) for our code analyser, and [black](https://pypi.org/project/black/) for our code formatting.
 To find the other (optional) developer dependencies, please check `pyproject.toml`.
 
 
 
-## Acknowledgements 
+## Acknowledgements
 
 The Causal Testing Framework is supported by the UK's Engineering and Physical Sciences Research Council (EPSRC),
-with the project name [CITCOM](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/T030526/1) - "_Causal Inference for Testing of Computational Models_" 
+with the project name [CITCOM](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/T030526/1) - "_Causal Inference for Testing of Computational Models_"
 under the grant EP/T030526/1.

causal_testing/__init__.py

@@ -1,11 +1,11 @@
 """
 This is the CausalTestingFramework Module
 It contains 5 subpackages:
-data_collection
-generation
-json_front
+estimation
 specification
+surrogate
 testing
+utils
 """
 
 import logging

causal_testing/__main__.py

@@ -0,0 +1,49 @@
+"""This module contains the main entrypoint functionality to the Causal Testing Framework."""
+
+import logging
+from .main import setup_logging, parse_args, CausalTestingPaths, CausalTestingFramework
+
+
+def main() -> None:
+    """
+
+    Main entry point for the Causal Testing Framework
+
+    """
+
+    # Parse arguments
+    args = parse_args()
+
+    # Setup logging
+    setup_logging(args.verbose)
+
+    # Create paths object
+    paths = CausalTestingPaths(
+        dag_path=args.dag_path,
+        data_paths=args.data_paths,
+        test_config_path=args.test_config,
+        output_path=args.output,
+    )
+
+    # Create and setup framework
+    framework = CausalTestingFramework(paths, ignore_cycles=args.ignore_cycles, query=args.query)
+    framework.setup()
+
+    # Load and run tests
+    framework.load_tests()
+
+    if args.batch_size > 0:
+        logging.info(f"Running tests in batches of size {args.batch_size}")
+        results = framework.run_tests_in_batches(batch_size=args.batch_size, silent=args.silent)
+    else:
+        logging.info("Running tests in regular mode")
+        results = framework.run_tests(silent=args.silent)
+
+    # Save results
+    framework.save_results(results)
+
+    logging.info("Causal testing completed successfully.")
+
+
+if __name__ == "__main__":
+    main()