{"id":16589341,"url":"https://github.com/sadrasabouri/pyrandwalk","last_synced_at":"2025-03-16T21:30:30.686Z","repository":{"id":47540771,"uuid":"345116340","full_name":"sadrasabouri/pyrandwalk","owner":"sadrasabouri","description":":walking:Python Library for Random Walks","archived":false,"fork":false,"pushed_at":"2024-05-02T17:58:22.000Z","size":201,"stargazers_count":20,"open_issues_count":9,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T05:51:15.510Z","etag":null,"topics":["education","educational","markov-chain","networkx","probabilistic-graphical-models","probability","python","random-walk","reinforcement-learning","reinforcement-learning-algorithms","simulation","stochastic-processes"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/sadrasabouri.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-06T14:41:24.000Z","updated_at":"2025-03-14T02:02:46.000Z","dependencies_parsed_at":"2023-01-21T15:48:22.092Z","dependency_job_id":null,"html_url":"https://github.com/sadrasabouri/pyrandwalk","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sadrasabouri%2Fpyrandwalk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sadrasabouri%2Fpyrandwalk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sadrasabouri%2Fpyrandwalk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sadrasabouri%2Fpyrandwalk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sadrasabouri","download_url":"https://codeload.github.com/sadrasabouri/pyrandwalk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243936411,"owners_count":20371509,"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":["education","educational","markov-chain","networkx","probabilistic-graphical-models","probability","python","random-walk","reinforcement-learning","reinforcement-learning-algorithms","simulation","stochastic-processes"],"created_at":"2024-10-11T23:08:31.100Z","updated_at":"2025-03-16T21:30:30.230Z","avatar_url":"https://github.com/sadrasabouri.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://github.com/sadrasabouri/pyrandwalk/raw/master/Otherfiles/logo.png\" width=\"300\" height=\"300\" alt=\"pyrandwalk-logo\"\u003e\u003cbr/\u003e\n\u003cbr/\u003e\n\u003ch1\u003e:walking: Python Library for Random Walks\u003c/h1\u003e\n\n\u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/built%20with-Python3-green.svg\" alt=\"built with Python3\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.codefactor.io/repository/github/sadrasabouri/pyrandwalk/overview/master\"\u003e\u003cimg src=\"https://www.codefactor.io/repository/github/sadrasabouri/pyrandwalk/badge/master\" alt=\"CodeFactor\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/sadrasabouri/pyrandwalk\"\u003e\n  \u003cimg src=\"https://codecov.io/gh/sadrasabouri/pyrandwalk/branch/master/graph/badge.svg\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://colab.research.google.com/github/sadrasabouri/pyrandwalk/blob/master/Document/Document.ipynb\"\u003e\n  \u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Document\"/\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\n----------\n## Table of contents\t\t\t\t\t\n   * [Overview](https://github.com/sadrasabouri/pyrandwalk#overview)\n   * [Installation](https://github.com/sadrasabouri/pyrandwalk#installation)\n   * [Usage](https://github.com/sadrasabouri/pyrandwalk#usage)\n   * [Contribution](https://github.com/sadrasabouri/pyrandwalk/blob/master/.github/CONTRIBUTING.md)\n   * [References](https://github.com/sadrasabouri/pyrandwalk#references)\n   * [Authors](https://github.com/sadrasabouri/pyrandwalk/blob/master/AUTHORS.md)\n   * [Changelog](https://github.com/sadrasabouri/pyrandwalk/blob/master/CHANGELOG.md)\n   * [License](https://github.com/sadrasabouri/pyrandwalk/blob/master/LICENSE)\n\n## Overview\n\n\u003cp align=\"justify\"\u003e\t\nPyrandwalk is an educational tool for simulating random walks, calculating the probability of given state sequences, etc. Random walk is a representation of the discrete-time, discrete-value Markov chain model used in stochastic processes.\n\u003c/p\u003e\n\n\n\u003ctable\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd align=\"center\"\u003ePyPI Counter\u003c/td\u003e\n\t\t\u003ctd align=\"center\"\u003e\u003ca href=\"http://pepy.tech/count/pyrandwalk\"\u003e\u003cimg src=\"http://pepy.tech/badge/pyrandwalk\"\u003e\u003c/a\u003e\u003c/td\u003e\n\t\u003c/tr\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd align=\"center\"\u003eGithub Stars\u003c/td\u003e\n\t\t\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/sadrasabouri/pyrandwalk\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/sadrasabouri/pyrandwalk.svg?style=social\u0026label=Stars\"\u003e\u003c/a\u003e\u003c/td\u003e\n\t\u003c/tr\u003e\n\u003c/table\u003e\n\n\n\n\u003ctable\u003e\n\t\u003ctr\u003e \n\t\t\u003ctd align=\"center\"\u003eBranch\u003c/td\u003e\n\t\t\u003ctd align=\"center\"\u003emaster\u003c/td\u003e\t\n\t\t\u003ctd align=\"center\"\u003edev\u003c/td\u003e\t\n\t\u003c/tr\u003e\n    \u003ctr\u003e\n\t\t\u003ctd align=\"center\"\u003eCI\u003c/td\u003e\n\t\t\u003ctd align=\"center\"\u003e\u003cimg src=\"https://github.com/sadrasabouri/pyrandwalk/workflows/CI/badge.svg?branch=master\"\u003e\u003c/td\u003e\n\t\t\u003ctd align=\"center\"\u003e\u003cimg src=\"https://github.com/sadrasabouri/pyrandwalk/workflows/CI/badge.svg?branch=dev\"\u003e\u003c/td\u003e\n\t\u003c/tr\u003e\n\u003c/table\u003e\n\n\n\n## Installation\n\n### Source code\n- Download [Version 1.1](https://github.com/sadrasabouri/pyrandwalk/archive/v1.1.zip) or [Latest Source ](https://github.com/sadrasabouri/pyrandwalk/archive/dev.zip)\n- Run `pip install -r requirements.txt` or `pip3 install -r requirements.txt` (Need root access)\n- Run `python3 setup.py install` or `python setup.py install` (Need root access)\n\n### PyPI\n\n- Check [Python Packaging User Guide](https://packaging.python.org/installing/)\n- Run `pip install pyrandwalk` or `pip3 install pyrandwalk` (Need root access)\n\n\n## Usage\n\n\n```pycon\n\u003e\u003e\u003e from pyrandwalk import *\n\u003e\u003e\u003e import numpy as np\n\u003e\u003e\u003e states = [0, 1, 2, 3, 4]\n\u003e\u003e\u003e trans = np.array([[1,    0, 0,    0, 0],\n...                   [0.25, 0, 0.75, 0, 0],\n...                   [0, 0.25, 0, 0.75, 0],\n...                   [0, 0, 0.25, 0, 0.75],\n...                   [0, 0,    0, 1,    0]])\n\u003e\u003e\u003e rw = RandomWalk(states, trans)\n```\nWe are simulating random walks on the above graph (weights are probabilities):\n\u003cimg src=\"https://github.com/sadrasabouri/pyrandwalk/raw/master/Otherfiles/usage_example.webp\"\u003e\n\n\n### Probability of A Sequence\n\nImagine you want to calculate probability which you start from state 2, go to state 1 and stuck in state 0.\nWhat's the probability of these walk sequences?\n```pycon\n\u003e\u003e\u003e rw.prob_sec([2, 1, 0])\n0.0125\n```\n\nInitial probability distribution is assumed to be uniform by default but you can change it by passing optional argument `initial_dist`:\n```pycon\n\u003e\u003e\u003e rw.prob_sec([2, 1, 0], initial_dist=[0, 0, 1, 0, 0])\n0.0625\n```\n\n\n### Run a random walk\n\nYou can start a random walk on given markov chain and see the result:\n\n```pycon\n\u003e\u003e\u003e states, probs = rw.run()\n\u003e\u003e\u003e states\n[4, 3, 4, 3, 4, 3, 4, 3, 2, 3, 4]\n\u003e\u003e\u003e probs\n[0.2, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.25, 0.75, 0.75]\n```\n\nBy default your random walk will contain 10 steps, but you can change it by passing optional argument `ntimes`:\n\n```pycon\n\u003e\u003e\u003e states, probs = rw.run(ntimes=20)\n\u003e\u003e\u003e states\n[3, 4, 3, 4, 3, 2, 1, 2, 3, 4, 3, 4, 3, 4, 3, 4, 3, 4, 3, 2, 3]\n\u003e\u003e\u003e probs\n[0.2, 0.75, 1.0, 0.75, 1.0, 0.25, 0.25, 0.75, 0.75, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.25, 0.75]\n```\n\nAnd if you want to see what's going on down there during the simulation you can set the `show` flag:\n\n```pycon\n\u003e\u003e\u003e states, probs = rw.run(ntimes=30, show=True)\n1 --\u003e 2  (p = 0.750)\n2 --\u003e 3  (p = 0.750)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 2  (p = 0.250)\n2 --\u003e 1  (p = 0.250)\n1 --\u003e 2  (p = 0.750)\n2 --\u003e 3  (p = 0.750)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 4  (p = 0.750)\n4 --\u003e 3  (p = 1.000)\n3 --\u003e 2  (p = 0.250)\n2 --\u003e 3  (p = 0.750)\n\u003e\u003e\u003e states\n[1, 2, 3, 4, 3, 4, 3, 4, 3, 4, 3, 4, 3, 4, 3, 2, 1, 2, 3, 4, 3, 4, 3, 4, 3, 4, 3, 4, 3, 2, 3]\n\u003e\u003e\u003e probs\n[0.2, 0.75, 0.75, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.25, 0.25, 0.75, 0.75, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.75, 1.0, 0.25, 0.75]\n```\n\n\n### Final Probability Distribution\n\nYou can easily find out the final probability distribution of you random walk by:\n```pycon\n\u003e\u003e\u003e rw.final_dist()\narray([1., 0., 0., 0., 0.])\n```\nWhich implies that the walk will in state `0` for sure as time goes on.\n\n### Is it irreducible?\n\nYou can check if your Markov chain is irreducible to lower rank ones or not by:\n\n```pycon\n\u003e\u003e\u003e rw.is_irreducible()\nFalse\n```\n\n\n### nth transition matrix\n\nIf you want to see what's the probability of moving from state `i` to `j` with `n` steps, you can easily calculate the nth transition matrix by:\n```pycon\n\u003e\u003e\u003e rw.trans_power(2)\narray([[1.    , 0.    , 0.    , 0.    , 0.    ],\n       [0.25  , 0.1875, 0.    , 0.5625, 0.    ],\n       [0.0625, 0.    , 0.375 , 0.    , 0.5625],\n       [0.    , 0.0625, 0.    , 0.9375, 0.    ],\n       [0.    , 0.    , 0.25  , 0.    , 0.75  ]])\n```\n\n\n### Graph edges\n\nYou can have your final graph edges in a list containing tuples like `(from, to, probability)` for each edge by:\n\n```pycon\n\u003e\u003e\u003e rw.get_edges()\n[(0, 0, 1.0), (1, 0, 0.25), (1, 2, 0.75), (2, 1, 0.25), (2, 3, 0.75), (3, 2, 0.25), (3, 4, 0.75), (4, 3, 1.0)]\n```\n\n### Graph\n\nMaking a *networkx* graph object from your random walk process is also token care of by this library:\n\n```pycon\n\u003e\u003e\u003e rw_graph = rw.get_graph()\n```\n\n### __Colors of Nodes__ [will be removed]\n\nUntil now we could not show graphs with self-loops using networkx so as far as this feature being added to networkx, we're using `blue` color for ordinary states and `red` color for states with self-loop.\n\n```pycon\n\u003e\u003e\u003e rw.get_colormap()\n['red', 'blue', 'blue', 'blue', 'blue']\n```\n\n\n### Type of Classes\n\nFor knowing which class is recurrent or transient you can use above method, you can also have reduced transition matrix for each set.\n\n```pycon\n\u003e\u003e\u003e rw_class_types = rw.get_typeof_classes()\n\u003e\u003e\u003e rw_class_types['recurrent']\n([0], array([[1.]]))\n\u003e\u003e\u003e rw_class_types['transient'][0]\n[1, 2, 3, 4]\n\u003e\u003e\u003e rw_class_types['transient'][1]\narray([[0.  , 0.75, 0.  , 0.  ],\n       [0.25, 0.  , 0.75, 0.  ],\n       [0.  , 0.25, 0.  , 0.75],\n       [0.  , 0.  , 1.  , 0.  ]])\n\n```\n\n\n### The Best Policy Problems\n\nFor making the best policy problems for your random walk you can easily:\n\n```pycon\n\u003e\u003e\u003e states = [0, 1, 2]\n\u003e\u003e\u003e trans = np.array([[1, 0, 0], [1/2, 0, 1/2], [0, 1, 0]])\n\u003e\u003e\u003e rw = RandomWalk(states, trans, payoff=[0, 1, 4], cost=[1, 0, 2], discount=0.5)\n\u003e\u003e\u003e rw.best_policy()\n{'continue': [], 'stop': [0, 1, 2]}\n```\n\n\n## References\t\t\t\n\n\u003cblockquote\u003e1- Lawler, Gregory F. Introduction to stochastic processes. Chapman and Hall/CRC, 2018.\u003c/blockquote\u003e\n\u003cblockquote\u003e2- \u003ca href=\"https://markusfeng.com/projects/graph/\"\u003eMarkusfeng\u003c/a\u003e\u003c/blockquote\u003e\n\u003cdiv\u003eIcon made by \u003ca href=\"https://www.flaticon.com/authors/becris\" title=\"Becris\"\u003eBecris\u003c/a\u003e from \u003ca href=\"https://www.flaticon.com/\" title=\"Flaticon\"\u003ewww.flaticon.com\u003c/a\u003e\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsadrasabouri%2Fpyrandwalk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsadrasabouri%2Fpyrandwalk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsadrasabouri%2Fpyrandwalk/lists"}