lcgp 0.1.2__tar.gz

lcgp-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on:
+      ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip setuptools 'setuptools_scm[toml]' setuptools_scm_git_archive numpy Cython
+          python setup.py --version
+          pip install --no-cache-dir -U -r requirements.txt | cat
+          pip install --upgrade numpy
+          pip install ruff pytest
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff --format=github --select=E9,F63,F7,F82 --exclude=illustration-examples,reference_code .
+          # default set of ruff rules with GitHub Annotations
+          ruff --format=github --exclude=illustration-examples,reference_code,tests .
+      - name: Test with pytest
+        run: pytest
+      - name: Upload coverage data
+        run: |
+         coveralls --service=github
+        env:
+         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+         COVERALLS_FLAG_NAME: ${{ matrix.test-name }}
+         COVERALLS_PARALLEL: true
+  
+  finish:
+   name: Finish Coveralls
+   needs: test
+   runs-on: ubuntu-latest
+   steps:
+     - name: Coveralls GitHub Action
+       uses: coverallsapp/github-action@v2
+       with:
+         github-token: ${{ secrets.GITHUB_TOKEN }}
+         parallel-finished: true

lcgp-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+# This workflow publishes releases to https://pypi.org/project/surmise/
+
+name: PyPI publisher
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  pypi-publish:
+    name: Build and upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/lcgp/
+    permissions:
+      id-token: write  
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m pip install build --user
+    - name: Build a binary wheel and a source tarball
+      run: >-
+        python3 -m build
+        --sdist
+        --wheel
+        --outdir dist/
+        .
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_ACCESS_TOKEN }}

lcgp-0.1.2/.github/workflows/ruff.yaml

@@ -0,0 +1,12 @@
+name: Ruff
+on: [push, pull_request]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1
+
+        with:
+          version: 0.0.280
+          args: --fix --exit-non-zero-on-fix

lcgp-0.1.2/.gitignore

@@ -0,0 +1,57 @@
+# local virtual environment and pycharm files
+.idea/
+
+venv/
+*.pyc
+*.pclprof
+*.dat
+
+# build
+build/
+dist/
+lcgp.egg-info/
+
+# archive
+src/archive/*
+lcgp/archive/
+lcgp/debug/
+lcgp/reference_code/
+lcgp/plot_code/
+
+# data files
+tests/data/*
+tests/testfunctions/*
+
+# documentation and coverage
+docs/_build
+docs/_static
+docs/source
+cover
+.coverage
+
+# illustrations
+submethod-illustration/illustrate-submethod-loss.py
+illustration-examples/lcgp-3d-illustration-addon.py
+illustration-examples/lcgp-3d-mean-var.py
+# figures
+illustration-examples/output_fig/*
+# notebooks
+illustration-examples/notebooks/*
+
+# output and plot files
+*/data/
+*/output/
+*/figures/
+*plot.py
+
+# debug files
+illustration-examples/lcgp_debug.py
+
+# other codes
+reference_code/GPPCA/
+
+# ignore version
+lcgp/_version.py
+
+# pdfs
+literature/

lcgp-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.0.282
+  hooks:
+    - id: ruff
+      args: [--fix, --exit-non-zero-on-fix]

lcgp-0.1.2/.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt

lcgp-0.1.2/CITATION.cff

@@ -0,0 +1,30 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: Latent component Gaussian process
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Moses Y.-H.
+    family-names: Chan
+    email: mosesyhc@u.northwestern.edu
+    affiliation: Northwestern University
+    orcid: 'https://orcid.org/0000-0002-2181-5116'
+identifiers:
+  - type: url
+    value: 'https://github.com/mosesyhc/lcgp'
+repository-code: 'https://github.com/mosesyhc/lcgp'
+url: 'https://lcgp.readthedocs.io'
+abstract: >-
+  An emulator strategy for multivariate stochastic
+  simulations.
+keywords:
+  - stochastic simulation
+  - multivariate output
+  - gaussian process
+  - emulator
+  - surrogate
+license: MIT

lcgp-0.1.2/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Moses Chan <mosesyhc@u.northwestern.edu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

lcgp-0.1.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include pyproject.toml
+prune illustration-examples*
+prune literature*
+prune docs*

lcgp-0.1.2/Makefile

@@ -0,0 +1,56 @@
+.PHONY: docmake docopen docinit docremove docupdate install test clean
+
+PACKAGE := lcgp
+
+docmake:
+	rm -rf docs/source
+	sphinx-apidoc -eMT -o docs/source/ $(PACKAGE)
+	rm docs/source/$(PACKAGE).rst
+	pandoc --from=markdown --to=rst --output=docs/readme.rst README.md
+	cd docs && make html
+
+docopen:
+	open docs/_build/html/index.html
+
+docinit:
+	$(eval BRANCH := $(shell git rev-parse --abbrev-ref HEAD))
+	git checkout -b gh-pages
+	git ls-tree HEAD \
+		| awk '$$4 !~ /\.nojekyll|docs|index\.html/ { print $$4 }' \
+		| xargs -I {} git rm -r {}
+	touch .nojekyll
+	echo '<meta http-equiv="refresh" content="0; url=./docs/_build/html/index.html" />' > index.html
+	git add .nojekyll index.html
+	git commit -m "Branch cleaned for docs"
+	git push origin gh-pages
+	git checkout $(BRANCH)
+
+docremove:
+	git branch -D gh-pages
+	git push origin --delete gh-pages
+
+docupdate: docmake
+	$(eval BRANCH := $(shell git rev-parse --abbrev-ref HEAD))
+	rm -rf docs/_build/html_new
+	mv docs/_build/html docs/_build/html_new
+	git checkout gh-pages
+	rm -rf docs/_build/html
+	mv docs/_build/html_new docs/_build/html
+	git add -f docs/_build/html
+	git commit -m "Update docs at $$(date +'%d %b %Y, %H:%M')"
+	git push origin gh-pages
+	git checkout $(BRANCH)
+
+install:
+	pip install -r requirements.txt
+
+test:
+	python setup.py --version
+#	pytest -v --cov=$(PACKAGE) --cov-report html:cover --cov-report term-missing
+
+clean:
+	rm -rf docs/_build docs/source docs/readme.rst
+	git rm --cached -r docs
+	git add docs/Makefile docs/conf.py docs/index.rst docs/api.rst
+	rm -rf .coverage cover
+	find . | grep '\(\.DS_Store\|\.pyc\)$$' | xargs rm

lcgp-0.1.2/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.1
+Name: lcgp
+Version: 0.1.2
+Summary: Latent component Gaussian process
+Author-email: Moses Chan <mosesyhc@u.northwestern.edu>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2023 Moses Chan <mosesyhc@u.northwestern.edu>
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+        
+Project-URL: Repository, https://github.com/mosesyhc/lcgp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: torch>=2.0.1
+Requires-Dist: numpy>=1.18.3
+Requires-Dist: scipy>=1.10.1
+
+# [Latent component Gaussian process (LCGP)](https://github.com/mosesyhc/LCGP)
+
+[![CI](https://github.com/mosesyhc/lcgp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mosesyhc/LCGP/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/mosesyhc/LCGP/badge.svg)](https://coveralls.io/github/mosesyhc/LCGP)
+[![Documentation Status](https://readthedocs.org/projects/lcgp/badge/?version=latest)](https://lcgp.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://badge.fury.io/py/lcgp.svg)](https://badge.fury.io/py/lcgp)
+
+Implementation of latent component Gaussian process (LCGP).  LCGP handles the emulation
+of multivariate stochastic simulation outputs. 
+
+___
+
+List of Contents:
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+  - [What most of us need](#what-most-of-us-need)
+  - [Specifying number of latent components](#specifying-number-of-latent-components)
+  - [Specifying diagonal error groups](#specifying-diagonal-error-groupings)
+  - [Calling different submethod](#define-lcgp-using-different-submethod)
+  - [Standardization choices](#standardization-choices)
+
+
+## Installation
+The implementation of LCGP can be installed through
+
+```bash
+pip install lcgp
+```
+
+> **Note on LBFGS optimizer:** 
+> 
+> It is strongly recommended that 
+> [PyTorch-LBFGS](https://github.com/hjmshi/PyTorch-LBFGS) is installed to fully utilize
+> this implementation.
+> Installation guide on PyTorch-LBFGS can be found on 
+> [its repository](https://github.com/hjmshi/PyTorch-LBFGS).
+> Note that PyTorch-LBFGS has an additional requirement `matplotlib`.  The source code of a version
+> of PyTorch-LBFGS that **does not** require `matplotlib` is included in [reference_code](reference_code/).
+> 
+
+## Basic usage
+### What most of us need:
+```python
+import numpy as np
+from lcgp import LCGP
+from lcgp import evaluation  # optional evaluation module
+
+# Generate fifty 2-dimensional input and 4-dimensional output
+x = np.random.randn(50, 2)
+y = np.random.randn(4, 50)
+
+# Define LCGP model
+model = LCGP(y=y, x=x)
+
+# Estimate error covariance and hyperparameters
+model.fit()
+
+# Prediction
+p = model.predict(x0=x)  # mean and variance
+rmse = evaluation.rmse(y, p[0].numpy())
+dss = evaluation.dss(y, p[0].numpy(), p[1].numpy(), use_diag=True)
+print('Root mean squared error: {:.3E}'.format(rmse))
+print('Dawid-Sebastiani score: {:.3f}'.format(dss))
+
+# Access parameters
+print(model)
+```
+
+### Specifying number of latent components
+There are two ways to specify the number of latent components by 
+passing one of the following arguments in initializing an LCGP instance:
+
+- `q = 5`: Five latent components will be used.  `q` must be less than or 
+equal to the output dimension.
+- `var_threshold = 0.99`: Include $q$ latent components such that 99% of the output 
+variance are explained, using a singular value decomposition.
+
+> **Note**: Only one of the options should be provided at a time.
+
+```python
+model_q = LCGP(y=y, x=x, q=5)
+model_var = LCGP(y=y, x=x, var_threshold=0.99)
+```
+
+### Specifying diagonal error groupings
+If errors of multiple output dimensions are expected to be similar, the error variances
+can be grouped in estimation.  
+
+For example, the 6-dimensional output is split into two groups: the
+first two have low errors and the remaining four have high errors.
+
+```python
+import numpy as np
+
+x = np.linspace(0, 1, 100)
+y = np.row_stack((
+    np.sin(x), np.cos(x), np.tan(x),
+    np.sin(x/2), np.cos(x/2), np.tan(x/2)
+))
+
+y[:2] += np.random.normal(2, 1e-3, size=(2, 100))
+y[2:] += np.random.normal(-2, 1e-1, size=(4, 100))
+```
+
+Then, LCGP can be defined with the argument `diag_error_structure` as a list
+of output dimensions to group.  The following code groups the first 2 and the remaining 
+4 output dimensions.
+```python
+model_diag = LCGP(y=y, x=x, diag_error_structure=[2, 4])
+```
+
+By default, LCGP assigns a separate error variance to each dimension,
+equivalent to 
+
+```python
+model_diag = LCGP(y=y, x=x, diag_error_structure=[1]*6)
+```
+
+### Define LCGP using different submethod
+Three submethods are implemented under LCGP:
+
+* Full posterior (`full`)
+* ELBO (`elbo`)
+* Profile likelihood (`proflik`)
+
+Under circumstances where the simulation outputs are stochastic, the full posterior 
+approach should perform the best.  If the simulation outputs are deterministic, the
+profile likelihood method should suffice. 
+
+```python
+LCGP_models = []
+submethods = ['full', 'elbo', 'proflik']
+for submethod in submethods:
+    model = LCGP(y=y, x=x, submethod=submethod)
+    LCGP_models.append(model)
+```
+
+### Standardization choices
+LCGP standardizes the simulation output by each dimension to facilitate hyperparameter
+training.  The two choices are implemented through `robust_mean = True` or 
+`robust_mean = False`. 
+
+* `robust_mean = False`: The empirical mean and standard deviation are used.
+* `robust_mean = True`: The empirical median and median absolute error are used.
+
+```python
+model = LCGP(y=y, x=x, robust_mean=False)
+```
+
+---

lcgp-0.1.2/README.md

@@ -0,0 +1,151 @@
+# [Latent component Gaussian process (LCGP)](https://github.com/mosesyhc/LCGP)
+
+[![CI](https://github.com/mosesyhc/lcgp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mosesyhc/LCGP/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/mosesyhc/LCGP/badge.svg)](https://coveralls.io/github/mosesyhc/LCGP)
+[![Documentation Status](https://readthedocs.org/projects/lcgp/badge/?version=latest)](https://lcgp.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://badge.fury.io/py/lcgp.svg)](https://badge.fury.io/py/lcgp)
+
+Implementation of latent component Gaussian process (LCGP).  LCGP handles the emulation
+of multivariate stochastic simulation outputs. 
+
+___
+
+List of Contents:
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+  - [What most of us need](#what-most-of-us-need)
+  - [Specifying number of latent components](#specifying-number-of-latent-components)
+  - [Specifying diagonal error groups](#specifying-diagonal-error-groupings)
+  - [Calling different submethod](#define-lcgp-using-different-submethod)
+  - [Standardization choices](#standardization-choices)
+
+
+## Installation
+The implementation of LCGP can be installed through
+
+```bash
+pip install lcgp
+```
+
+> **Note on LBFGS optimizer:** 
+> 
+> It is strongly recommended that 
+> [PyTorch-LBFGS](https://github.com/hjmshi/PyTorch-LBFGS) is installed to fully utilize
+> this implementation.
+> Installation guide on PyTorch-LBFGS can be found on 
+> [its repository](https://github.com/hjmshi/PyTorch-LBFGS).
+> Note that PyTorch-LBFGS has an additional requirement `matplotlib`.  The source code of a version
+> of PyTorch-LBFGS that **does not** require `matplotlib` is included in [reference_code](reference_code/).
+> 
+
+## Basic usage
+### What most of us need:
+```python
+import numpy as np
+from lcgp import LCGP
+from lcgp import evaluation  # optional evaluation module
+
+# Generate fifty 2-dimensional input and 4-dimensional output
+x = np.random.randn(50, 2)
+y = np.random.randn(4, 50)
+
+# Define LCGP model
+model = LCGP(y=y, x=x)
+
+# Estimate error covariance and hyperparameters
+model.fit()
+
+# Prediction
+p = model.predict(x0=x)  # mean and variance
+rmse = evaluation.rmse(y, p[0].numpy())
+dss = evaluation.dss(y, p[0].numpy(), p[1].numpy(), use_diag=True)
+print('Root mean squared error: {:.3E}'.format(rmse))
+print('Dawid-Sebastiani score: {:.3f}'.format(dss))
+
+# Access parameters
+print(model)
+```
+
+### Specifying number of latent components
+There are two ways to specify the number of latent components by 
+passing one of the following arguments in initializing an LCGP instance:
+
+- `q = 5`: Five latent components will be used.  `q` must be less than or 
+equal to the output dimension.
+- `var_threshold = 0.99`: Include $q$ latent components such that 99% of the output 
+variance are explained, using a singular value decomposition.
+
+> **Note**: Only one of the options should be provided at a time.
+
+```python
+model_q = LCGP(y=y, x=x, q=5)
+model_var = LCGP(y=y, x=x, var_threshold=0.99)
+```
+
+### Specifying diagonal error groupings
+If errors of multiple output dimensions are expected to be similar, the error variances
+can be grouped in estimation.  
+
+For example, the 6-dimensional output is split into two groups: the
+first two have low errors and the remaining four have high errors.
+
+```python
+import numpy as np
+
+x = np.linspace(0, 1, 100)
+y = np.row_stack((
+    np.sin(x), np.cos(x), np.tan(x),
+    np.sin(x/2), np.cos(x/2), np.tan(x/2)
+))
+
+y[:2] += np.random.normal(2, 1e-3, size=(2, 100))
+y[2:] += np.random.normal(-2, 1e-1, size=(4, 100))
+```
+
+Then, LCGP can be defined with the argument `diag_error_structure` as a list
+of output dimensions to group.  The following code groups the first 2 and the remaining 
+4 output dimensions.
+```python
+model_diag = LCGP(y=y, x=x, diag_error_structure=[2, 4])
+```
+
+By default, LCGP assigns a separate error variance to each dimension,
+equivalent to 
+
+```python
+model_diag = LCGP(y=y, x=x, diag_error_structure=[1]*6)
+```
+
+### Define LCGP using different submethod
+Three submethods are implemented under LCGP:
+
+* Full posterior (`full`)
+* ELBO (`elbo`)
+* Profile likelihood (`proflik`)
+
+Under circumstances where the simulation outputs are stochastic, the full posterior 
+approach should perform the best.  If the simulation outputs are deterministic, the
+profile likelihood method should suffice. 
+
+```python
+LCGP_models = []
+submethods = ['full', 'elbo', 'proflik']
+for submethod in submethods:
+    model = LCGP(y=y, x=x, submethod=submethod)
+    LCGP_models.append(model)
+```
+
+### Standardization choices
+LCGP standardizes the simulation output by each dimension to facilitate hyperparameter
+training.  The two choices are implemented through `robust_mean = True` or 
+`robust_mean = False`. 
+
+* `robust_mean = False`: The empirical mean and standard deviation are used.
+* `robust_mean = True`: The empirical median and median absolute error are used.
+
+```python
+model = LCGP(y=y, x=x, robust_mean=False)
+```
+
+---