feat!(documentation, overhaul): updated documentation, overhauled API

.github/workflows/update_wiki.yml

@@ -37,10 +37,6 @@ jobs:
       env:
         SEMANTIC_VERSION: 1.0.0   # not actually 1.0.0, but has no impact on wiki-building
 
-    - name: Build Pages (replace stubs)
-      run: |
-        python ./wiki/build_wiki.py
-
     - name: Push Wiki Changes
       uses: Andrew-Chen-Wang/github-wiki-action@v2
       env:

README.md

@@ -28,3 +28,12 @@
 * **Contact**: [[email protected]](mailto:[email protected])
 
 See the [wiki](https://github.com/bradendubois/do-calculus/wiki) to get started.
+
+
+## Development Status
+
+A full overhaul has been completed, and marks important milestones in my life and (consequently) this project's. Development on this project is halted until further notice, barring further changes to my own life, or necessary bug fixes and/or security fixes.
+
+## Acknowledgements
+
+This project represents approximately two years of part- and full-time work as part of an indescribably fulfilling undergraduate research project. This project was done under the supervision of Dr. Eric Neufeld from approximately Spring 2020 - Winter 2022. Without Dr. Neufeld's support, guidance, patience, expertise (and of course, funding), this project would never have been started, let alone completed. I cannot overstate my appreciation - you've changed my academic and professional path, and provided me with so many wonderful experiences and memories that I will never forget. Thanks, Eric.

archive/GitHub.md

@@ -0,0 +1,54 @@
+Instructions for installing the project from the [source code](https://github.com/bradendubois/do-calculus/wiki).
+
+## Acquiring a Copy
+
+To acquire a copy of the source code, one can [**clone the repository**](#clone), [**download a release**](#release), or use the [**GitHub CLI**](#cli).
+
+After a copy has been acquired, [install the extra dependencies](#extra-dependencies).
+
+## Clone
+
+In order to clone the repository, you must have [git](https://git-scm.com/) installed; if you are on [macOS](https://www.apple.com/ca/macos/) or [Linux](https://www.linux.org/), you almost certainly already have this installed.
+
+You can clone the repository using either the **HTTPS** or **SSH** URL.  If you do not know which to choose, or do not intend to commit to the project, use **HTTPS**.
+
+To clone with the **HTTPS** URL:
+
+```shell
+git clone https://github.com/bradendubois/do-calculus.git
+```
+
+To clone with the **SSH** URL:
+```shell
+git clone [email protected]:bradendubois/do-calculus.git
+```
+
+## Release
+
+The project's [releases page](https://github.com/bradendubois/do-calculus/releases) shows all tagged version of the project, according to [semantic versioning](https://semver.org/). Both **.zip** and **.tar.gz** archives are available. 
+
+**Releases**: [https://github.com/bradendubois/do-calculus/releases](https://github.com/bradendubois/do-calculus/releases)
+
+Releases are automatically created, tagged, and versioned using [semantic-release](https://github.com/semantic-release/semantic-release). 
+
+## CLI
+
+To clone with the [GitHub CLI](https://cli.github.com/).
+
+```shell
+gh repo clone bradendubois/do-calculus
+```
+
+## Extra Dependencies
+
+After acquiring a copy from any of the above steps:
+
+```shell
+pip install -r requirements.txt
+```
+
+The above command will install all dependencies listed in ``requirements.txt``.
+
+## Further
+
+An [API](https://en.wikipedia.org/wiki/API) is available and [[details can be found here|Do API]].

archive/Home.md

@@ -0,0 +1,5 @@
+# do-calculus wiki
+
+This wiki is *under construction*, and most documentation is still a work in progress.
+
+See the Sidebar for relevant links.

archive/Installation.md

@@ -0,0 +1,20 @@
+How to install and set up the software.
+
+## Table of Contents
+
+* [Requirements](#requirements)
+* [Options](#options)
+
+## Requirements
+
+Setup requirements for the project are:
+- **[Python 3.8+](https://www.python.org/)**
+- [**pip**](https://pip.pypa.io/en/stable/) is used to install required packages.
+
+**Note**: `pip` will already be installed with any installation of **Python 3.4+**.
+
+## Options
+
+There are **two** main ways to install the package:
+- [[Install from PyPI|PyPI]]
+- [[Install from source|GitHub]]

archive/PyPI.md

@@ -0,0 +1,29 @@
+Instructions for installing the package through its [PyPI distribution](https://pypi.org/project/do-calculus/).
+
+## PyPI Package
+
+The package is published on [PyPI](https://pypi.org/) as [do-calculus](https://pypi.org/project/do-calculus/).
+
+To install from [PyPI](https://pypi.org/) as a package:
+
+```shell
+pip install do-calculus
+```
+
+## Upgrade
+
+To upgrade a local installation of the project (such as when a new version is released), add the ``-U`` flag:
+
+```shell
+pip install -U do-calculus
+```
+
+## PyPI Release Cycle
+
+By default, a new package will be automatically uploaded to PyPI on a new [semantically-versioned](https://semver.org/) [release](https://github.com/bradendubois/do-calculus/releases) which is automatically handled by [semantic-release](https://github.com/semantic-release/semantic-release) in a [workflow](https://github.com/bradendubois/do-calculus/actions).
+
+Releases are generated by [semantic-release](https://github.com/semantic-release/semantic-release) on pushes or merges to the [main](https://github.com/bradendubois/do-calculus/tree/main) and [beta](https://github.com/bradendubois/do-calculus/tree/beta) branches of the project.
+
+*Only* releases produced from [main](https://github.com/bradendubois/do-calculus/tree/main) will be uploaded to the [PyPI](https://pypi.org/project/do-calculus/) distribution. All development on the project will eventually work its way up to the [PyPI](https://pypi.org/project/do-calculus/) distribution, though it may lag behind [GitHub releases](https://github.com/bradendubois/do-calculus/releases) by anywhere between minutes to a few days.
+
+See the [[API|Do API]] page for importing and using the package once installed.

archive/README.md

@@ -0,0 +1,5 @@
+# Archive
+
+Contained here is some old code that built a (now-outdated) wiki that I don't have the heart to delete.
+
+Don't rely on it expecting accurate information.

archive/_Sidebar.md

@@ -0,0 +1,34 @@
+### [[Home]]
+
+### [[Installation]]
+* [[PyPI]]
+* [[GitHub]]
+
+### [[Resources]]
+* [[Definitions]]
+* [[Markovian Models]]
+* [[Configuration]]
+* [[Literature]]
+
+### [[Do API]]
+* [[Do.\_\_init\_\_|\_\_init\_\_]]
+* [[Do.load_model|Loading a Model]]
+* [[Do.p|Probability Queries]]
+* [[Do.joint_distribution_table|Joint Distribution Table]]
+* [[Do.backdoor_paths|Backdoor Paths]]
+* [[Do.standard_paths|Standard Paths]]
+* [[Do.deconfounding_sets|Deconfounding Sets]]
+* [[Do.independent|Conditional Independence]]
+* [[Do.roots|Roots]]
+* [[Do.sinks|Sinks]]
+* [[Do.parents|Parents]]
+* [[Do.children|Children]]
+* [[Do.ancestors|Ancestors]]
+* [[Do.descendants|Descendants]]
+* [[Do.topology|Topology]]
+* [[Do.topology_position|Topology]]
+* [[Do.set_print_result|Output]]
+* [[Do.set_print_detail|Output]]
+* [[Do.set_logging|Output]]
+* [[Do.set_log_fd|Output]]
+* [[Exceptions]]

do/identification/API.py

@@ -5,7 +5,7 @@
 from ..core.Variables import Intervention, Outcome
 
 from .LatentGraph import latent_transform
-from .Identification import Identification
+from .Identification import Identification, simplify_expression
 from .PExpression import PExpression, TemplateExpression
 
 
@@ -62,7 +62,6 @@ def _process(current: Union[PExpression, TemplateExpression], known: Mapping[str
                 return t
 
         result = _process(expression, {v.name: v.outcome for v in y} | {v.name: v.outcome for v in x})
-
         return (result, expression.proof()) if include_proof else result
 
     def proof(self, y: Set[Outcome], x: Set[Intervention], model: Model) -> str:

do/identification/LatentGraph.py

@@ -179,29 +179,29 @@ def latent_transform(g: Graph, u: Set[str]):
         reduction = False
 
         remove = set()
-        for u in Un:
+        for un in Un:
 
-            parents = [edge[0] for edge in E if edge[1] == u]       # Edges : parent -> u
-            children = [edge[1] for edge in E if edge[0] == u]      # Edges : u -> child
+            parents = [edge[0] for edge in E if edge[1] == un]       # Edges : parent -> u
+            children = [edge[1] for edge in E if edge[0] == un]      # Edges : u -> child
 
             # All parents are unobservable, all children are observable, at least one parent
             if all(x in u for x in parents) and len(parents) > 0 and all(x not in u for x in children):
                 reduction = True
 
                 # Remove edges from parents to u
                 for parent in parents:
-                    E.remove((parent, u))
+                    E.remove((parent, un))
 
                 # Remove edges from u to children
                 for child in children:
-                    E.remove((u, child))
+                    E.remove((un, child))
 
                 # Replace with edge from edge parent to each child
                 for cr in product(parents, children):
                     E.add((cr[0], cr[1]))
 
                 # U can be removed entirely from graph
-                remove.add(u)
+                remove.add(un)
 
         V -= remove
         Un -= remove
@@ -229,4 +229,5 @@ def latent_transform(g: Graph, u: Set[str]):
             a, b = child_edges[i], child_edges[(i + 1) % len(child_edges)]
             E_Bidirected.add((a[1], b[1]))
 
+    print(V, u)
     return LatentGraph(V, E, E_Bidirected, [x for x in g.topology_sort() if x in V - u])

examples/2-backdoor-paths/deconfound.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from do import API
+
+api = API()
+
+file = Path("pearl-3.4.yml")
+model = api.instantiate_model(file)
+
+backdoors = api.backdoors({"Xi"}, {"Xj"}, model.graph())
+assert len(backdoors) > 0, "No backdoor paths detected!"
+assert not api.blocks({"Xi"}, {"Xj"}, model.graph(), set()), "This should not block all paths!" 
+
+for path in backdoors:
+    print("Path:", path)
+
+backdoors = api.backdoors({"Xi"}, {"Xj"}, model.graph(), {"X1", "X4"})
+assert len(backdoors) == 0, "Expected this to block!"
+assert api.blocks({"Xi"}, {"Xj"}, model.graph(), {"X1", "X4"}), "This should block!"

examples/2-backdoor-paths/pearl-3.4.yml

@@ -0,0 +1,116 @@
+name: 'Pearl: Figure 3.4'
+endogenous:
+  X1:
+    outcomes:
+    - x1
+    - ~x1
+    parents: []
+    table: [
+      [x1, 0.4],
+      [~x1, 0.6]
+    ]
+  X2:
+    outcomes:
+    - x2
+    - ~x2
+    parents: []
+    table: [
+      [x2, 0.15],
+      [~x2, 0.85]
+    ]
+  X3:
+    outcomes:
+    - x3
+    - ~x3
+    parents:
+    - X1
+    table: [
+      [x3, x1, 0.1],
+      [x3, ~x1, 0.3],
+      [~x3, x1, 0.9],
+      [~x3, ~x1, 0.7]
+    ]
+  X4:
+    outcomes:
+    - x4
+    - ~x4
+    parents:
+    - X1
+    - X2
+    table: [
+      [x4, x1, x2, 0.7],
+      [x4, x1, ~x2, 0.9],
+      [x4, ~x1, x2, 0.55],
+      [x4, ~x1, ~x2, 0.15],
+      [~x4, x1, x2, 0.3],
+      [~x4, x1, ~x2, 0.1],
+      [~x4, ~x1, x2, 0.45],
+      [~x4, ~x1, ~x2, 0.85]
+   ]
+  X5:
+    outcomes:
+    - x5
+    - ~x5
+    parents:
+    - X2
+    table: [
+      [x5, x2, 0.8],
+      [x5, ~x2, 0.25],
+      [~x5, x2, 0.2],
+      [~x5, ~x2, 0.75]
+    ]
+  X6:
+    outcomes:
+    - x6
+    - ~x6
+    parents:
+    - Xi
+    table: [
+      [x6, xi, 0.9],
+      [x6, ~xi, 0.25],
+      [~x6, xi, 0.1],
+      [~x6, ~xi, 0.75]
+   ]
+  Xi:
+    outcomes:
+    - xi
+    - ~xi
+    parents:
+    - X3
+    - X4
+    table: [
+      [xi, x3, x4, 0.5],
+      [xi, x3, ~x4, 0.65],
+      [xi, ~x3, x4, 0.1],
+      [xi, ~x3, ~x4, 0.25],
+      [~xi, x3, x4, 0.5],
+      [~xi, x3, ~x4, 0.35],
+      [~xi, ~x3, x4, 0.9],
+      [~xi, ~x3, ~x4, 0.75]
+    ]
+  Xj:
+    outcomes:
+    - xj
+    - ~xj
+    parents:
+    - X6
+    - X4
+    - X5
+    table: [
+      [xj, x6, x4, x5, 0.0],
+      [xj, x6, x4, ~x5, 0.25],
+      [xj, x6, ~x4, x5, 0.7],
+      [xj, x6, ~x4, ~x5, 0.45],
+      [xj, ~x6, x4, x5, 0.15],
+      [xj, ~x6, x4, ~x5, 0.8],
+      [xj, ~x6, ~x4, x5, 0.95],
+      [xj, ~x6, ~x4, ~x5, 0.05],
+      [~xj, x6, x4, x5, 1.0],
+      [~xj, x6, x4, ~x5, 0.75],
+      [~xj, x6, ~x4, x5, 0.3],
+      [~xj, x6, ~x4, ~x5, 0.55],
+      [~xj, ~x6, x4, x5, 0.85],
+      [~xj, ~x6, x4, ~x5, 0.2],
+      [~xj, ~x6, ~x4, x5, 0.05],
+      [~xj, ~x6, ~x4, ~x5, 0.95]
+    ]