{"id":18366580,"url":"https://github.com/ajcr/urn","last_synced_at":"2025-04-06T16:32:12.848Z","repository":{"id":186558426,"uuid":"655333854","full_name":"ajcr/urn","owner":"ajcr","description":"Terminal-based multivariate hypergeometric calculator with a simple query language interface","archived":false,"fork":false,"pushed_at":"2023-11-12T22:32:09.000Z","size":167,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T03:31:41.878Z","etag":null,"topics":["calculator","hypergeometric-distribution","shell"],"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/ajcr.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}},"created_at":"2023-06-18T15:29:30.000Z","updated_at":"2023-12-21T12:39:51.000Z","dependencies_parsed_at":"2023-11-12T19:42:53.744Z","dependency_job_id":null,"html_url":"https://github.com/ajcr/urn","commit_stats":null,"previous_names":["ajcr/urn"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajcr%2Furn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajcr%2Furn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajcr%2Furn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajcr%2Furn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajcr","download_url":"https://codeload.github.com/ajcr/urn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247512873,"owners_count":20950946,"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":["calculator","hypergeometric-distribution","shell"],"created_at":"2024-11-05T23:18:20.395Z","updated_at":"2025-04-06T16:32:12.489Z","avatar_url":"https://github.com/ajcr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# urn\n\n![PyPI version](https://img.shields.io/pypi/v/urn-calculator.svg?color=brightgreen)\n\nA fast multivariate hypergeometric calculator with an intuitive language interface.\n\nFind the probability of drawing a target set of objects from a collection, either with or without replacement.\n\nDisplay the results as a table or a plot in your terminal.\n\n## Installing the calculator\n\nThe calculator can be installed via pypi:\n```\npip install urn-calculator\n```\nSome calculations may be faster with the [gmpy2](https://pypi.org/project/gmpy2/) library installed. This is optional:\n```\npip install gmpy2\n```\n\n## Using the calculator\n\nThe `urn` program can be run as a shell:\n```\n$ urn\nurn\u003e\n```\nComputations are described in the following form:\n```\nPROBABILITY DRAW [number of things]\nFROM [collection]\nWHERE [zero or more constraints on draw];\n```\nTo see the total count of possible draws, replace `PROBABILITY` with `COUNT`.\n\nBy default, the computation assumes that draws are made without replacement. This can be changed by specifying `DRAW [number of things] WITH REPLACEMENT`.\n\nLet's look at some examples.\n\nSuppose we want to draw _without replacement_ from an urn containing coloured marbles. We want to see the probability that we see _at least_ 2 red and _at most_ 5 blue (and we don't care about the green marbles):\n```\nurn\u003e PROBABILITY DRAW FROM red=5, blue=7, green=3 WHERE red \u003e= 2 AND blue \u003c= 5;\n```\nThis returns the table of probabilities:\n```\n  draw size    probability\n-----------  -------------\n          2      0.0952381\n          3      0.241758\n          4      0.406593\n          5      0.566434\n          6      0.706294\n          7      0.818182\n          8      0.888889\n          9      0.895105\n         10      0.818182\n         11      0.661538\n         12      0.446154\n         13      0.2\n\n```\nNote that the query keywords such as `FROM` and `WHERE` are not case sensitive. A semicolon `;` ends the query. Whitespace is ignored.\n\nWe didn't specify a size for our draw, so the program returned _all_ draw sizes with a non-zero probability of meeting our constraints.\n\nBy default `urn` returns float numbers for probabilities. We can make it show exact rational numbers by appending `SHOW RATIONAL`:\n```\nurn\u003e PROBABILITY DRAW 1..5 FROM red=5, blue=7, green=3\n     WHERE red \u003e= 2 AND blue \u003c= 5\n     SHOW RATIONAL;\n  draw size  probability\n-----------  -------------\n          1  0\n          2  2/21\n          3  22/91\n          4  37/91\n          5  81/143\n```\nHere we also specified a range `1..5` for the draw size. Single draw sizes (e.g. `5`) are also permitted.\n\nIt's often useful to create a plot (`SHOW PLOT`) to see the optimal draw size at a glance:\n```\nurn\u003e PROBABILITY DRAW FROM red=5, blue=7, green=3\n     WHERE red \u003e= 2 AND blue \u003c= 5\n     SHOW PLOT;\n┌────────────────────────────────────────────────────────────┐\n│                                ▝     ▘                     │ \n│                           ▘               ▝                │ \n│                                                            │ \n│                     ▗                                      │ \n│                                                 ▘          │ \n│                                                            │ \n│                ▘                                           │ \n│                                                            │ 0.5\n│                                                      ▖     │ \n│          ▝                                                 │ \n│                                                            │ \n│                                                            │ \n│     ▝                                                      │ \n│                                                           ▝│ \n│                                                            │ \n│▘                                                           │ \n│▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│ 0.0\n└────────────────────────────────────────────────────────────┘\n   2             5             7           10            12\n```\nTo see the same calculation, but in the case where we draw _with replacement_, we must specify a range and use the `WITH REPLACEMENT` modifier:\n\n```\nurn\u003e PROBABILITY DRAW 2..13 WITH REPLACEMENT\n     FROM red=5, blue=7, green=3\n     WHERE red \u003e= 2 AND blue \u003c= 5\n     SHOW PLOT;\n┌────────────────────────────────────────────────────────────┐\n│                           ▖    ▝     ▖                     │ \n│                                                            │ \n│                     ▗                     ▝                │ \n│                                                            │ \n│                                                 ▘          │ \n│                ▘                                           │ \n│                                                      ▖     │ 0.5\n│                                                            │ \n│          ▝                                                ▗│ \n│                                                            │ \n│                                                            │ \n│     ▝                                                      │ \n│                                                            │ \n│                                                            │ \n│▖                                                           │ \n│                                                            │ \n│▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│ 0.0\n└────────────────────────────────────────────────────────────┘\n   2             5             7           10            12\n```\n\nFinally, we can use `OR` to specify alternative constraints on our draw.\n```\nurn\u003e PROBABILITY DRAW 1..10 FROM red=5, blue=7, green=3\n     WHERE red  \u003e= 2 AND blue  \u003c= 3\n        OR blue \u003e  0 AND green  \u003e 1\n        OR blue =  2 AND red   \u003e= 2 AND green \u003c= 2\n     SHOW PLOT;\n┌────────────────────────────────────────────────────────────┐\n│                                       ▗      ▝      ▘     ▝│ 1.0\n│                                                            │ \n│                                 ▘                          │ \n│                    ▖                                       │ \n│                          ▗                                 │ \n│             ▖                                              │ \n│                                                            │ \n│                                                            │ \n│                                                            │ 0.5\n│                                                            │ \n│                                                            │ \n│      ▗                                                     │ \n│                                                            │ \n│                                                            │ \n│                                                            │ \n│                                                            │ \n│▖▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│ 0.0\n└────────────────────────────────────────────────────────────┘\n       2             4            6            8           10\n```\nTo exit the shell, type `quit`:\n```\nurn\u003e quit;\nExiting urn shell.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajcr%2Furn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajcr%2Furn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajcr%2Furn/lists"}