Skip to main content

HTTP-based interface to Stan, a package for Bayesian inference.

Project description

Stan logo

pypi version

HTTP-based REST interface to Stan, a package for Bayesian inference.

An HTTP 1.1 interface to the Stan C++ package, httpstan is a shim that allows users to interact with the Stan C++ library using a REST API. The package is intended for use as a universal backend for frontends which know how to make HTTP requests. The primary audience for this package is developers.

In addition to providing the essential functionality of the command-line interface to Stan (CmdStan) over HTTP, httpstan provides the following features:

  • Automatic caching of compiled Stan models

  • Automatic caching of samples from Stan models

  • Parallel sampling

Documentation: https://httpstan.readthedocs.org.

Requirements

  • Linux or macOS

  • C++ compiler: gcc ≥9.0 or clang ≥10.0.

Background

httpstan is a shim allowing clients able to make HTTP-based requests to call functions in the Stan C++ library’s stan::services namespace. httpstan was originally developed as a “backend” for a Stan interface written in Python, PyStan.

Stability and maintainability are two overriding goals of this software package.

Install

$ python3 -m pip install httpstan

In order to install httpstan from PyPI make sure your system satisfies the requirements:

  • Linux or macOS

  • x86-64 CPU

  • C++ compiler: gcc ≥9.0 or clang ≥10.0.

If your system uses a different kind of CPU, you should be able to install from source using the following commands:

# Build shared libraries
make

# Build the httpstan wheel on your system
python3 -m pip install poetry
python3 -m poetry build

# Install the wheel
python3 -m pip install dist/*.whl

Usage

After installing httpstan, running the module will begin listening on localhost, port 8080:

python3 -m httpstan

In a different terminal, make a POST request to http://localhost:8080/v1/models with Stan program code to compile the program:

curl -H "Content-Type: application/json" \
    --data '{"program_code":"parameters {real y;} model {y ~ normal(0,1);}"}' \
    http://localhost:8080/v1/models

This request will return a model name along with all the compiler output:

{"compiler_output": "In file included from …", "stanc_warnings": "", "name": "models/xc2pdjb4"}

(The model name depends on the platform and the version of Stan.)

Drawing samples from this model using default settings requires two steps: (1) launching the sampling operation and (2) retrieving the output of the operation (once it has finished).

First we make a request to launch the sampling operation:

curl -H "Content-Type: application/json" \
    --data '{"function":"stan::services::sample::hmc_nuts_diag_e_adapt"}' \
    http://localhost:8080/v1/models/xc2pdjb4/fits

This request instructs httpstan to draw samples from the normal distribution described in the model. The function name picks out a specific function in the stan::services namespace found in the Stan C++ library (see the Stan C++ documentation for details). This request will return immediately with a reference to a long-running fit operation:

{"name": "operations/gkf54axb", "done": false, "metadata": {"fit": {"name": "models/xc2pdjb4/fits/gkf54axb"}}}

Once the operation is complete, the “fit” can be retrieved. The name of the fit, models/xc2pdjb4/fits/gkf54axb, is included in the metadata field of the operation. The fit is saved as sequence of JSON-encoded messages. These messages are strung together with newlines. To retrieve these messages, saving them locally in the file myfit.jsonlines, make the following request:

curl http://localhost:8080/v1/models/xc2pdjb4/fits/gkf54axb > myfit.jsonlines

The Stan “fit”, saved in myfit.jsonlines, aggregates all messages. By reading them one by one you can recover all messages sent by the Stan C++ library.

Citation

We appreciate citations as they let us discover what people have been doing with the software. Citations also provide evidence of use which can help in obtaining grant funding.

To cite httpstan in publications use:

Riddell, A., Hartikainen, A., & Carter, M. (2021). httpstan (4.4.0). https://pypi.org/project/httpstan

Or use the following BibTeX entry:

@misc{httpstan,
  title = {httpstan (4.4.0)},
  author = {Riddell, Allen and Hartikainen, Ari and Carter, Matthew},
  year = {2021},
  month = mar,
  howpublished = {PyPI}
}

Please also cite Stan.

License

ISC License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

httpstan-4.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (45.6 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

httpstan-4.13.0-cp312-cp312-macosx_13_0_x86_64.whl (39.6 MB view details)

Uploaded CPython 3.12 macOS 13.0+ x86-64

httpstan-4.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (45.5 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

httpstan-4.13.0-cp311-cp311-macosx_13_0_x86_64.whl (39.6 MB view details)

Uploaded CPython 3.11 macOS 13.0+ x86-64

httpstan-4.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (45.5 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

httpstan-4.13.0-cp310-cp310-macosx_13_0_x86_64.whl (39.6 MB view details)

Uploaded CPython 3.10 macOS 13.0+ x86-64

File details

Details for the file httpstan-4.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a452f600e314f107f6bc17e43905ea2f3aaeebf8b8b98350e861aacf84476382
MD5 832cc1a7cfb2ecf7d36c84201c94ce81
BLAKE2b-256 d06e069e28610b85d93341ce830b1470aa103d19ba0eded27ab718264041e2c1

See more details on using hashes here.

File details

Details for the file httpstan-4.13.0-cp312-cp312-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 046cc66f0adbf7e149361ccaa76a0e1478ed865490d1288eb91ef5007d4de590
MD5 841018b1039413c031a3502f6fec2502
BLAKE2b-256 88d5e7998ed6558debc5029f7d6f1dc60bee494ff41d2a77dc20df464a885abf

See more details on using hashes here.

File details

Details for the file httpstan-4.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7b490d6c0e8b7048d1b58dfb79db561ae1879cb3bde3012d024ef374c0308469
MD5 5211ca5cccf33fe489a9511dbf37cc7e
BLAKE2b-256 861f4b508886d3e545aab614c20dbd5f9b1dcb7645dc180942c77474c999cf45

See more details on using hashes here.

File details

Details for the file httpstan-4.13.0-cp311-cp311-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp311-cp311-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 d0c0807843d75629f61876319d5715e6a4efcc0c7b55fdbaa970baa86e7d2b09
MD5 57b926c9b9aeb026a83c95d918263893
BLAKE2b-256 0310811a8cc58cfefd114b85197444b55ad97e9fa1905e452d92ee04cd61f80f

See more details on using hashes here.

File details

Details for the file httpstan-4.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fc16ee696c16aa57e35e588b5b3219224a43897589861bdd6e1e610f7b6197b2
MD5 082f68216b68bb0729ac04a0f5665e02
BLAKE2b-256 a6770492bf3a332d24ea986acb74c9b1258d17a2636e7f681ebd6db74de49db5

See more details on using hashes here.

File details

Details for the file httpstan-4.13.0-cp310-cp310-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for httpstan-4.13.0-cp310-cp310-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 d74077e482391586da9510847bd56cb7feb6fbed8b32bfc741c9067f1bb5cd17
MD5 2730c49dade85663fe00bee0b2dda7f0
BLAKE2b-256 eb349df0d62d250c8ab58a137b4f957d1962072c4c3aa1abb51240bf3a2fad44

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page