Merge pull request #5 from ControlAI/docs/initial-docs

docs: current docs state in prep for release. still missing concepts …

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+
+      - run: pip install -r requirements-docs.txt
+      - run: mkdocs gh-deploy --force

.vscode/settings.json

@@ -1,8 +1,8 @@
 {
   "files.autoSave": "onFocusChange",
   "editor.rulers": [88],
-  "editor.formatOnSaveMode": "file",
   "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
   "files.insertFinalNewline": true,
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,
@@ -12,5 +12,8 @@
       "source.organizeImports": true
     },
     "editor.defaultFormatter": "charliermarsh.ruff"
-  }
+  },
+  "[markdown]": {
+    "editor.formatOnSave": false
+  },
 }

docs/README.md

@@ -1,16 +1,17 @@
 # Getting Started with PyTorch Lattice
 
-DESCRIPTION HERE
+A PyTorch implementation of constrained optimization and modeling techniques
 
 ---
 
-ADD OTHER MISSING TAGS HERE e.g. Documentation, Downloads, PyPI version
-
 [![GitHub stars](https://img.shields.io/github/stars/ControlAI/pytorch-lattice.svg)](https://github.com/ControlAI/pytorch-lattice/stargazers)
+[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://broken.github.io/pytorch-lattice)
 [![](https://github.com/ControlAI/pytorch-lattice/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ControlAI/pytorch-lattice/actions/workflows/test.yml)
 [![GitHub issues](https://img.shields.io/github/issues/ControlAI/pytorch-lattice.svg)](https://github.com/ControlAI/pytorch-lattice/issues)
-[![GitHub license](https://img.shields.io/github/license/ControlAI/pytorch-lattice.svg)](https://github.com/ControlAI/pytorch-lattice/blob/main/LICENSE)
 [![Github discussions](https://img.shields.io/github/discussions/ControlAI/pytorch-lattice)](https:github.com/ControlAI/pytorch-lattice/discussions)
+[![GitHub license](https://img.shields.io/github/license/ControlAI/pytorch-lattice.svg)](https://github.com/ControlAI/pytorch-lattice/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/pytorch-lattice.svg)](https://pypi.python.org/pypi/pytorch-lattice)
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/pytorch-lattice.svg)](https://pypi.python.org/pypi/pytorch-lattice)
 
 ---
 
@@ -24,8 +25,6 @@ $ pip install pytorch-lattice
 
 ## Quickstart
 
-!!! info "Use the [Quickstart Colab](https://colab.research.google.com/drive/1KSzTXCIXSo20w7s_3c0yKcYVTOEADm6H?usp=sharing) to get started even faster!"
-
 ### Step 1. Import the package
 
 First, import the PyTorch Lattice library:
@@ -43,31 +42,50 @@ X, y = pyl.datasets.heart()
 clf = pyl.Classifier(X.columns).fit(X, y)
 ```
 
-### Step 3. Plot feature calibrators
+### Step 3. Plot a feature calibrator
 
 Now that you've trained a classifier, you can plot the feature calibrators to better understand how the model is understanding each feature.
 
 ```py
-pyl.plot.calibrators(clf)
+pyl.plots.calibrator(clf.model, "thal")
 ```
 
-NEED TO ADD IMAGES HERE
+![Thal Calibrator](img/thal_calibrator.png)
+
+### Step 4. What's Next?
+
+-   Check out the [Concepts](concepts/classifier.md) section to dive deeper into the library and the core features that make it powerful, such as [calibrators](concepts/calibrators.md) and [shape constraints](concepts/shape_constraints.md).
+-   You can follow along with more detailed [walkthroughs](walkthroughs/uci_adult_income.md) to get a better understanding of how to utilize the library to effectively model your data. You can also take a look at [code examples](https://github.com/ControlAI/pytorch-lattice/tree/main/examples) in the repo.
+-   The [API Reference](api/layers.md) contains full details on all classes, methods, functions, etc.
+
+## Related Research
+
+- [Monotonic Kronecker-Factored Lattice](https://openreview.net/forum?id=0pxiMpCyBtr), William Taylor Bakst, Nobuyuki Morioka, Erez Louidor, International Conference on Learning Representations (ICLR), 2021
+- [Multidimensional Shape Constraints](https://proceedings.mlr.press/v119/gupta20b.html), Maya Gupta, Erez Louidor, Oleksandr Mangylov, Nobu Morioka, Taman Narayan, Sen Zhao, Proceedings of the 37th International Conference on Machine Learning (PMLR), 2020
+- [Deontological Ethics By Monotonicity Shape Constraints](https://arxiv.org/abs/2001.11990), Serena Wang, Maya Gupta, International Conference on Artificial Intelligence and Statistics (AISTATS), 2020
+- [Shape Constraints for Set Functions](http://proceedings.mlr.press/v97/cotter19a.html), Andrew Cotter, Maya Gupta, H. Jiang, Erez Louidor, Jim Muller, Taman Narayan, Serena Wang, Tao Zhu. International Conference on Machine Learning (ICML), 2019
+- [Diminishing Returns Shape Constraints for Interpretability and Regularization](https://papers.nips.cc/paper/7916-diminishing-returns-shape-constraints-for-interpretability-and-regularization), Maya Gupta, Dara Bahri, Andrew Cotter, Kevin Canini, Advances in Neural Information Processing Systems (NeurIPS), 2018
+- [Deep Lattice Networks and Partial Monotonic Functions](https://research.google.com/pubs/pub46327.html), Seungil You, Kevin Canini, David Ding, Jan Pfeifer, Maya R. Gupta, Advances in Neural Information Processing Systems (NeurIPS), 2017
+- [Fast and Flexible Monotonic Functions with Ensembles of Lattices](https://papers.nips.cc/paper/6377-fast-and-flexible-monotonic-functions-with-ensembles-of-lattices), Mahdi Milani Fard, Kevin Canini, Andrew Cotter, Jan Pfeifer, Maya Gupta, Advances in Neural Information Processing Systems (NeurIPS), 2016
+- [Monotonic Calibrated Interpolated Look-Up Tables](http://jmlr.org/papers/v17/15-243.html), Maya Gupta, Andrew Cotter, Jan Pfeifer, Konstantin Voevodski, Kevin Canini, Alexander Mangylov, Wojciech Moczydlowski, Alexander van Esbroeck, Journal of Machine Learning Research (JMLR), 2016
+- [Optimized Regression for Efficient Function Evaluation](http://ieeexplore.ieee.org/document/6203580/), Eric Garcia, Raman Arora, Maya R. Gupta, IEEE Transactions on Image Processing, 2012
+- [Lattice Regression](https://papers.nips.cc/paper/3694-lattice-regression), Eric Garcia, Maya Gupta, Advances in Neural Information Processing Systems (NeurIPS), 2009
 
-## What's Next?
+## Contributing
 
-### Concepts
+PyTorch Lattice welcomes contributions from the community! See the [contribution guide](CONTRIBUTING.md) for more information on the development workflow. For bugs and feature requests, visit our [GitHub Issues](https://github.com/ControlAI/pytorch-lattice/issues) and check out our [templates](https://github.com/ControlAI/pytorch-lattice/tree/main/.github/ISSUE_TEMPLATES).
 
-See link to concepts + add more description
+## How To Help
 
-### Walkthroughs & Examples
+Any and all help is greatly appreciated! Check out our page on [how you can help](HELP.md).
 
-See link to walkthroughs for full guided walkthroughs with explanations on specific datasets
+## Roadmap
 
-Also check out our python examples of pure code in the repo.
+Check out the our [roadmap](https://github.com/orgs/ControlAI/projects/1/views/1) to see what's planned. If there's an item that you really want that isn't assigned or in progress, take a stab at it!
 
-### API Reference
+## Versioning
 
-Check out the API Reference for full details on all classes, methods, functions, etc.
+PyTorch Lattice uses [Semantic Versioning](https://semver.org/).
 
 ## License
 

docs/api/classifier.md

@@ -0,0 +1,3 @@
+# classifier
+
+::: pytorch_lattice.classifier.Classifier

docs/api/constrained_module.md

@@ -0,0 +1,3 @@
+# constrained_module
+
+::: pytorch_lattice.constrained_module.ConstrainedModule

docs/api/datasets.md

@@ -0,0 +1,3 @@
+# datasets
+
+::: pytorch_lattice.datasets

docs/api/enums.md

@@ -0,0 +1,3 @@
+# enums
+
+::: pytorch_lattice.enums

docs/api/feature_config.md

@@ -0,0 +1,3 @@
+# feature_config
+
+::: pytorch_lattice.feature_config

docs/api/layers.md

@@ -0,0 +1,9 @@
+# layers
+
+::: pytorch_lattice.layers.CategoricalCalibrator
+
+::: pytorch_lattice.layers.Lattice
+
+::: pytorch_lattice.layers.Linear
+
+::: pytorch_lattice.layers.NumericalCalibrator

docs/api/model_configs.md

@@ -0,0 +1,3 @@
+# model_configs
+
+::: pytorch_lattice.model_configs

docs/api/models.md

@@ -0,0 +1,9 @@
+# models
+
+::: pytorch_lattice.models.CalibratedLattice
+
+::: pytorch_lattice.models.CalibratedLinear
+
+::: pytorch_lattice.models.features.CategoricalFeature
+
+::: pytorch_lattice.models.features.NumericalFeature

docs/api/plots.md

@@ -0,0 +1,3 @@
+# plots
+
+::: pytorch_lattice.plots

docs/api/utils.md

@@ -0,0 +1,5 @@
+# utils
+
+::: pytorch_lattice.utils.data
+
+::: pytorch_lattice.utils.models

docs/concepts/calibrators.md

@@ -0,0 +1,3 @@
+# Calibrators
+
+Coming soon...

docs/concepts/classifier.md

@@ -0,0 +1,3 @@
+# Classifier
+
+Coming soon...

docs/concepts/model_types.md

@@ -0,0 +1,3 @@
+# Model Types
+
+Coming soon...

docs/concepts/plotting.md

@@ -0,0 +1,3 @@
+# Plotting
+
+Coming soon...

docs/concepts/shape_constraints.md

@@ -0,0 +1,3 @@
+# Shape Constraints
+
+Coming soon...

docs/contributing.md

@@ -0,0 +1,102 @@
+# Contributing
+
+## Setting Up Development Environment
+
+First, [install pyenv](https://github.com/pyenv/pyenv#installation) so you can run the code under all of the supported environments. Also make sure to [install pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv#installation) so you can create python environments with the correct versions.
+
+To install a specific version of python, you can run e.g. `pyenv install 3.10.9`. You can then create a virtual environment to run and test code locally during development by running the following code from the base directory:
+
+```sh
+pyenv virtualenv {python_version} env-name
+pyenv activate env-name
+pip install poetry
+poetry install
+```
+
+If you'd prefer, you can also use conda to manage your python versions and environments. For installing conda, see their [installation guide](https://conda.io/projects/conda/en/latest/user-guide/install/index.html).
+
+The following code is an example of how to set up such an environment:
+
+```sh
+conda create -n env-name pip poetry python={python_version}
+conda activate env-name
+poetry install
+```
+
+Make sure to replace `{python_version}` in the above snippets with the version you want the environment to use (e.g. 3.10.9) and name the environment accordingly (e.g. env-name-3.10).
+
+## Development Workflow
+
+1.  Search through existing [GitHub Issues](https://github.com/ControlAI/pytorch-lattice/issues) to see if what you want to work on has already been added.
+
+    -   If not, please create a new issue. This will help to reduce duplicated work.
+
+2.  For first-time contributors, visit [https://github.com/ControlAI/pytorch-lattice](https://github.com/ControlAI/pytorch-lattice) and "Fork" the repository (see the button in the top right corner).
+
+    -   You'll need to set up [SSH authentication](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+    -   Clone the forked project and point it to the main project:
+
+    ```shell
+    git clone https://github.com/<your-username>/pytorch-lattice.git
+    git remote add upstream https://github.com/ControlAI/pytorch-lattice.git
+    ```
+
+3.  Development.
+
+    -   Make sure you are in sync with the main repo:
+
+    ```shell
+    git checkout dev
+    git pull upstream dev
+    ```
+
+    -   Create a `git` feature branch with a meaningful name where you will add your contributions.
+
+    ```shell
+    git checkout -b meaningful-branch-name
+    ```
+
+    -   Start coding! commit your changes locally as you work:
+
+    ```shell
+    git add pytorch-lattice/modified_file.py tests/test_modified_file.py
+    git commit -m "feat: specific description of changes contained in commit"
+    ```
+
+    -   Format your code!
+
+    ```shell
+    poetry run ruff format .
+    ```
+
+    -   Lint and test your code! From the base directory, run:
+
+    ```shell
+    poetry run ruff check .
+    poetry run mypy .
+    ```
+
+4.  Contributions are submitted through [GitHub Pull Requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
+
+    -   When you are ready to submit your contribution for review, push your branch:
+
+    ```shell
+    git push origin meaningful-branch-name
+    ```
+
+    -   Open the printed URL to open a PR. Make sure to fill in a detailed title and description. Submit your PR for review.
+
+    -   Link the issue you selected or created under "Development"
+
+    -   We will review your contribution and add any comments to the PR. Commit any updates you make in response to comments and push them to the branch (they will be automatically included in the PR)
+
+### Pull Requests
+
+Please conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for all PR titles and commits.
+
+## Formatting & Linting
+
+In an effort to keep the codebase clean and easy to work with, we use `ruff` for formatting and both `ruff` and `mypy` for linting. Before sending any PR for review, make sure to run both `ruff` and `mypy`.
+
+If you are using VS Code, then install the extensions in `.vscode/extensions.json` and the workspace settings should automatically run `ruff` formatting on save and show `ruff` and `mypy` errors.