Update: corrected docs and uploaded logo

Author: f-allian

docs/source/_static/css/custom.css

@@ -0,0 +1,29 @@
+/* Custom CSS */
+
+/* Note: /*
+The CSS below will only work if 'logo_only':True in conf.py, but will require adjusting if False.
+ */
+
+.wy-side-nav-search a .logo {
+    max-width: 200px;
+    max-height: 170px;
+    height: auto;
+    width:auto;
+}
+
+
+
+.wy-nav-top a {
+    color: #131E29;  /* Change the colour of the homepage navigation title on mobiles */
+}
+
+.wy-menu-vertical p.caption {
+
+    color: #9ADBE8; /* Change the colour of captions*/
+}
+
+
+.rst-content code.literal, .highlight .s2, .highlight .s1, .rst-content tt.literal{
+    color: #440099;
+    font-weight: bold;
+}

docs/source/_static/images/CITCOM-logo.png

@@ -57,9 +57,17 @@
 # Path to generate documentation from using sphinx AutoAPI
 autoapi_dirs = [os.path.abspath(os.path.join("..", "..", "causal_testing"))]
 
+autoapi_generate_api_docs = True
+autoapi_keep_files = True
+
+# Suppress label warnings
+suppress_warnings = ['autosectionlabel.*']
+
+
 html_logo = '_static/images/CITCOM-logo.png'
 
 html_theme_options = {
     'style_nav_header_background': '#9ADBE8',  # Set the colour using CSS
     'logo_only' : True,
-}
+}
+

docs/source/conf.py

@@ -20,7 +20,7 @@ An example is provided in `examples/poisson` which contains a README with more d
 
 run_causal_tests.py
 *******************
-`examples/poisson/run_causal_tests.py <https://github.com/CITCOM-project/CausalTestingFramework/blob/main/examples/poisson/run_causal_tests.py>`_
+The `examples/poisson/example_run_causal_tests.py <https://github.com/CITCOM-project/CausalTestingFramework/blob/main/examples/poisson/example_run_causal_tests.py>`_
 contains python code written by the user to implement scenario specific features
 such as:
 
@@ -34,9 +34,9 @@ Use-case specific information is also declared here such as the paths to the rel
 
 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:
+The `examples/poisson/causal_tests.json <https://github.com/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:
 
 #. name
 #. mutations
@@ -57,17 +57,22 @@ The second method of specifying a test is to specify the test in a concrete form
 #. expected_effect
 #. skip
 
+
+Alternatively, a ``causal_tests.json`` file can be created from a ``dag.dot`` file using the ``causal_testing/specification/metamorphic_relation.py`` script as follows::
+
+  python causal_testing/specification/metamorphic_relation.py --dag_path dag.dot --output_path causal_tests.json
+
 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
+    python examples\poisson\example_run_causal_tests.py --data_path="examples\poisson\data.csv" --dag_path="examples\poisson\dag.dot" --json_path="examples\poisson\causal_tests.json
 
 A failure flag `-f` can be specified to stop the framework running if a test is failed::
 
-    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
+    python examples\poisson\example_run_causal_tests.py -f --data_path="examples\poisson\data.csv" --dag_path="examples\poisson\dag.dot" --json_path="examples\poisson\causal_tests.json
 
 There are two main outputs of this frontend, both are controlled by the logging module. Firstly outputs are printed to stdout (terminal).
 Secondly a log file is produced, by default a file called `json_frontend.log` is produced in the directory the script is called from.

docs/source/frontends/json_front_end.rst

@@ -4,11 +4,12 @@ Welcome to the Causal Testing Framework
 |status| |ci-tests| |code-cov| |docs| |python| |pypi| |doi| |license|
 
 Overview
-*******
+**********
 
 Causal testing is a :term:`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
-perspective. In this framework, we use causal :term:`directed acyclic graphs` (DAGs) to express the anticipated cause-effect
+perspective. In this framework, we use causal directed acyclic graphs (DAGs) to express the anticipated cause-effect
+relationships amongst the inputs and outputs of the system-under-test and the supporting mathematical framework to
 relationships amongst the inputs and outputs of the system-under-test and the supporting mathematical framework to
 design statistical procedures capable of making causal inferences. Each causal test case focuses on the causal effect
 of an intervention made to the system-under test. That is, a prescribed change to the input configuration of the
@@ -118,7 +119,7 @@ system-under-test that is expected to cause a change to some output(s).
    :hidden:
    :titlesonly:
 
-   /autoapi/causal_testing/index
+   /autoapi/index
 
 .. toctree::
    :hidden:
@@ -155,7 +156,7 @@ system-under-test that is expected to cause a change to some output(s).
 
 .. toctree::
    :hidden:
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Credits
 
    credits
@@ -192,4 +193,4 @@ system-under-test that is expected to cause a change to some output(s).
 
 .. |license| image:: https://img.shields.io/github/license/CITCOM-project/CausalTestingFramework
    :target: https://github.com/CITCOM-project/CausalTestingFramework
-   :alt: License
+   :alt: License

docs/source/index.rst

@@ -1,14 +1,14 @@
 Getting started
-============
+================
 
 Requirements
-------------
+---------------
 * Python >= 3.9.
 * `Microsoft Visual C++ <https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist>`_ 14.0+ (Windows only).
 
 
 Installation
------------
+-----------------
 The Causal Testing Framework can be installed through either the `Python Package Index (PyPI)`_ (recommended), or directly from source.
 
 .. _Python Package Index (PyPI): https://dl.acm.org/doi/10.1145/3607184

docs/source/installation.rst

@@ -40,4 +40,4 @@ there are a couple of requirements that should be satisfied.
 
 -  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?``
+   can answer causal questions about the scenario-under-test, such as `Does opening a window impair the viruses ability to spread?`

docs/source/modules/causal_specification.rst

@@ -42,9 +42,6 @@ We then define a number of causal test cases to apply to the scenario-under-test
 * ``mask_wearing_test = (X={precaution = None}, \Delta = {precaution = Mask}, Y = {-20% < n_infected_t5 < -10% })`` (Mask wearing is expected to result in between 10% and 20% fewer infections).
 * ``hand_washing_test = (X={precaution = None}, \Delta = {precaution = Hand Washing}, Y = {-40% < n_infected_t5 < -25%})`` (Hand washing is expected to result in between 25% and 40% fewer infections).
 
-Data Collection
----------------
-
 - To run these test cases experimentally, we need to execute both ``X`` and ``\Delta(X)`` - that is, with and without the interventions. Since the only difference between these test cases is the intervention, we can conclude that the observed difference in ``n_infected_t5`` was caused by the interventions. While this is the simplest approach, it can be extremely inefficient at scale, particularly when dealing with complex software such as computational models.
 
 - To run these test cases observationally, we need to collect *valid* observational data for the scenario-under-test. This means we can only use executions with between 20 and 30 people, a square environment of size betwen 20x20 and 40x40, and where a single person was initially infected. In addition, this data must contain executions both with and without the intervention. Next, we need to identify any sources of bias in this data and determine a procedure to counteract them. This is achieved automatically using graphical causal inference techniques that identify a set of variables that can be adjusted to obtain a causal estimate. Finally, for any categorical biasing variables, we need to make sure we have executions corresponding to each category otherwise we have a positivity violation (i.e. missing data). In the worst case, this at least guides the user to an area of the system-under-test that should be executed.

docs/source/modules/causal_tests.rst

@@ -103,5 +103,4 @@ various information. Here, we simply assert that the observed result is (on aver
    test_passes = causal_test_case.expected_causal_effect.apply(causal_test_result)
    assert test_passes, "Expected to see a positive change in y."
 
-Multiple tests can be executed at once using the test engines `test_suite <https://causal-testing-framework.readthedocs.io/en/test_suite.html>`_
-feature.
+Multiple tests can be executed at once using the test engines :doc:`Test Suite </frontends/test_suite>` feature.