From 27602c435222cc8617d5005b6784d4f1c737201c Mon Sep 17 00:00:00 2001 From: Jeong-Yoon Lee Date: Thu, 24 Aug 2023 09:36:37 -0700 Subject: [PATCH] update docs/*.rst to reflect #637 --- docs/causalml.rst | 10 ++--- docs/changelog.rst | 52 ++++++++++----------- docs/installation.rst | 102 +++++++++++++++++++++++++++++------------- 3 files changed, 101 insertions(+), 63 deletions(-) diff --git a/docs/causalml.rst b/docs/causalml.rst index f5c66c99..5ea378c8 100644 --- a/docs/causalml.rst +++ b/docs/causalml.rst @@ -23,7 +23,7 @@ causalml.inference.meta module :show-inheritance: causalml.inference.iv module ------------------------------- +---------------------------- .. automodule:: causalml.inference.iv :members: @@ -32,7 +32,7 @@ causalml.inference.iv module :show-inheritance: causalml.inference.nn module ------------------------------- +---------------------------- .. automodule:: causalml.inference.nn :members: @@ -41,7 +41,7 @@ causalml.inference.nn module :show-inheritance: causalml.inference.tf module ------------------------------- +---------------------------- .. automodule:: causalml.inference.tf :members: @@ -93,7 +93,7 @@ causalml.metrics module :show-inheritance: causalml.feature_selection module ------------------------ +--------------------------------- .. automodule:: causalml.feature_selection :members: @@ -102,7 +102,7 @@ causalml.feature_selection module :show-inheritance: causalml.features module --------------------------- +------------------------ .. automodule:: causalml.features :members: diff --git a/docs/changelog.rst b/docs/changelog.rst index 858a8128..fe8f9ab8 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,27 +4,27 @@ Changelog ========= 0.14.0 (July 2023) ------------------ +------------------ - CausalML surpassed `2MM downloads `_ on PyPI and `4,100 stars `_ on GitHub. Thanks for choosing CausalML and supporting us on GitHub. - We have 7 new contributors: @darthtrevino, @ras44, @AbhishekVermaDH, @joel-mcmurry, @AlxClt, @kklein, and @volico. Thanks for your contributions! Updates -~~~~~~~~~~~~~ +~~~~~~~ - Fix the readthedocs build failure by @jeongyoonlee in https://github.com/uber/causalml/pull/545 -- Add pyproject.toml with basic build dependencies for PEP518 compliance by @darthtrevino in https://github.com/uber/causalml/pull/553 -- bump numpy from 1.20.3 to 1.23.2 in environment-py38.yml #338 by @ras44 in https://github.com/uber/causalml/pull/550 +- Add ``pyproject.toml`` with basic build dependencies for PEP518 compliance by @darthtrevino in https://github.com/uber/causalml/pull/553 +- bump ``numpy`` from 1.20.3 to 1.23.2 in ``environment-py38.yml`` #338 by @ras44 in https://github.com/uber/causalml/pull/550 - CausalTree split criterions fix and fit optimization by @alexander-pv in https://github.com/uber/causalml/pull/557 - fixing math notations for proper rendering by @AbhishekVermaDH in https://github.com/uber/causalml/pull/558 -- Update methodology.rst by @joel-mcmurry in https://github.com/uber/causalml/pull/568 -- Causal trees bootstrapping and `max_leaf_nodes` fixes with minor update by @alexander-pv in https://github.com/uber/causalml/pull/583 +- Update ``methodology.rst`` by @joel-mcmurry in https://github.com/uber/causalml/pull/568 +- Causal trees bootstrapping and ``max_leaf_nodes`` fixes with minor update by @alexander-pv in https://github.com/uber/causalml/pull/583 - Fix #596 by @AlxClt in https://github.com/uber/causalml/pull/597 -- Add **kwargs to Explainer.plot_shap_values() by @jeongyoonlee in https://github.com/uber/causalml/pull/603 +- Add ``**kwargs`` to ``Explainer.plot_shap_values()`` by @jeongyoonlee in https://github.com/uber/causalml/pull/603 - Make the Adam optimization optional and learning rate/epochs configurable in DragonNet by @jeongyoonlee in https://github.com/uber/causalml/pull/604 - Fix bug in variance calculation in drivlearner. by @huigangchen in https://github.com/uber/causalml/pull/606 - Bug Fix in Dragonnet: Adam parameter name lr depreciation by @huigangchen in https://github.com/uber/causalml/pull/617 -- Fix AttributeError in builds with numpy>=1.24 and pandas>=2.0 by @jeongyoonlee in https://github.com/uber/causalml/pull/631 -- Pass on **kwargs in `plot_shap_values` of base meta leaner by @kklein in https://github.com/uber/causalml/pull/627 -- Bump scipy from 1.4.1 to 1.10.0 by @dependabot in https://github.com/uber/causalml/pull/629 +- Fix AttributeError in builds with ``numpy>=1.24`` and ``pandas>=2.0`` by @jeongyoonlee in https://github.com/uber/causalml/pull/631 +- Pass on ``**kwargs`` in ``plot_shap_values`` of base meta leaner by @kklein in https://github.com/uber/causalml/pull/627 +- Bump ``scipy`` from 1.4.1 to 1.10.0 by @dependabot in https://github.com/uber/causalml/pull/629 - Feature/ttest criterion by @volico in https://github.com/uber/causalml/pull/570 - Added Interaction Tree (IT), Causal Inference Tree (CIT), and Invariant DDP (IDDP) by @jroessler in https://github.com/uber/causalml/pull/562 - Causal trees option to return counterfactual outcomes by @alexander-pv in https://github.com/uber/causalml/pull/623 @@ -48,21 +48,21 @@ New contributors - We dropped the support for Python 3.6 and removed its test workflow. Updates -~~~~~~~~~~~~~ -- Fix typo `(% -> $)` by @saiwing-yeung in https://github.com/uber/causalml/pull/488 +~~~~~~~ +- Fix typo ``(% -> $)`` by @saiwing-yeung in https://github.com/uber/causalml/pull/488 - Add function for calculating PNS bounds by @t-tte in https://github.com/uber/causalml/pull/482 - Fix hard coding bug by @t-tte in https://github.com/uber/causalml/pull/492 -- Update README of `conda` install and instruction of maintain in conda-forge by @ppstacy in https://github.com/uber/causalml/pull/485 -- Update `examples.rst` by @lixuan12315 in https://github.com/uber/causalml/pull/496 -- Fix incorrect `effect_learner_objective` in `XGBRRegressor` by @jeongyoonlee in https://github.com/uber/causalml/pull/504 -- Fix Filter F doesn't work with latest `statsmodels`' F test f-value format by @paullo0106 in https://github.com/uber/causalml/pull/505 -- Exclude tests in `setup.py` by @aldenrogers in https://github.com/uber/causalml/pull/508 +- Update README of ``conda`` install and instruction of maintain in ``conda-forge`` by @ppstacy in https://github.com/uber/causalml/pull/485 +- Update ``examples.rst`` by @lixuan12315 in https://github.com/uber/causalml/pull/496 +- Fix incorrect ``effect_learner_objective`` in ``XGBRRegressor`` by @jeongyoonlee in https://github.com/uber/causalml/pull/504 +- Fix Filter F doesn't work with latest ``statsmodels``' F test f-value format by @paullo0106 in https://github.com/uber/causalml/pull/505 +- Exclude tests in ``setup.py`` by @aldenrogers in https://github.com/uber/causalml/pull/508 - Enabling higher orders feature importance for F filter and LR filter by @zhenyuz0500 in https://github.com/uber/causalml/pull/509 - Ate pretrain 0506 by @vincewu51 in https://github.com/uber/causalml/pull/511 -- Update `methodology.rst` by @AlkanSte in https://github.com/uber/causalml/pull/518 +- Update ``methodology.rst`` by @AlkanSte in https://github.com/uber/causalml/pull/518 - Fix the bug of incorrect result in qini for multiple models by @enzoliao in https://github.com/uber/causalml/pull/520 -- Test `get_qini()` by @enzoliao in https://github.com/uber/causalml/pull/523 -- Fixed typo in `uplift_trees_with_synthetic_data.ipynb` by @jroessler in https://github.com/uber/causalml/pull/531 +- Test ``get_qini()`` by @enzoliao in https://github.com/uber/causalml/pull/523 +- Fixed typo in ``uplift_trees_with_synthetic_data.ipynb`` by @jroessler in https://github.com/uber/causalml/pull/531 - Remove Python 3.6 test from workflows by @jeongyoonlee in https://github.com/uber/causalml/pull/535 - Causal trees update by @alexander-pv in https://github.com/uber/causalml/pull/522 - Causal trees interpretation example by @alexander-pv in https://github.com/uber/causalml/pull/536 @@ -73,7 +73,7 @@ Updates This patch is to release a version without the constraint for Shap to be abled to use for Conda. Updates -~~~~~~~~~~~~~ +~~~~~~~ - `#483 `_ by @ppstacy: Modify the requirement version of Shap @@ -82,7 +82,7 @@ Updates This patch includes three updates by @tonkolviktor and @heiderich as follows. We also start using `black `_, a Python formatter. Please check out the updated `contribution guideline `_ to learn how to use it. Updates -~~~~~~~~~~~~~ +~~~~~~~ - `#473 `_ by @tonkolviktor: Open up the scipy dependency version - `#476 `_ by @heiderich: Use preferred backend for joblib instead of hard-coding it - `#477 `_ by @heiderich: Allow parallel prediction for UpliftRandomForestClassifier and make the joblib's preferred backend configurable @@ -93,7 +93,7 @@ Updates This patch includes two bug fixes for UpliftRandomForestClassifier as follows: Updates -~~~~~~~~~~~~~ +~~~~~~~ - `#462 `_ by @paullo0106: Use the correct treatment_idx for fillTree() when applying validation data set - `#468 `_ by @jeongyoonlee: Switch the joblib backend for UpliftRandomForestClassifier to threading to avoid memory copy across trees @@ -107,7 +107,7 @@ Updates - Our team gave talks at `2021 Conference on Digital Experimentation @ MIT (CODE@MIT) `_, `Causal Data Science Meeting 2021 `_, and `KDD 2021 Tutorials `_ on CausalML introduction and applications. Please take a look if you missed them! Full list of publications and talks can be found here. Updates -~~~~~~~~~~~~~ +~~~~~~~ - Update documentation on Instrument Variable methods @huigangchen (`#447 `_) - Add benchmark simulation studies example notebook by @t-tte (`#443 `_) - Add sample_weight support for R-learner by @paullo0106 (`#425 `_) @@ -122,7 +122,7 @@ Updates 0.11.0 (2021-07-28) ------------------- +------------------- - CausalML surpassed `2K stars `_! - We have 3 new community contributors, Jannik (`@jroessler `_), Mohamed (`@ibraaaa `_), and Leo (`@lleiou `_). Thanks for the contribution! @@ -148,7 +148,7 @@ Minor Updates 0.10.0 (2021-02-18) ------------------- +------------------- - CausalML surpassed `235,000 downloads `_! - We have 5 new community contributors, Suraj (`@surajiyer `_), Harsh (`@HarshCasper `_), Manoj (`@manojbalaji1 `_), Matthew (`@maccam912 `_) and Václav (`@vaclavbelak `_). Thanks for the contribution! diff --git a/docs/installation.rst b/docs/installation.rst index d5b88494..8be75293 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,58 +2,96 @@ Installation ============ -Installation with ``conda`` is recommended. ``conda`` environment files for Python 3.6, 3.7, 3.8 and 3.9 are available in the repository. To use models under the ``inference.tf`` module (e.g. ``DragonNet``), additional dependency of ``tensorflow`` is required. For detailed instructions, see below. +Installation with ``conda`` is recommended. -Install using ``conda`` ------------------------ +``conda`` environment files for Python 3.7, 3.8 and 3.9 are available in the repository. To use models under the ``inference.tf`` module (e.g. ``DragonNet``), additional dependency of ``tensorflow`` is required. For detailed instructions, see below. -This will create a new ``conda`` virtual environment named ``causalml-[tf-]py3x``, where ``x`` is in ``[6, 7, 8, 9]``. e.g. ``causalml-py37`` or ``causalml-tf-py38``. If you want to change the name of the environment, update the relevant YAML file in ``envs/``. +Install using ``conda``: +------------------------ + +Install ``conda`` with: +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh + bash Miniconda3-latest-Linux-x86_64.sh -b + source miniconda3/bin/activate + conda init + source ~/.bashrc + +Install from ``conda-forge`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Directly install from the ``conda-forge`` channel using ``conda``. + +.. code-block:: bash + + conda install -c conda-forge causalml + +Install from the ``conda`` virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This will create a new ``conda`` virtual environment named ``causalml-[tf-]py3x``, where ``x`` is in ``[7, 8, 9]``. e.g. ``causalml-py37`` or ``causalml-tf-py38``. If you want to change the name of the environment, update the relevant YAML file in ``envs/``. .. code-block:: bash - $ git clone https://github.com/uber/causalml.git - $ cd causalml/envs/ - $ conda env create -f environment-py38.yml # for the virtual environment with Python 3.8 and CausalML - $ conda activate causalml-py38 + git clone https://github.com/uber/causalml.git + cd causalml/envs/ + conda env create -f environment-py38.yml # for the virtual environment with Python 3.8 and CausalML + conda activate causalml-py38 (causalml-py38) -To install ``causalml`` with ``tensorflow`` using ``conda``, use a relevant ``causalml-[tf-]py3x`` environment file as follows: +Install ``causalml`` with ``tensorflow`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash - $ git clone https://github.com/uber/causalml.git - $ cd causalml/envs/ - $ conda env create -f environment-tf-py38.yml # for the virtual environment with Python 3.8 and CausalML - $ conda activate causalml-tf-py38 + git clone https://github.com/uber/causalml.git + cd causalml/envs/ + conda env create -f environment-tf-py38.yml # for the virtual environment with Python 3.8 and CausalML + conda activate causalml-tf-py38 (causalml-tf-py38) pip install -U numpy # this step is necessary to fix [#338](https://github.com/uber/causalml/issues/338) -Install using ``pip`` ---------------------- +Install from ``PyPI``: +---------------------- .. code-block:: bash - $ git clone https://github.com/uber/causalml.git - $ cd causalml - $ pip install -r requirements.txt - $ pip install causalml + pip install causalml + +Install ``causalml`` with ``tensorflow`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + pip install causalml[tf] + pip install -U numpy # this step is necessary to fix [#338](https://github.com/uber/causalml/issues/338) + + +Install from source: +-------------------- + +Create a clean ``conda`` environment. + +.. code-block:: bash + conda create -n causalml-py38 python=3.8 + conda activate causalml-py38 + conda install -c conda-forge cxx-compiler + conda install python-graphviz + conda install -c conda-forge xorg-libxrender -To install ``causalml`` with ``tensorflow`` using ``pip``, use ``causalml[tf]`` as follows: +Then: .. code-block:: bash - $ git clone https://github.com/uber/causalml.git - $ cd causalml - $ pip install -r requirements-tf.txt - $ pip install causalml[tf] - $ pip install -U numpy # this step is necessary to fix [#338](https://github.com/uber/causalml/issues/338) + git clone https://github.com/uber/causalml.git + cd causalml + pip install . + python setup.py build_ext --inplace -Install from source -------------------- +with ``tensorflow``: .. code-block:: bash - $ git clone https://github.com/uber/causalml.git - $ cd causalml - $ pip install -r requirements.txt - $ python setup.py build_ext --inplace - $ python setup.py install + pip install .[tf]