Update README.md

Author: cthoyt

README.md

@@ -33,12 +33,94 @@
     </a>
 </p>
 
-`y0` (pronounced "why not?") is Python code for causal inferencing.
+`y0` (pronounced "why not?") is Python code for causal inference.
 
 ## 💪 Getting Started
 
-> TODO show in a very small amount of space the **MOST** useful thing your package can do.
-Make it as short as possible! You have an entire set of docs for later.
+### Representing Probability Expressions
+
+`y0` has a fully featured internal domain specific language for representing
+probability expressions:
+
+```python
+from y0.dsl import P, A, B
+
+# The probability of A given B
+expr_1 = P(A | B)
+
+# The probability of A given not B
+expr_2 = P(A | ~B)
+
+# The joint probability of A and B
+expr_3 = P(A, B)
+```
+
+It can also be used to manipulate expressions:
+
+```python
+from y0.dsl import P, A, B, Sum
+
+P(A, B).marginalize(A) == P(A, B) / Sum[A](P(A, B))
+```
+
+DSL objects can be converted into strings with `str()` and parsed back
+using `y0.parser.parse_y0()`.
+
+A full demo of the DSL can be found in this
+[Jupyter Notebook](https://github.com/y0-causal-inference/y0/blob/main/notebooks/DSL%20Demo.ipynb)
+
+### Representing Causality
+
+`y0` has a notion of acyclic directed mixed graphs built on top of
+`networkx` that can be used to model causality:
+
+```python
+from y0.graph import NxMixedGraph
+from y0.dsl import X, Y, Z1, Z2
+
+# Example from:
+#   J. Pearl and D. Mackenzie (2018)
+#   The Book of Why: The New Science of Cause and Effect.
+#   Basic Books, p. 240.
+napkin = NxMixedGraph.from_edges(
+    directed=[
+        (Z2, Z1),
+        (Z1, X),
+        (X, Y),
+    ],
+    undirected=[
+        (Z2, X),
+        (Z2, Y),
+    ],
+)
+```
+
+`y0` has many pre-written examples in `y0.examples` from Pearl, Shpitser,
+Bareinboim, and others.
+
+### do Calculus
+
+`y0` provides _actual_ implementations of many algorithms that have remained
+unimplemented for the last 15 years of publications including:
+
+| Algorithm | Reference                                                                   |
+|-----------|-----------------------------------------------------------------------------|
+| ID        | [Shpitser and Pearl, 2006](https://dl.acm.org/doi/10.5555/1597348.1597382)  |
+| IDC       | [Shpitser and Pearl, 2008](https://www.jmlr.org/papers/v9/shpitser08a.html) |
+
+Apply an algorithm to an ADMG and a causal query to generate an estimand
+represented in the DSL like:
+
+```python
+from y0.dsl import P, X, Y
+from y0.examples import napkin
+from y0.algorithm.identify import Identification, identify
+
+# TODO after ID* and IDC* are done, we'll update this interface
+query = Identification.from_expression(graph=napkin, query=P(Y @ X))
+estimand = identify(query)
+assert estimand == P(Y @ X)
+```
 
 ## ⬇️ Installation
 
@@ -55,28 +137,20 @@ The most recent code and data can be installed directly from GitHub with:
 $ pip install git+https://github.com/y0-causal-inference/y0.git
 ```
 
-To install in development mode, use the following:
-
-```bash
-$ git clone git+https://github.com/y0-causal-inference/y0.git
-$ cd y0
-$ pip install -e .
-```
-
-## ⚖️ License
-
-The code in this package is licensed under the [BSD-3-Clause
-license](https://github.com/y0-causal-inference/y0/blob/master/LICENSE).
-
-## 🙏 Contributing
+## 👐 Contributing
 
 Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See
 [CONTRIBUTING.rst](https://github.com/y0-causal-inference/y0/blob/master/CONTRIBUTING.rst) for more information on getting
 involved.
 
-## Acknowledgements
+👋 Attribution
+
+### ⚖️ License
+
+The code in this package is licensed under the [BSD-3-Clause
+license](https://github.com/y0-causal-inference/y0/blob/master/LICENSE).
 
-### Supporters
+### 🙏 Supporters
 
 This project has been supported by several organizations (in alphabetical order):
 
@@ -100,8 +174,21 @@ This package was created with [@audreyfeldroy](https://github.com/audreyfeldroy)
 
 ## 🛠️ Development
 
+<details>
+  <summary>See developer instructions</summary>
+
 The final section of the README is for if you want to get involved by making a code contribution.
 
+### Developer Installation
+
+To install in development mode, use the following:
+
+```bash
+$ git clone git+https://github.com/y0-causal-inference/y0.git
+$ cd y0
+$ pip install -e .
+```
+
 ### ❓ Testing
 
 After cloning the repository and installing `tox` with `pip install tox`, the unit tests in the `tests/` folder can be
@@ -133,3 +220,5 @@ This script does the following:
 4. Push to GitHub. You'll need to make a release going with the commit where the version was bumped.
 5. Bump the version to the next patch. If you made big changes and want to bump the version by minor, you can
    use `tox -e bumpversion minor` after.
+
+</details>