{"id":26482607,"url":"https://github.com/rfeinman/pybpl","last_synced_at":"2025-03-20T04:14:29.353Z","repository":{"id":38448931,"uuid":"119080139","full_name":"rfeinman/pyBPL","owner":"rfeinman","description":"Python implementation of Bayesian Program Learning tools (with PyTorch)","archived":false,"fork":false,"pushed_at":"2022-06-27T17:38:17.000Z","size":45608,"stargazers_count":67,"open_issues_count":0,"forks_count":11,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-02-27T22:37:30.523Z","etag":null,"topics":["bayesian-methods","differentiable-rendering","program-learning","pytorch","splines"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rfeinman.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}},"created_at":"2018-01-26T17:11:07.000Z","updated_at":"2024-01-08T10:38:30.000Z","dependencies_parsed_at":"2022-08-19T15:52:00.701Z","dependency_job_id":null,"html_url":"https://github.com/rfeinman/pyBPL","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfeinman%2FpyBPL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfeinman%2FpyBPL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfeinman%2FpyBPL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfeinman%2FpyBPL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rfeinman","download_url":"https://codeload.github.com/rfeinman/pyBPL/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244547578,"owners_count":20470104,"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":["bayesian-methods","differentiable-rendering","program-learning","pytorch","splines"],"created_at":"2025-03-20T04:14:28.522Z","updated_at":"2025-03-20T04:14:29.341Z","avatar_url":"https://github.com/rfeinman.png","language":"Python","readme":"# pyBPL: Python-based Bayesian Program Learning\n\npyBPL is a package of tools to implement Bayesian Program Learning (BPL) in Python 3 using PyTorch backend. \nThe [original BPL implementation](https://github.com/brendenlake/BPL) was written in MATLAB (see Lake et al. (2015): \"Human-level concept learning through probabilistic program induction\"). \nI'm a Ph.D. student with Brenden Lake and I've developed this library for our [ongoing modeling work](https://lake-lab.github.io/projects/#concept-learning-in-minds-and-machines).\nAt the moment, only the forward generative model is complete; inference algorithms are still in the works (contributions welcome!). \nThe library is still experimental and under heavy development.\n\nThe key components of this repository are:\n1. A fully-differentiable implementation of BPL character learning tools including symbolic rendering, spline fitting/evaluation, and model scoring (log-likelihoods).\n2. A generalized framework for representing concepts and conceptual background knowledge as probabilistic programs. Character concepts are one manifestation of the framework, included here as the preliminary use case.\n\nI am thankful to Maxwell Nye, Mark Goldstein and Tuan-Anh Le for their help developing this library.\n\n\n## Setup\n\nThis code repository requires Python 3 and PyTorch \u003e= 1.0.0. A full list of requirements can be found in `requirements.txt`. \nTo install, first run the following command to clone the repository into a folder of your choice:\n```\ngit clone https://github.com/rfeinman/pyBPL.git\n```\nThen, run the following command to install the package:\n```\npython setup.py install\n```\n\n\n## Documentation\nIn order to generate the documentation site for the pyBPL library, execute the\nfollowing commands from the root folder:\n```\ncd docs/\nmake html\n```\nHELP WANTED: documentation build is broken right now, needs to be fixed.\n\n\n## Usage Example\n\nThe following code loads the BPL model with pre-defined hyperparameters \nand samples a token\n\n```python\nfrom pybpl.library import Library\nfrom pybpl.model import CharacterModel\n\n# load the hyperparameters of the BPL graphical model (i.e. the \"library\")\nlib = Library(use_hist=True)\n\n# create the BPL graphical model\nmodel = CharacterModel(lib)\n\n# sample a character type from the prior P(Type) and score its log-probability\nchar_type = model.sample_type()\nll_type = model.score_type(char_type)\n\n# sample a character token from P(Token | Type=type) and score its log-probability\nchar_token = model.sample_token(char_type)\nll_token_given_type = model.score_token(char_type, char_token)\n\n# sample an image from P(Image | Token=token)\nimage = model.sample_image(char_token)\nll_image_given_token = model.score_image(char_token, image)\n\n```\n\n## Status Notes\n\n#### General\n\nAll functions required to sample character types, tokens and images are now\ncomplete. \nCurrently, independent relations sample their position from a uniform distribution over the entire image window by default. \nTo use the original spatial histogram from BPL, make sure to load the Library object with `use_hist=True`. \nNote, however, that log-likelihoods for spatial histograms are not differentiable.\n\nMy Python implementations of the bottum-up image parsing algorithms are not yet complete (HELP WANTED! see `pybpl/bottomup` for current status).\nHowever, I have provided some wrapper functions that call the original matlab code using the [MATLAB Engine API for Python](https://www.mathworks.com/help/matlab/matlab-engine-for-python.html). \nThese functions are located in `pybpl/matlab/bottomup`.\nYou must have the MATLAB bindings installed to use this code.\n\n\n#### Library\n\nThe library contains all of the parameters of the character learning BPL\nmodel. These parameters have been learned from the Omniglot dataset. \nThe library data is stored as a \nseries of `.mat` files in the subfolder `lib_data/`. \nI've included a Matlab script, `process_library.m`, which can be\nrun inside the original BPL repository to \nobtain this folder of files. For an example of how to load the library, see\n`examples/generate_character.py`.\n\n\n## Demos\nCurrently there are 3 working demos, both found in the `examples` subfolder.\n\n#### 1. generate character\n\nYou can generate a character type and sample a few tokens of the type by running the following command from the root folder:\n```\npython examples/generate_character.py\n```\nThe script will sample a character type from the prior and then sample 4 tokens of the type, displaying the images.\n\n#### 2. optimize character type\nYou can generate a character type and then optimize its parameters to maximize the likelihood of the type under the prior by running the following command from the root folder:\n```\npython examples/optimize_type.py\n```\nOptionally, you may add the integer parameter `--ns=\u003cint\u003e` to specify how many strokes you would like the generated character type to have.\n\n#### 3. bottom-up parsing\nTo use the bottom-up parsing code, you must meet the following prerequisites:\n- You must have an active MATLAB installation and must have installed the [MATLAB Engine API for Python](https://www.mathworks.com/help/matlab/matlab-engine-for-python.html).\n- You must download the [BPL matlab repository](https://github.com/brendenlake/BPL) and all of its prerequisites, including the Lightspeed toolbox. The BPL repo must be added to your matlab path (alternatively, you may set a BPL_PATH environment variable as `export BPL_PATH=\"/path/to/BPL\"`).\n\nWith these prerequisites met, you can produce bottom-up parses using the skeleton extraction + random walks algorithm with the following example script:\n```\npython examples/parse_image.py\n```\n\n\n\n## Citing\nIf you use pyBPL for your research, you are encouraged (though not required) to cite this repository with the following BibTeX reference:\n\n```\n@misc{feinman2020pybpl,\n    title={{pyBPL}},\n    author={Feinman, Reuben},\n    year={2020},\n    version={0.1},\n    url={https://github.com/rfeinman/pyBPL}\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfeinman%2Fpybpl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frfeinman%2Fpybpl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfeinman%2Fpybpl/lists"}