Dev/677 documentation

[ras44]

Proposed changes

This is a first pass at consolidating much of the README.md into docs/*.rst. This moves all of the existing examples into the docs, creating a single source of truth via the notebooks in docs/examples/ and the code-snippets included in the *.rst files.

Future possibilities:

• include selected screenshots in README.md to add visual examples of output
• add platform-specific links and/or very small code snippets to installation section: ie. pip install causalml
• revise the References section (consolidate literature references with docs/)
• edit docs/examples.rst to order/organize topics from intro to advanced
• further develop docs/methodology.rst to include use case examples
• add a developer section to docs/installation.rst
• add consistent format for each algorithm, like:
  • Uplift Modeling: Meta-Learners
    • Introduction
    • Formulation
    • Use Cases
    • Examples
    • FAQ

Disclaimer: This presents a significant modification to the README.md so care should be taken in considering how best to edit before eventually rolling out so as to maintain a smooth user experience. This is simply a first pass and feedback is welcome.

Types of changes

What types of changes does your code introduce to CausalML?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• I have read the CONTRIBUTING doc
• I have signed the CLA
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)
• Any dependent changes have been merged and published in downstream modules

Further comments

[t-tte]

Thanks for the contribution. I would suggest removing the "Measuring causal effects" section as the main focus of the library is in measuring heterogeneous treatment effects in randomized experiments. There's a widespread misunderstanding that CausalML and adjacent tools are helpful for observational studies when they are not. I think that explaining the various observational causal inference methods is too big of a task to undertake in this documentation, and that we should simply refer users to one of the primary sources.

[ras44]

thanks @t-tte That brings to mind a 2021 paper from Abadie cautioning on appropriate usage, and also your "Iceberg" metaphor on the key role of assumptions re unobserved confounders in causal inference. I wonder if in addition to removing the "Measuring causal effects" section, we should include any guidance for caution/avoidance when applying CausalML to purely observational data?

[t-tte]

I think it's a good idea given how frequently it is asked. I'm currently working on a brief intro and will make a PR for it soon.