{"id":21409280,"url":"https://github.com/acerbilab/pyibs","last_synced_at":"2026-05-19T00:36:28.648Z","repository":{"id":172780776,"uuid":"585930016","full_name":"acerbilab/pyibs","owner":"acerbilab","description":"Inverse binomial sampling for efficient log-likelihood estimation of simulator models in Python","archived":false,"fork":false,"pushed_at":"2023-06-05T14:13:32.000Z","size":961,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-23T04:28:26.829Z","etag":null,"topics":["likelihood-free","log-likelihood","python","sampling","simulation-model"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/acerbilab.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":"2023-01-06T13:28:17.000Z","updated_at":"2024-06-21T10:37:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"f6df79e6-3438-4c5f-8abb-541f77c1b01e","html_url":"https://github.com/acerbilab/pyibs","commit_stats":null,"previous_names":["juls-art/pyibs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerbilab%2Fpyibs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerbilab%2Fpyibs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerbilab%2Fpyibs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerbilab%2Fpyibs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acerbilab","download_url":"https://codeload.github.com/acerbilab/pyibs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243908185,"owners_count":20367368,"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":["likelihood-free","log-likelihood","python","sampling","simulation-model"],"created_at":"2024-11-22T17:24:29.294Z","updated_at":"2026-05-19T00:36:28.603Z","avatar_url":"https://github.com/acerbilab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# PyIBS: Inverse Binomial Sampling in Python\n\n## What is it?\n\nPyIBS is a a Python implementation of the Inverse Binomial Sampling (IBS) estimator for obtaining unbiased, efficient estimates of the log-likelihood of a model by simulation, originally implemented [in MATLAB](https://github.com/acerbilab/ibs). [[1](#references)]\n\n## When should I use PyIBS?\n\nThe typical scenario is the case in which you have a *simulator*, that is a model from which you can randomly draw synthetic observations (for a given parameter vector), but cannot evaluate the log-likelihood analytically or numerically. In other words, IBS affords likelihood-based inference for models without explicit likelihood functions (also known as implicit models).\n\nIBS is commonly used as a part of an algorithm for maximum-likelihood estimation or Bayesian inference.\n\n- For maximum-likelihood (or maximum-a-posteriori) estimation, we recommend to use PyIBS combined with [Bayesian Adaptive Direct Search (PyBADS)](https://github.com/acerbilab/pybads).\n- For Bayesian inference of posterior distributions and model evidence, we recommend to use PyIBS with [Variational Bayesian Monte Carlo (PyVBMC)](https://github.com/acerbilab/pyvbmc).\n\nThis folder contains Python implementations and examples of IBS.\n\n## Installation\n\nPyIBS is available via `pip` and `conda-forge`.\n\n1. Install with:\n    ```console\n    python -m pip install pyibs\n    ```\n    or:\n    ```console\n    conda install --channel=conda-forge pyibs\n    ```\n    PyIBS requires Python version 3.9 or newer.\n\n### Quick start\n\nThe typical workflow of PyIBS follows four steps:\n\n1. Define the model function (a generative function from which you can draw synthetic observations);\n2. Setup the problem configuration (response matrix, stimulus matrix);\n3. Initialize and then run the estimator OR use the estimator as objective function in an optimization (for example [Bayesian Adaptive Direct Search (PyBADS)](https://github.com/acerbilab/pybads) or [Variational Bayesian Monte Carlo (PyVBMC)](https://github.com/acerbilab/pyvbmc));\n4. Examine and visualize the results.\n\nInitializing and running the estimator in step 3 only involves a couple of lines of code:\n\n```\nfrom pyibs import IBS\n# ...\nibs = IBS(sample_from_model, response_matrix, design_matrix)\nneg_logl = ibs(params, num_reps, additional_output, return_positive)\n```\n\nwith input arguments for the initialization:\n\n- ``sample_from_model``: model function, it takes as input a vector of parameters ``params`` and ``design_matrix`` and generates a matrix of simulated model responses (one row per trial, corresponding to rows of design_matrix);\n- ``response_matrix``: the observed responses;\n- ``design_matrix``: used as input to sample from the model;\nand following optional input arguments:\n- ``vectorized``: indicates whether to use a vectorized sampling algorithm with acceleration. If it is not given, the vectorized algorithm is used if the time to generate samples for each trial is less than ``vectorized_threshold``.\n- ``acceleration``: acceleration factor for vectorized sampling, default = ``1.5``;\n- ``num_samples_per_call``: number of starting samples per trial per function call. If equal to ``0`` the number of starting samples is chosen automatically, default = ``0``;\n- ``max_iter``: maximum number of iterations (per trial and estimate), default = ``1e5``;\n- ``max_time``: maximum time for an IBS call (in seconds), default = ``np.inf``;\n- ``max_samples``: maximum number of samples per function call, default = ``1e4``;\n- ``acceleration_threshold``: threshold at which to stop accelerating (in seconds), default = ``0.1``;\n- ``vectorized_threshold``: maximum threshold for using the vectorized algorithm (in seconds), default = ``0.1``;\n- ``max_mem``: maximum number of samples for the vectorized implementation, default = ``1e6``;\n- ``neg_logl_threshold``: threshold for the negative log-likelihood (works differently in vectorized version), default = ``np.inf``.\n\n\nInput arguments for running the estimator:\n\n- ``params``: parameter vector used to simulate the model's responses;\n- ``num_reps``: number of independent log-likelihood estimates to calculate, an average of the repetitions is returned. If not given, it is 10;\n- ``additional_output``: The output type, if not given then only the negative log-likelihood is returned. If equal to:\n  - ``var`` then the negative log-likelihood and the variance of the negative log-likelihood estimate is returned,\n  - ``std`` then the negative log-likelihood and the standard deviation of the negative log-likelihood estimate is returned,\n  - ``full`` then a dictionary type output is returned with additional information about the estimate;\n- ``return_positive``: boolean that indicates whether to return the positive log-likelihood. If not given, the negative log-likelihood estimate is returned;\n\nThe outputs are:\n\n- ``neg_logl``: the negative log-likelihood (if return_positive is False else positive log-likelihood);\n- ``neg_logl_var``: the variance of the negative log-likelihood estimate (if additional_output is ``var``);\n- ``neg_logl_std``: the standard deviation of negative log-likelihood estimate (if additional_output is ``std``);\nIf ``additional_output`` is ``full`` then a dictionary type output is returned with following additional information about the sampling:\n- ``exit_flag``: the exit flag (0 = correct termination, 1 = negative log-likelihood threshold reached, 2 = maximum runtime reached, 3 = maximum iterations reached);\n- ``message``: the exit message;\n- ``elapsed_time``: the elapsed time (in seconds);\n- ``num_samples_per_trial``: the number of samples per trial;\n- ``fun_count``: the number of ``sample_from_model`` function evaluations in the call;\n\n## Code\n\n- `ibs_basic.py` is a bare-bone implementation of IBS for didactic purposes.\n- `psycho_generator.py` and `psycho_neg_logl.py` are functions implementing, respectively, the generative model (simulator) and the negative log-likelihood function for the orientation discrimination model used in the example notebooks.\n- `ibs.py` is an advanced vectorized implementation of IBS, which supports several advanced features: it allows for repeated sampling, early stopping through a log-likelihood threshold and to return variance or standard deviation of the estimation.\n  - Initialize an IBS object by passing it a generative model, a response matrix and a design matrix. Call the object with a parameter to return an estimate of the *negative* log-likelihood.\n  - Note that by default it returns the *negative* log-likelihood as it is meant to be used with an optimization method such as [PyBADS](https://github.com/acerbilab/pybads). Set `return_positive = true` to return the *positive* log-likelihood.\n  - If you want to run  with [PyVBMC](https://github.com/acerbilab/pyvbmc), note that you need to pass the following arguments when calling the IBS object\n    - `return_positive = true` to return the *positive* log-likelihood;\n    - `additinal_output = std` to return as second output the standard deviation of the estimate.\n- `ibs_simple_example.ipynb` is an example notebook for running `ibs_basic.py`. It is only for didactic purposes.\n- `ibs_example_1_basic_use.ipynb` is an example notebook for running `ibs.py`. It contains an example on how to run the estimations and how to obtain different output types. It contains examples using the orientation discrimination model and one using a binomial model. The unbiasedness of the estimator is checked; this notebook is only for didactic purposes.\n- `ibs_example_2_parameter_estimation.ipynb` is a full working example usage of IBS. It requires the installation of [PyBADS](https://github.com/acerbilab/pybads) and [PyVBMC](https://github.com/acerbilab/pyvbmc).\n\n\n## References\n\n1. van Opheusden\\*, B., Acerbi\\*, L. \u0026 Ma, W.J. (2020). Unbiased and efficient log-likelihood estimation with inverse binomial sampling. *PLoS Computational Biology* 16(12): e1008483. (\\* equal contribution) ([link](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008483))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facerbilab%2Fpyibs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facerbilab%2Fpyibs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facerbilab%2Fpyibs/lists"}