Skip to content
This repository was archived by the owner on Feb 7, 2025. It is now read-only.

Commit 4f86a34

Browse files
andrewherrenandrewherren
authored
Merge pull request #3 from StochasticTree/doc_setup
Sphinx documentation setup
2 parents 06ac26c + fecd388 commit 4f86a34

File tree

12 files changed

+766
-47
lines changed

12 files changed

+766
-47
lines changed

‎.github/workflows/docs.yml

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Combination of https://github.com/RobinMagnet/pyFM/blob/master/.github/workflows/documentation.yml
2+
# and https://github.com/r-lib/pkgdown/blob/main/.github/workflows/pkgdown.yaml
3+
name: docs
4+
5+
on:
6+
push:
7+
branches: [main]
8+
pull_request:
9+
branches: [main]
10+
release:
11+
types: [published]
12+
workflow_dispatch:
13+
14+
jobs:
15+
build_documentation:
16+
name: Build Documentation
17+
runs-on: ubuntu-latest
18+
19+
permissions:
20+
contents: write
21+
22+
steps:
23+
- name: Checkout repository
24+
uses: actions/checkout@v4
25+
with:
26+
submodules: 'recursive'
27+
28+
- name: Setup Python 3.10
29+
uses: actions/setup-python@v5
30+
with:
31+
python-version: "3.10"
32+
cache: "pip"
33+
34+
- name: Install Package with Relevant Dependencies
35+
run: |
36+
pip install --upgrade pip
37+
pip install -r docs/requirements.txt
38+
pip install .
39+
40+
- name: Build HTML
41+
run: |
42+
sphinx-build -M html docs/source/ docs/_build/
43+
44+
- name: Upload Artifact
45+
uses: actions/upload-artifact@v4
46+
with:
47+
path:
48+
docs/_build/html/
49+
50+
- name: Deploy to GitHub Pages
51+
uses: peaceiris/actions-gh-pages@v4
52+
if: github.ref == 'refs/heads/main'
53+
with:
54+
github_token: ${{ secrets.GITHUB_TOKEN }}
55+
publish_dir: docs/_build/html

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
alabaster==0.7.13
2+
Babel==2.15.0
3+
beautifulsoup4==4.12.3
4+
certifi==2024.2.2
5+
charset-normalizer==3.3.2
6+
docutils==0.20.1
7+
furo==2024.5.6
8+
idna==3.7
9+
imagesize==1.4.1
10+
importlib_metadata==7.1.0
11+
Jinja2==3.1.4
12+
joblib==1.4.2
13+
MarkupSafe==2.1.5
14+
numpy==1.24.4
15+
packaging==24.0
16+
pandas==2.0.3
17+
pybind11==2.12.0
18+
Pygments==2.18.0
19+
python-dateutil==2.9.0.post0
20+
pytz==2024.1
21+
requests==2.32.2
22+
scikit-learn==1.3.2
23+
scipy==1.10.1
24+
six==1.16.0
25+
snowballstemmer==2.2.0
26+
soupsieve==2.5
27+
Sphinx==7.1.2
28+
sphinx-basic-ng==1.0.0b2
29+
sphinxcontrib-applehelp==1.0.4
30+
sphinxcontrib-devhelp==1.0.2
31+
sphinxcontrib-htmlhelp==2.0.1
32+
sphinxcontrib-jsmath==1.0.1
33+
sphinxcontrib-qthelp==1.0.3
34+
sphinxcontrib-serializinghtml==1.1.5
35+
threadpoolctl==3.5.0
36+
tzdata==2024.1
37+
urllib3==2.2.1
38+
zipp==3.18.2

‎docs/source/api.rst

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
StochTree API
2+
=============
3+
4+
BART
5+
----
6+
7+
.. autoclass:: stochtree.bart.BARTModel
8+
:members: sample, predict
9+
10+
BCF
11+
---
12+
13+
.. autoclass:: stochtree.bcf.BCFModel
14+
:members: sample, predict, predict_tau

‎docs/source/causal.rst

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Causal Inference
2+
================
3+
4+
This vignette provides a quick overview (using simulated data) of how to use ``stochtree`` for causal inference.
5+
Start by loading stochtree's ``BCFModel`` class and a number of other packages.
6+
7+
.. code-block:: python
8+
9+
import numpy as np
10+
import pandas as pd
11+
import seaborn as sns
12+
import matplotlib.pyplot as plt
13+
from stochtree import BCFModel
14+
from sklearn.model_selection import train_test_split
15+
16+
Now, we generate a simulated causal inference problem
17+
18+
.. code-block:: python
19+
20+
# RNG
21+
random_seed = 101
22+
rng = np.random.default_rng(random_seed)
23+
24+
# Generate covariates and basis
25+
n = 1000
26+
p_X = 5
27+
X = rng.uniform(0, 1, (n, p_X))
28+
pi_X = 0.25 + 0.5*X[:,0]
29+
Z = rng.binomial(1, pi_X, n).astype(float)
30+
31+
# Define the outcome mean functions (prognostic and treatment effects)
32+
mu_X = pi_X*5
33+
# tau_X = np.sin(X[:,1]*2*np.pi)
34+
tau_X = X[:,1]*2
35+
36+
# Generate outcome
37+
epsilon = rng.normal(0, 1, n)
38+
y = mu_X + tau_X*Z + epsilon
39+
40+
Split the dataset into train and test sets
41+
42+
.. code-block:: python
43+
44+
sample_inds = np.arange(n)
45+
train_inds, test_inds = train_test_split(sample_inds, test_size=0.5)
46+
X_train = X[train_inds,:]
47+
X_test = X[test_inds,:]
48+
Z_train = Z[train_inds]
49+
Z_test = Z[test_inds]
50+
y_train = y[train_inds]
51+
y_test = y[test_inds]
52+
pi_train = pi_X[train_inds]
53+
pi_test = pi_X[test_inds]
54+
mu_train = mu_X[train_inds]
55+
mu_test = mu_X[test_inds]
56+
tau_train = tau_X[train_inds]
57+
tau_test = tau_X[test_inds]
58+
59+
Initialize and run a BCF sampler for 1000 iterations (after 10 "warm-start" draws)
60+
61+
.. code-block:: python
62+
63+
bcf_model = BCFModel()
64+
bcf_model.sample(X_train, Z_train, y_train, pi_train, X_test, Z_test, pi_test, num_gfr=10, num_mcmc=1000)

‎docs/source/conf.py

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# import os
7+
# import sys
8+
# sys.path.insert(0, os.path.abspath('../..'))
9+
10+
# -- Project information -----------------------------------------------------
11+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
12+
13+
project = 'stochtree'
14+
copyright = '2024, Drew Herren'
15+
author = 'Drew Herren'
16+
release = '0.0.1'
17+
18+
# -- General configuration ---------------------------------------------------
19+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
20+
21+
extensions = [
22+
'sphinx.ext.autodoc',
23+
'sphinx.ext.autosummary',
24+
]
25+
26+
templates_path = ['_templates']
27+
exclude_patterns = []
28+
29+
30+
31+
# -- Options for HTML output -------------------------------------------------
32+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
33+
34+
html_theme = 'furo'
35+
html_static_path = ['_static']

‎docs/source/index.rst

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
StochTree
2+
=========
3+
4+
``stochtree`` runs stochastic machine learning algorithms for supervised learning and causal inference.
5+
For details on installing the package, see the :doc:`Installation <install>` page. Once you have ``stochtree`` installed,
6+
the :doc:`Supervised Learning <supervised>` and :doc:`Causal Inference <causal>` vignettes provide some guidance on
7+
using the package for your use case.
8+
9+
.. We also support a lower-level interface to the underlying C++ data structures which can allow for custom sampling routines
10+
.. (i.e. interspersing a BART forest with a neural network, a complicated variance sampler, etc...). This interface is introduced
11+
.. in the :doc:`Prototype <prototype>` vignette.
12+
13+
For complete function / class documentation, see the :doc:`API <api>` page.
14+
15+
.. toctree::
16+
install
17+
supervised
18+
causal
19+
api

‎docs/source/install.rst

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Installation
2+
============
3+
4+
The python package can be installed from source. Clone the repo recursively (including git submodules) by running
5+
6+
.. code-block:: console
7+
8+
$ git clone --recursive https://github.com/StochasticTree/stochtree-python.git
9+
10+
Conda
11+
-----
12+
13+
Conda provides a straightforward experience in managing python dependencies, avoiding version conflicts / ABI issues / etc.
14+
Before you begin, make sure you have `conda <https://www.anaconda.com/download>`_ installed.
15+
Next, create and activate a conda environment with the requisite dependencies
16+
17+
.. code-block:: console
18+
19+
$ conda create -n stochtree-dev -c conda-forge python=3.10 numpy scipy pytest pandas pybind11 scikit-learn matplotlib seaborn
20+
$ conda activate stochtree-dev
21+
$ pip install jupyterlab
22+
23+
Then, navigate to the main ``stochtree-python`` project folder (i.e. ``cd /path/to/stochtree-python``) and install the package locally via pip
24+
25+
.. code-block:: console
26+
27+
$ pip install .
28+
29+
pip
30+
---
31+
32+
If you would rather avoid installing and setting up conda, you can alternatively setup the dependencies and install ``stochtree`` using only ``pip`` (caveat: this has not been extensively tested
33+
across platforms and python versions).
34+
35+
First, navigate to the main ``stochtree-python`` project folder (i.e. ``cd /path/to/stochtree-python``) and create and activate a virtual environment as a subfolder of the repo
36+
37+
.. code-block:: console
38+
39+
$ python -m venv venv
40+
$ source venv/bin/activate
41+
42+
Install all of the package (and demo notebook) dependencies
43+
44+
.. code-block:: console
45+
46+
$ pip install numpy scipy pytest pandas scikit-learn pybind11 matplotlib seaborn jupyterlab
47+
48+
Then install stochtree via
49+
50+
.. code-block:: console
51+
52+
$ pip install .

0 commit comments

Comments
 (0)