Skip to content

Commit 42d133f

Browse files
authored
Merge branch 'main' into dafni-branch
2 parents bbafb24 + b82241f commit 42d133f

24 files changed

+524
-193
lines changed
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Continuous Integration Tests Draft PR (pytest)
2+
# This duplicate ci workflow is required so the badge in the README.md is not effected by draft PRs
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build:
10+
if: github.event.pull_request.draft == true
11+
name: Ex1 (${{ matrix.python-version }}, ${{ matrix.os }})
12+
runs-on: ${{ matrix.os }}
13+
strategy:
14+
matrix:
15+
os: ["ubuntu-latest", "windows-latest", "macos-latest"]
16+
python-version: ["3.9"]
17+
steps:
18+
- uses: actions/checkout@v2
19+
- name: Set up Python using Miniconda
20+
uses: conda-incubator/setup-miniconda@v2
21+
with:
22+
auto-update-conda: true
23+
python-version: ${{ matrix.python-version }}
24+
- name: Install package and dependencies
25+
run: |
26+
python --version
27+
pip install -e .
28+
pip install -e .[test]
29+
pip install pytest pytest-cov
30+
shell: bash -l {0}
31+
- name: Test with pytest
32+
run: |
33+
pytest --cov=causal_testing --cov-report=xml
34+
shell: bash -l {0}
35+
- name: "Upload coverage to Codecov"
36+
uses: codecov/codecov-action@v2
37+
with:
38+
fail_ci_if_error: true
39+
token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/ci-tests.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,15 @@ on:
44
pull_request:
55
branches:
66
- main
7+
types:
8+
- opened
9+
- synchronize
10+
- reopened
11+
- ready_for_review
712

813
jobs:
914
build:
15+
if: github.event.pull_request.draft == false # Filter out draft PRs
1016
name: Ex1 (${{ matrix.python-version }}, ${{ matrix.os }})
1117
runs-on: ${{ matrix.os }}
1218
strategy:

.github/workflows/figshare.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,5 +24,5 @@ jobs:
2424
with:
2525
FIGSHARE_TOKEN: ${{ secrets.FIGSHARE_TOKEN }}
2626
FIGSHARE_ENDPOINT: 'https://api.figshare.com/v2'
27-
FIGSHARE_ARTICLE_ID: <<24427516>>
28-
DATA_DIR: 'data'
27+
FIGSHARE_ARTICLE_ID: 24427516
28+
DATA_DIR: 'data'

README.md

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
1-
# Causal Testing Framework: A Causal Inference-Driven Software Testing Framework
1+
# Causal Testing Framework
2+
### A Causal Inference-Driven Software Testing Framework
23

3-
![example workflow](https://github.com/CITCOM-project/CausalTestingFramework/actions/workflows/ci-tests.yaml/badge.svg) [![codecov](https://codecov.io/gh/CITCOM-project/CausalTestingFramework/branch/main/graph/badge.svg?token=04ijFVrb4a)](https://codecov.io/gh/CITCOM-project/CausalTestingFramework) [![Documentation Status](https://readthedocs.org/projects/causal-testing-framework/badge/?version=latest)](https://causal-testing-framework.readthedocs.io/en/latest/?badge=latest)
4+
5+
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
6+
![example workflow](https://github.com/CITCOM-project/CausalTestingFramework/actions/workflows/ci-tests.yaml/badge.svg)
7+
[![codecov](https://codecov.io/gh/CITCOM-project/CausalTestingFramework/branch/main/graph/badge.svg?token=04ijFVrb4a)](https://codecov.io/gh/CITCOM-project/CausalTestingFramework)
8+
[![Documentation Status](https://readthedocs.org/projects/causal-testing-framework/badge/?version=latest)](https://causal-testing-framework.readthedocs.io/en/latest/?badge=latest)
9+
![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)
10+
![PyPI - Version](https://img.shields.io/pypi/v/causal-testing-framework)
11+
[![DOI](https://t.ly/FCT1B)](https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516)
12+
![GitHub License](https://img.shields.io/github/license/CITCOM-project/CausalTestingFramework)
413

514
Causal testing is a causal inference-driven framework for functional black-box testing. This framework utilises
615
graphical causal inference (CI) techniques for the specification and functional testing of software from a black-box
@@ -12,10 +21,9 @@ system-under-test that is expected to cause a change to some output(s).
1221

1322
![Causal Testing Workflow](images/workflow.png)
1423

15-
1624
## Installation
1725

18-
See the readthedocs site for [installation
26+
See the Read the Docs site for [installation
1927
instructions](https://causal-testing-framework.readthedocs.io/en/latest/installation.html).
2028

2129
## Documentation

docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The documentation is accessible on [Read the Docs](https://causal-testing-framew
66

77
## Locally building
88
To build locally, the requirements in `docs/source/requirements.txt` will need to be installed.
9-
9+
[README.md](README.md)
1010
Within `docs/`, run `make html` to create or update the .html files in the `docs/build` directory.
1111

1212
Running `make clean` will clean the `build` folder.

docs/source/_static/css/custom.css

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/* Custom CSS */
2+
3+
/* Note: /*
4+
The CSS below will only work if 'logo_only':True in conf.py, but will require adjusting if False.
5+
*/
6+
7+
.wy-side-nav-search a .logo {
8+
max-width: 200px;
9+
max-height: 170px;
10+
height: auto;
11+
width:auto;
12+
}
13+
14+
15+
16+
.wy-nav-top a {
17+
color: #131E29; /* Change the colour of the homepage navigation title on mobiles */
18+
}
19+
20+
.wy-menu-vertical p.caption {
21+
22+
color: #9ADBE8; /* Change the colour of captions*/
23+
}
24+
25+
26+
.rst-content code.literal, .highlight .s2, .highlight .s1, .rst-content tt.literal{
27+
color: #440099;
28+
font-weight: bold;
29+
}
19.8 KB
Loading

docs/source/conf.py

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,17 @@
1212
#
1313
import os
1414
import sys
15+
from datetime import date
1516

1617
# Include root directory of project
1718
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
1819

1920

2021
# -- Project information -----------------------------------------------------
2122

22-
project = "Causal Testing"
23-
copyright = "2021, Andrew Clark, Michael Foster, Neil Walkinshaw, Rob Hierons, Bob Turner"
24-
author = "Andrew Clark, Michael Foster, Neil Walkinshaw, Rob Hierons, Bob Turner"
23+
project = "Causal Testing Framework"
24+
copyright = f"{date.today().year}, The CITCOM Team"
25+
author = "Andrew Clark, Michael Foster, Neil Walkinshaw, Rob Hierons, Bob Turner, Christopher Wild, Farhad Allian"
2526

2627

2728
# -- General configuration ---------------------------------------------------
@@ -49,7 +50,24 @@
4950
# Add any paths that contain custom static files (such as style sheets) here,
5051
# relative to this directory. They are copied after the builtin static files,
5152
# so a file named "default.css" will overwrite the builtin "default.css".
52-
# html_static_path = ['_static']
53+
html_static_path = ['_static']
54+
55+
html_css_files = ['css/custom.css']
5356

5457
# Path to generate documentation from using sphinx AutoAPI
5558
autoapi_dirs = [os.path.abspath(os.path.join("..", "..", "causal_testing"))]
59+
60+
autoapi_generate_api_docs = True
61+
autoapi_keep_files = True
62+
63+
# Suppress label warnings
64+
suppress_warnings = ['autosectionlabel.*']
65+
66+
67+
html_logo = '_static/images/CITCOM-logo.png'
68+
69+
html_theme_options = {
70+
'style_nav_header_background': '#9ADBE8', # Set the colour using CSS
71+
'logo_only' : True,
72+
}
73+

docs/source/credits.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Acknowledging CITCOM
2+
*********************
3+
4+
If you use the Causal Testing Framework for your work, please add the following line within your paper to acknowledge
5+
our work:
6+
7+
.. admonition:: Important
8+
:class: important
9+
10+
This research has used version X.Y.Z (software citation) of the Causal Testing Framework (paper citation).
11+
12+
The paper citation should be the Causal Testing Framework paper_, and the software citation should be the specific
13+
Figshare DOI_ for the version used in your research.
14+
15+
.. _paper: https://dl.acm.org/doi/10.1145/3607184
16+
.. _DOI: https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516
17+
18+
.. code-block:: latex
19+
20+
@ARTICLE{Clark_etal_2023,
21+
author = {Clark, Andrew G. and Foster, Michael and Prifling, Benedikt and Walkinshaw, Neil and Hierons, Robert M.
22+
and Schmidt, Volker and Turner, Robert D.},
23+
title = {Testing Causality in Scientific Modelling Software},
24+
year = {2023},
25+
publisher = {Association for Computing Machinery},
26+
url = {https://doi.org/10.1145/3607184},
27+
doi = {10.1145/3607184},
28+
journal = {ACM Trans. Softw. Eng. Methodol.},
29+
month = {jul},
30+
keywords = {Software Testing, Causal Testing, Causal Inference}
31+
}
32+
33+
The CITCOM Team
34+
***************
35+
36+
- Andrew G. Clark, Michael Foster, Richard Somers, Christopher Wild, Farhad Allian, Robert M. Hierons, Nick Latimer, David Wagg, Neil Walkinshaw.
37+

docs/source/description.rst

Lines changed: 12 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,28 @@
1-
Framework Overview
1+
Background
22
=====================================
33

4-
CTF Components
5-
--------------
4+
The Causal Testing Framework consists of 3 main components: 1) Causal Specification, 2) Causal Test Case and 3) Data Collection.
65

76
#.
8-
:doc:`Causal Specification <../modules/causal_specification>`\ : Before we can test software, we need to obtain an
9-
understanding of how it should behave in a particular use-case scenario. In addition, to apply graphical CI
7+
:doc:`Causal Specification <../modules/causal_specification>`\ : To apply graphical CI
108
techniques for testing, we need a causal DAG which depicts causal relationships amongst inputs and outputs. To
119
collect this information, users must create a *causal specification*. This comprises a set of scenarios which place
1210
constraints over input variables that capture the use-case of interest, a causal DAG corresponding to this scenario,
1311
and a series of high-level functional requirements that the user wishes to test. In causal testing, these
1412
requirements should describe how the model should respond to interventions (changes made to the input configuration).
1513

14+
15+
1616
#.
1717
:doc:`Causal Tests <../modules/causal_tests>`\ : With a causal specification in hand, we can now go about designing
1818
a series of test cases that interrogate the causal relationships of interest in the scenario-under-test. Informally,
19-
a causal test case is a triple (M, X, Delta, Y), where M is the modelling scenario, X is an input configuration,
20-
Delta is an intervention which should be applied to X, and Y is the expected *causal effect* of that intervention on
21-
some output of interest. Therefore, a causal test case states the expected causal effect (Y) of a particular
22-
intervention (Delta) made to an input configuration (X). For each scenario, the user should create a suite of causal
19+
a causal test case is a triple ``(M, X, Delta, Y)``, where ``M`` is the modelling scenario, ``X`` is an input configuration,
20+
``Delta`` is an intervention which should be applied to ``X``, and ``Y`` is the expected *causal effect* of that intervention on
21+
some output of interest. Therefore, a causal test case states the expected causal effect (``Y``) of a particular
22+
intervention (``Delta``) made to an input configuration (``X``). For each scenario, the user should create a suite of causal
2323
tests. Once a causal test case has been defined, it is executed as follows:
2424

25-
26-
#. Using the causal DAG, identify an estimand for the effect of the intervention on the output of interest. That is,
25+
a. Using the causal DAG, identify an estimand for the effect of the intervention on the output of interest. That is,
2726
a statistical procedure capable of estimating the causal effect of the intervention on the output.
2827
#. Collect the data to which the statistical procedure will be applied (see Data collection below).
2928
#. Apply a statistical model (e.g. linear regression or causal forest) to the data to obtain a point estimate for
@@ -35,6 +34,8 @@ CTF Components
3534
test should pass or fail based on the results. In the simplest case, this takes the form of an assertion which
3635
compares the point estimate to the expected causal effect specified in the causal test case.
3736

37+
38+
3839
#.
3940
:doc:`Data Collection <../modules/data_collector>`\ : Data for the system-under-test can be collected in two
4041
ways: experimentally or observationally. The former involves executing the system-under-test under controlled
@@ -48,22 +49,3 @@ CTF Components
4849
provide instructions for an execution that will fill the gap (future work).
4950

5051
For more information on each of these steps, follow the link to their respective documentation.
51-
52-
Causal Inference Terminology
53-
----------------------------
54-
55-
Here are some explanations for the causal inference terminology used above.
56-
57-
58-
* Causal inference (CI) is a family of statistical techniques designed to quantify and establish **causal**
59-
relationships in data. In contrast to purely statistical techniques that are driven by associations in data, CI
60-
incorporates knowledge about the data-generating mechanisms behind relationships in data to derive causal conclusions.
61-
* One of the key advantages of CI is that it is possible to answer causal questions using **observational data**. That
62-
is, data which has been passively observed rather than collected from an experiment and, therefore, may contain all
63-
kinds of bias. In a testing context, we would like to leverage this advantage to test causal relationships in software
64-
without having to run costly experiments.
65-
* There are many forms of CI techniques with slightly different aims, but in this framework we focus on graphical CI
66-
techniques that use directed acyclic graphs to obtain causal estimates. These approaches used a causal DAG to explain
67-
the causal relationships that exist in data and, based on the structure of this graph, design statistical experiments
68-
capable of estimating the causal effect of a particular intervention or action, such as taking a drug or changing the
69-
value of an input variable.

0 commit comments

Comments
 (0)