Merge pull request #47 from StochasticTree/readme_edit

Updated README

Author: andrewherren

README.md

@@ -1,10 +1,104 @@
-# StochasticTree C++ Core
+# StochasticTree
 
-[![Build and test](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/test-multi-platform.yml/badge.svg)](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/test-multi-platform.yml)
+[![C++ Tests](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/cpp-test.yml/badge.svg)](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/cpp-test.yml)
+[![Python Tests](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/python-test.yml/badge.svg)](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/python-test.yml)
+[![R Tests](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/r-test.yml/badge.svg)](https://github.com/StochasticTree/stochtree-cpp/actions/workflows/r-test.yml)
 
-This repository hosts the "core" C++ code for defining and sampling stochastic tree ensembles (BART, XBART) for various applications. 
-The [R](https://github.com/StochasticTree/stochtree-r) and [Python](https://github.com/StochasticTree/stochtree-python) 
-packages have been refactored into separate repositories with installation instructions and demo notebooks. 
+Software for building stochastic tree ensembles (i.e. BART, XBART) for supervised learning and causal inference.
+
+# Getting Started
+
+`StochasticTree` is composed of a C++ "core" and R / Python interfaces to that core. 
+Details on installation and use are available below:
+
+* [Python](#python-package)
+* [R](#r-package)
+* [C++ core](#c-core)
+
+# Python Package
+
+The python package is not yet on PyPI but can be installed from source using pip's [git interface](https://pip.pypa.io/en/stable/topics/vcs-support/). 
+To proceed, you will need a working version of [git](https://git-scm.com) and python 3.8 or greater (available from several sources, one of the most 
+straightforward being the [anaconda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) suite).
+
+## Quick start
+
+Without worrying about virtual environments (detailed further below), `stochtree` can be installed from the command line
+
+```
+pip install numpy scipy pytest pandas scikit-learn pybind11
+pip install git+https://github.com/StochasticTree/stochtree-cpp.git
+```
+
+## Virtual environment installation
+
+Often, users prefer to manage different projects (with different package / python version requirements) in virtual environments. 
+
+### Conda
+
+Conda provides a straightforward experience in managing python dependencies, avoiding version conflicts / ABI issues / etc.
+
+To build stochtree using a `conda` based workflow, first create and activate a conda environment with the requisite dependencies
+
+```{bash}
+conda create -n stochtree-dev -c conda-forge python=3.10 numpy scipy pytest pandas pybind11 scikit-learn matplotlib seaborn
+conda activate stochtree-dev
+```
+
+Then, navigate to the main `stochtree-python` project folder (i.e. `cd /path/to/stochtree-python`) and install the package locally via pip
+
+```{bash}
+pip install .
+```
+
+(*Note*: if you'd also like to run the notebook examples in the `demo/` subfolder, you will also need jupyterlab, seaborn, and matplotlib)
+
+```{bash}
+conda install matplotlib seaborn
+pip install jupyterlab
+```
+
+### Venv
+
+You could also use venv for environment management. 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:
+
+```{bash}
+python -m venv venv
+source venv/bin/activate
+```
+
+Install all of the package (and demo notebook) dependencies
+
+```{bash}
+pip install numpy scipy pytest pandas scikit-learn pybind11
+```
+
+Then install stochtree via
+
+```{bash}
+pip install .
+```
+
+(As above, if you'd like to run the notebook examples in the `demo/` subfolder, you will also need jupyterlab, seaborn, and matplotlib)
+
+```{bash}
+pip install matplotlib seaborn jupyterlab
+```
+
+# R Package
+
+The package can be installed in R via
+
+```
+remotes::install_github("StochasticTree/stochtree-cpp")
+```
+
+# C++ Core
+
+While the C++ core links to both R and Python for a performant, high-level interface, 
+the C++ code can be compiled and unit-tested and compiled into a standalone 
+[debug program](https://github.com/StochasticTree/stochtree-cpp/tree/main/debug).
 
 ## Compilation
 
@@ -54,3 +148,24 @@ via `lldb ./build/debugstochtree` (clang) or `gdb ./build/debugstochtree` (gcc).
 We test `stochtree-cpp` using the [GoogleTest](https://google.github.io/googletest/) framework.
 Unit tests are compiled into a single target as part of the CMake build if the `BUILD_TEST` option is set to `ON` 
 and the test suite can be run after compilation via `./build/teststochtree`
+
+## Xcode
+
+While using `gdb` or `lldb` on `debugstochtree` at the command line is very helpful, users may prefer debugging in a full-fledged IDE like xcode. This project's C++ core can be converted to an xcode project from `CMakeLists.txt`, but first you must turn off sanitizers (xcode seems to have its own way of setting this at build time for different configurations, and having injected 
+`-fsanitize=address` statically into compiler arguments will cause xcode errors). To do this, modify the `USE_SANITIZER` line in `CMakeLists.txt`:
+
+```
+option(USE_SANITIZER "Use santizer flags" OFF)
+```
+
+To generate an XCode project based on the build targets and specifications defined in a `CMakeLists.txt`, navigate to the main project folder (i.e. `cd /path/to/project`) and run the following commands:
+
+```{bash}
+rm -rf xcode/
+mkdir xcode
+cd xcode
+cmake -G Xcode .. -DCMAKE_C_COMPILER=cc -DCMAKE_CXX_COMPILER=c++
+cd ..
+```
+
+Now, if you navigate to the xcode subfolder (in Finder), you should be able to click on a `.xcodeproj` file and the project will open in XCode.