{"id":16518973,"url":"https://github.com/zoj613/htnorm","last_synced_at":"2025-03-23T13:32:24.597Z","repository":{"id":48485541,"uuid":"309504603","full_name":"zoj613/htnorm","owner":"zoj613","description":"Fast and Exact Simulation of Hyperplane-Truncated Multivariate Normal Distributions, with C, Python and R interfaces.","archived":false,"fork":false,"pushed_at":"2023-05-23T23:27:12.000Z","size":143,"stargazers_count":11,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T20:54:04.797Z","etag":null,"topics":["cholesky-decomposition","conditional-distribution","high-dimensional-regression","multivariate-gaussian-distribution","truncated-distribution"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zoj613.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-02T21:55:14.000Z","updated_at":"2023-05-23T23:57:18.000Z","dependencies_parsed_at":"2024-10-28T16:15:48.449Z","dependency_job_id":"a7db583a-6219-4f31-a23f-f92f8d21b906","html_url":"https://github.com/zoj613/htnorm","commit_stats":{"total_commits":71,"total_committers":1,"mean_commits":71.0,"dds":0.0,"last_synced_commit":"da31350449c437bbffe2d30664c1d7a5f23e554c"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoj613%2Fhtnorm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoj613%2Fhtnorm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoj613%2Fhtnorm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoj613%2Fhtnorm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoj613","download_url":"https://codeload.github.com/zoj613/htnorm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245108286,"owners_count":20562019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cholesky-decomposition","conditional-distribution","high-dimensional-regression","multivariate-gaussian-distribution","truncated-distribution"],"created_at":"2024-10-11T16:44:28.573Z","updated_at":"2025-03-23T13:32:24.248Z","avatar_url":"https://github.com/zoj613.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# htnorm\n\nThis repo provides a C implementation of a fast and exact sampling algorithm for a \nmultivariate normal distribution (MVN) truncated on a hyperplane as described [here][1]\n\nThis repo implements the following from the paper:\n\n- Efficient sampling from a MVN truncated on a hyperplane: \n\n    ![hptrunc](https://latex.codecogs.com/svg.latex?%5Cmathbf%7Bx%7D%20%5Csim%20%5Cmathcal%7BN%7D_%7B%5Cmathcal%7BS%7D%7D%28%5Cmathbf%7B%5Cmu%7D%2C%20%5Cmathbf%7B%5CSigma%7D%29%3B%20%5Chspace%7B2mm%7D%20%5Cmathcal%7BS%7D%20%3D%20%5C%7B%5Cmathbf%7Bx%7D%20%3A%20%5Cmathbf%7BG%7D%5Cmathbf%7Bx%7D%20%3D%20%5Cmathbf%7Br%7D%5C%7D%2C%20%5Cmathbf%7BG%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bk_2%20%5Ctimes%20k%7D%2C%20rank%28%5Cmathbf%7BG%7D%29%20%3D%20k_2%20%3C%20k)\n\n- Efficient sampling from a MVN with a stuctured precision matrix that is a sum of an invertible matrix and a low rank matrix: \n\n    ![struc](https://latex.codecogs.com/svg.latex?%5Cmathbf%7Bx%7D%20%5Csim%20%5Cmathcal%7BN%7D%5C%5B%5Cmathbf%7B%5Cmu%7D%2C%20%28%5Cmathbf%7BA%7D%20\u0026plus;%20%5Cmathbf%7B%5CPhi%7D%5ET%5Cmathbf%7B%5COmega%7D%5Cmathbf%7B%5CPhi%7D%29%5E%7B-1%7D%5C%5D%3B%20%5Chspace%7B2mm%7D%20%5Cmathbf%7B%5CPhi%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bn%20%5Ctimes%20p%7D%2C%20%5Cmathbf%7B%5COmega%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bn%20%5Ctimes%20n%7D%2C%20%5Cmathbf%7BA%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bp%20%5Ctimes%20p%7D)\n\n- Efficient sampling from a MVN with a structured precision and mean:\n\n    ![strucmean](https://latex.codecogs.com/svg.latex?%5Cmathbf%7Bx%7D%20%5Csim%20%5Cmathcal%7BN%7D%5CBig%5C%5B%28%5Cmathbf%7BA%7D%20\u0026plus;%20%5Cmathbf%7B%5CPhi%7D%5ET%5Cmathbf%7B%5COmega%7D%5Cmathbf%7B%5CPhi%7D%29%5E%7B-1%7D%5Cmathbf%7B%5CPhi%7D%5ET%5Cmathbf%7B%5COmega%7D%5Cmathbf%7Bt%7D%2C%20%28%5Cmathbf%7BA%7D%20\u0026plus;%20%5Cmathbf%7B%5CPhi%7D%5ET%5Cmathbf%7B%5COmega%7D%5Cmathbf%7B%5CPhi%7D%29%5E%7B-1%7D%5CBig%5C%5D%3B%20%5Chspace%7B2mm%7D%20%5Cmathbf%7B%5COmega%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bn%20%5Ctimes%20n%7D%2C%20%5Cmathbf%7BA%7D%20%5Cin%20%5Cmathcal%7BR%7D%5E%7Bp%20%5Ctimes%20p%7D)\n\nThe algorithms implemented have the following practical applications:\n- Topic models when unknown parameters can be interpreted as fractions.\n- Admixture models\n- discrete graphical models\n- Sampling from the posterior distribution of an Intrinsic Conditional Autoregressive prior [icar][8]\n- Sampling from the posterior conditional distributions of various bayesian regression problems.\n\n\n## Dependencies\n\n- A C compiler that implements the C99 standard or later\n- An installation of `LAPACK`.\n\n## Usage\n\nBuilding a shared library of `htnorm` can be done with the following:\n```bash\n# optionally set path to LAPACK shared library\n$ export LIBS_DIR=\"some/path/to/lib/\"\n$ make lib\n```\nAfterwards the shared library will be found in a `lib/` directory of the project root,\nand the library can be linked dynamically via `-lhtnorm`.\n\nThe puplic interface exposes the samplers through the function declarations\n```C\n int htn_hyperplane_truncated_mvn(rng_t* rng, const ht_config_t* conf, double* out);\n int htn_structured_precision_mvn(rng_t* rng, const sp_config_t* conf, double* out);\n```\n\nThe details of the parameters are documented in ther header files [\"htnorm.h\"][4].\n\nRandom number generation is done using [PCG64][2] or [Xoroshiro128plus][3] bitgenerators. \nThe interface allows using a custom bitgenerator, and the details are documented in the header file \n[\"rng.h\"][5].\n\n## Example\n```C\n#include \"htnorm.h\"\n\nint main (void)\n{\n    ...\n    // instantiate a random number generator\n    rng_t* rng = rng_new_pcg64_seeded(12345);\n    ht_config_t config;\n    init_ht_config(\u0026config, ...);\n    double* out = ...; // array to store the samples\n    int res = htn_hyperplane_truncated_mvn(rng, \u0026config, out);\n    // res contains a number that indicates whether sampling failed or not.\n    ...\n    // finally free the RNG pointer at some point\n    rng_free(rng);\n    ...\n    return 0;\n}\n```\n\n## Python Interface\n[![PyPI - Wheel][10]](https://pypi.org/project/pyhtnorm/#files)\n[![PyPI][11]](https://pypi.org/project/pyhtnorm/)\n[![CI][12]](https://github.com/zoj613/htnorm/actions/workflows/build-and-test.yml)\n[![Codecov][13]](https://codecov.io/gh/zoj613/htnorm/)\n[![PyPI - License][14]](https://github.com/zoj613/htnorm/blob/main/LICENSE)\n\n\n### Dependencies\n- NumPy \u003e= 1.19.0\n\nA high level python interface to the library is also provided. Linux and MacOS users can \ninstall it using wheels via pip (thus not needing to worry about availability of C libraries).\nWindows OS is currently not supported.\n```bash\npip install -U pyhtnorm\n```\nWheels are not provided for MacOS. To install via pip, one can run the following commands:\n```bash\npip install -U pyhtnorm\n```\nAlternatively, one can install it from source using the following shell commands:\n\n```bash\n$ git clone https://github.com/zoj613/htnorm.git\n$ cd htnorm/\n$ export PYHT_LIBS_DIR=\u003csome directory with blas and lapack shared library files\u003e # this is optional\n$ pip install .\n```\n\nBelow is an example of how to use htnorm in python to sample from a multivariate\ngaussian truncated on the hyperplane ![sumzero](https://latex.codecogs.com/svg.latex?%5Cmathbf%7B1%7D%5ET%5Cmathbf%7Bx%7D%20%3D%200) (i.e. making sure the sampled values sum to zero). The python\ninterface is such that the code can be easily integrated into other existing libraries.\nSince `v1.0.0`, it supports passing a `numpy.random.Generator` instance as a parameter to aid reproducibility.\n\n```python\nfrom pyhtnorm import hyperplane_truncated_mvnorm, structured_precision_mvnorm\nimport numpy as np\n\nrng = np.random.default_rng()\n\n# generate example input\nk1, k2 = 1000, 1\ntemp = rng.random((k1, k1))\ncov = temp @ temp.T\nG = np.ones((k2, k1))\nr = np.zeros(k2)\nmean = rng.random(k1)\n\n# passing `random_state` is optional. If the argument is not used, a fresh\n# random generator state is instantiated internally using system entropy.\no = hyperplane_truncated_mvnorm(mean, cov, G, r, random_state=rng)\nprint(o.sum())  # verify if sampled values sum to zero\n# alternatively one can pass an array to store the results in\nhyperplane_truncated_mvnorm(mean, cov, G, r, out=o)\n```\n\nFor more information about the function's arguments, refer to its docstring.\n\nA pure numpy implementation is demonstrated in this [example script][9].\n\n\n## R Interface\n\nOne can also use the package in R. To install, use one the following commands:\n```R\ndevtools::install_github(\"zoj613/htnorm\")\npak::pkg_install(\"zoj613/htnorm\")\n```\n\nBelow is an R translation of the above python example:\n\n```R\nlibrary(htnorm)\n\n# make dummy data\nmean \u003c- rnorm(1000)\ncov \u003c- matrix(rnorm(1000 * 1000), ncol=1000)\ncov \u003c- cov %*% t(cov)\nG \u003c- matrix(rep(1, 1000), ncol=1000)\nr \u003c- c(0)\n\n# initialize the Generator instance\nrng \u003c- HTNGenerator(seed=12345, gen=\"pcg64\")\n\nsamples \u003c- rng$hyperplane_truncated_mvnorm(mean, cov, G, r)\n#verify if sampled values sum to zero\nsum(samples)\n\n# optionally pass a vector to store the results in\nout \u003c- rep(0, 1000)\nrng$hyperplane_truncated_mvnorm(mean, cov, G, r, out = out)\nsum(out)  #verify\n\nout \u003c- rep(0, 1000)\neig \u003c- eigen(cov)\nphi \u003c- eig$vectors\nomega \u003c- diag(eig$values)\na \u003c- diag(runif(length(mean)))\nrng$structured_precision_mvnorm(mean, a, phi, omega, a_type = \"diagonal\", out = out)\n```\n\n## Licensing\n\n`htnorm` is free software made available under the BSD-3 License. For details\nsee the [LICENSE][6] file.\n\n\n## References\n- Cong, Yulai; Chen, Bo; Zhou, Mingyuan. Fast Simulation of Hyperplane-Truncated \n   Multivariate Normal Distributions. Bayesian Anal. 12 (2017), no. 4, 1017--1037. \n   doi:10.1214/17-BA1052.\n- Bhattacharya, A., Chakraborty, A., and Mallick, B. K. (2016). \n  “Fast sampling with Gaussian scale mixture priors in high-dimensional regression.” \n  Biometrika, 103(4):985. \n\n\n[1]: https://projecteuclid.org/euclid.ba/1488337478\n[2]: https://www.pcg-random.org/\n[3]: https://en.wikipedia.org/wiki/Xoroshiro128%2B\n[4]: ./include/htnorm.h \n[5]: ./include/htnorm_rng.h\n[6]: ./LICENSE\n[7]: https://python-poetry.org/docs/pyproject/\n[8]: https://www.sciencedirect.com/science/article/abs/pii/S2211675317301574 \n[9]: ./examples/numpy_implementation.py\n[10]: https://img.shields.io/pypi/wheel/pyhtnorm?style=flat-square\n[11]: https://img.shields.io/pypi/v/pyhtnorm?style=flat-square\n[12]: https://img.shields.io/github/workflow/status/zoj613/htnorm/CI/main?style=flat-square\n[13]: https://img.shields.io/codecov/c/github/zoj613/htnorm?style=flat-square\n[14]: https://img.shields.io/pypi/l/pyhtnorm?style=flat-square\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoj613%2Fhtnorm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoj613%2Fhtnorm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoj613%2Fhtnorm/lists"}