{"id":18750357,"url":"https://github.com/ntia/gilbert-elliot-model","last_synced_at":"2025-09-01T10:31:02.632Z","repository":{"id":78086745,"uuid":"546160482","full_name":"NTIA/gilbert-elliot-model","owner":"NTIA","description":"Tools for manipulating the Gilbert-Elliot burst error model.","archived":false,"fork":false,"pushed_at":"2022-12-14T16:51:19.000Z","size":581,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-07T17:12:24.703Z","etag":null,"topics":["bit-errors","bursty-errors","error-statistics","gilbert-elliot","markov-chain","packet-loss","software-simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NTIA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2022-10-05T16:22:21.000Z","updated_at":"2024-10-04T08:59:24.000Z","dependencies_parsed_at":"2023-03-09T02:15:48.882Z","dependency_job_id":null,"html_url":"https://github.com/NTIA/gilbert-elliot-model","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NTIA%2Fgilbert-elliot-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NTIA%2Fgilbert-elliot-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NTIA%2Fgilbert-elliot-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NTIA%2Fgilbert-elliot-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NTIA","download_url":"https://codeload.github.com/NTIA/gilbert-elliot-model/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231684210,"owners_count":18410622,"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":["bit-errors","bursty-errors","error-statistics","gilbert-elliot","markov-chain","packet-loss","software-simulation"],"created_at":"2024-11-07T17:11:31.910Z","updated_at":"2024-12-28T22:31:41.422Z","avatar_url":"https://github.com/NTIA.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gilbert-elliot-model\n[![DOI](https://zenodo.org/badge/546160482.svg)](https://zenodo.org/badge/latestdoi/546160482)\n\n\nThe Gilbert-Elliot burst error model is a popular and effective tool for treating bursty (non-independent) errors in communication links.\nThis software accompanies the following publication: Pieper J; Voran S, [Relationships between Gilbert-Elliot Burst Error Model Parameters and Error Statistics](https://its.ntia.gov/publications/3298.aspx), NTIA Technical Memo TM-23-565. \nIt provides functions for simulating errors using the model and analyzing error arrays to estimate model parameters.\nIt can also make an estimate of the most likely version of the model to emit a given observation: the two-parameter $(p, r)$, three-parameter $(p, r, h)$ or four-parameter $(p, r, k, h)$.\n\nUpon installation the package provides a command line interface which allows users to determine valid model control values and simulate errors.\n\n## Installation\nNavigate to the directory containing the source code and run:\n\n```\npip install .\n```\n\n## Documentation\nThe software includes doc strings for all methods, viewable via `help(method)`.\nFor example to see the help for the `simulate` method:\n```\nimport gilbert_elliot_model as ge\nprint(help(ge.simulate))\n```\n\nHere we list the primary methods included in the package with a brief description of each:\n* `simulate` - Simulate errors using the Gilbert-Elliot burst model and a variety of controls as parameters.\n* `determine_model` - Determine version of Gilbert-Elliot model with highest likelihood of emitting observation.\n* `model_error_statistics` - Determine error statistics given model parameters.\n* `data_error_statistics` - Measure error statsitics from error pattern.\n* `fit_hmm` - Fit two-state Hidden Markov model to data in observation.\n* `valid_regions` - Determine valid ranges for Gilbert-Elliot model controls and error statistics.\n* `valid_parameters` - Return valid parameters either as a list of pairs or a set of all parameters.\n\n### Selecting a model\n\nIt is worth noting that more than one set of model parameters could yield the same or very similar error patterns.\nThus, unless there is a good reason for selecting a more complicated model (such as the three- or four-parameter) models, we suggest using the two-parameter model.\nMore complicated models are valid and interesting provided there is good reasoning behind their use. \nWe provide the `determine_model` method as an additional tool in this process, but do not claim that it should be the primary decision maker as to which model is most appropriate in a given situation.\n\n## Stochastic Behavior\nThe functions `fit_hmm` and `determine_model` are stochastic in nature and also fairly slow, making them unsuitable for standard unit testing.\nTo understand the functionality of each method and ensure they are working as intended, a number of random tests were performed and their results analyzed.\nThese analyses are viewable at\n[fit hmm distribution analysis](https://nbviewer.org/github/NTIA/gilbert-elliot-model/blob/main/tests/distribution_analysis.ipynb)\nand\n[determine model analysis](https://nbviewer.org/github/NTIA/gilbert-elliot-model/blob/main/tests/determine_model_tests.ipynb)\nrespectively.\n\n## Command Line Interface\nUpon installation, a command line tool called `gilbert-elliot` is installed and added to the path.\nIt allows users to determine valid model control values and simulate error patterns.\nTo see all options for the command line tool run \n\n```\ngilbert-elliot --help\n```\n\n### Examples\n\n#### Valid region in three-parameter model\nHere we fix the proportion of time spent in the Bad state, $\\pi_B$, and the expected burst length, $L_1$, and then determine the valid region for the error rate, $\\bar{x}$.\n```\ngilbert-elliot --pi_B 0.7 --L1 3 --free-parameter xbar\n```\nThis outputs: `xbar must be in Interval.Lopen(0.466666666666667, 0.700000000000000)`.\n\n#### Valid region in the four-parameter model\nHere we fix the error rate, $\\bar{x}$, the proportion of time spent in the Bad state, $\\pi_B$, and the expected burst length, $L_1$, and then determine the valid region for the conditional error rate in the Bad state, $h$.\n```\ngilbert-elliot --xbar 0.6 --pi_B 0.7 --L1 3 --free-parameter h\n```\nThis outputs: `h must be in Union(Interval.Ropen(0.142857142857143, 0.269069265858405), Interval.open(0.530930734141595, 0.571428571428572))`.\n\n#### Translating error statistics into model controls\nBuilding on the last example we select a value of $h$ from the valid region above and translate these error statistic model controls into the standard set of model parameters, $(p, r, k, h)$. \n```\ngilbert-elliot --xbar 0.6 --pi_B 0.7 --L1 3 --h 0.55\n```\nThis outputs: `Model Parameters: {'p': 0.166666666666667, 'r': 0.0714285714285714, 'h': 0.550000000000000, 'k': 0.0500000000000000}`.\n\n#### Simulating an error pattern\nThis further builds on the previous example by using the model controls to generate a length 10000 error pattern and save it to `myerrors.csv`.\n```\ngilbert-elliot --xbar 0.6 --pi_B 0.7 --L1 3 --h 0.55 --simulate --n_observations 10000 --output myerrors.csv\n```\n\n\n\n## Contact\nFor questions contact Jaden Pieper, jpieper@ntia.gov\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntia%2Fgilbert-elliot-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fntia%2Fgilbert-elliot-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntia%2Fgilbert-elliot-model/lists"}