# `MarChie`: a Compact Open Source Tool for Analyzing Discrete **Mar**kov **Ch**ains
[](https://badge.fury.io/py/MarChie)
[](https://github.com/maxschmaltz/MarChie)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://www.python.org/)
----------
### Contents:
* [Intro](#intro)
* [Quick Start](#quick-start)
* [Acknowledgements](#acknowledgements)
* [License](#license)
----------
## Intro
Markov Chain is a model of a system with $N$ states, that assumes that
transition from one state to another is independent of the history of transitions
and is strictly defined by the probability of such transition (Markov assumption).
At the beginning moment of time (step $0$), the probabilities of the states are defined by the initial states distribution vector.
On each next time step $k$, the system goes from a state $\xi_k = i$ to a state $\xi_{k + 1} = j$ with a probability $P(\xi_{k + 1} = j| \xi_k = i) \equiv p_{ij}$, while the history of the transitions does not change this probability (Markov assumption):
$$
P(\xi_{k + 1} =j| \xi_0 = i_0, \xi_1 = i_1, ..., \xi_{k - 1} = i_{i - 1}, \xi_k = i) = P(\xi_{k + 1} =j| \xi_k = i) \equiv p_{ij}
$$
Thus, a discrete Markov Chain is described with 2 components:
1. Initial probability distribution vector $\pi = (\pi_0, \pi_1, ..., \pi_n)$, where $n$ is the number of states in the system, and $\pi_i$ is the probability that the system starts in the state $\xi_0 = i$.
2. Transition probability matrix $P = (p_{ij})$, where $p_{ij}$ is the probability to go to the state $\xi_{k + 1} = j$ from the state $\xi_k = i$ in one step.
The vector of an initial states distribution, as well as the rows of a transition matrix, are stochastic (the probabilities should add up to 1) as the events of transitions are mutually exclusive, while the system must make a transition at each step, so the sum of the probabilities of all the transitions must be 1 altogether.
From Markov assumption it follows:
$$
\forall n \geq 1, \forall i_k: \quad
P(\xi_0 = i_0, \xi_1 = i_1, ..., \xi_n = i_n) = \pi_i^{(0)} p_{i_{0} i_{1}} p_{i_{1} i_{2}} ... p_{i_{n - 1} i_{n}}
$$
<br>
Given transition probability matrix and (optional) initial state probability distribution,
`MarChie` does the following:
* computes adjacency matrix;
* computes reachability matrix (using adjacency matrix);
* computes transposed reachability matrix (using reachability);
* computes communication matrix (using reachability and transposed reachability matrices);
* computes communication matrix complement (using communication);
* computes classification matrix (using reachability and communication matrix complement);
* computes classification matrix extension (using classification matrix);
* computes equivalency classes matrix (using communication matrix and classification matrix extension);
* defines essential and inessential states;
* defines equivalency classes and their cyclic subclasses;
* builds the structure of the chain from where all its states, classes and subclasses are easily accessible;
* defines properties of the chain;
* classifies the chain (based on the properties);
* defines end behavior of the chain (based on the classification).
## Quick Start
`March` is a `pip`-installable package. You can access it directly from PyPI:
```bash
pip install MarChie
```
The main object that is really intended to be used is `class MarChie.marchie.March`. The class requires only transition probability matrix and (optionally) initial state probability distribution vector as arguments; if you provide no initial distribution vector, it will be generated.
```python
>>> import numpy as np
>>> from March.marchie import March
>>> trans_mat = np.array([
[1, 0, 0 ],
[0.8, 0.2, 0 ],
[0.3, 0.5, 0.2]
])
>>> init_distr = np.array(
[0.3, 0.2, 0.5]
)
>>> marchie = MarChie(
init_distr=init_distr,
trans_mat=trans_mat
)
>>> marchie
```
Output:
```text
Monoergodic Absorbing Markov Chain
|
|___Essential States
|
|___Acyclic Equivalency Class 0 : states 0
|
|___Inessential States: states 1, 2
[+reducible][-polyergodic][+regular][+absorbing][+strong_convergence]
```
All the information is accessible in class / instance variables, which you will learn in details in API_reference.html. Also, make sure to take a look at the demo notebook for relevant examples.
## Acknowledgements
I would like to kindly thank Elena Ilyushina (MSU, Faculty of Mechanics and Mathematics) for the course "Markov Chains and their linguistic applications" (2021). Even though at the moment, the course was far above my educational stage, I was kindly accepted to take it and, with Elena Ilyushina's help, I was able to understand the basic concepts of Markov Chains Theory thoroughly and solidly, learn to apply the Theory in real-life tasks and found my programming skills useful for efficient Markov Chains analysis.
## License
> Copyright 2023 Max Schmaltz: @maxschmaltz
>
> Licensed under the Apache License, Version 2.0 (the "License"); <br>
> you may not use this file except in compliance with the License. <br>
> You may obtain a copy of the License at <br>
>
> http://www.apache.org/licenses/LICENSE-2.0 <br>
>
> Unless required by applicable law or agreed to in writing, software <br>
> distributed under the License is distributed on an "AS IS" BASIS, <br>
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. <br>
> See the License for the specific language governing permissions and <br>
> limitations under the License.
Raw data
{
"_id": null,
"home_page": "https://github.com/maxschmaltz/MarChie",
"name": "MarChie",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "markov chain,mathematics",
"author": "Max Schmaltz",
"author_email": "schmaltzmax@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/89/8c/5c87d89b069924683cdc544871dbc6f2fa81f7b32f8fdf1e27ee6b83c022/MarChie-0.1.tar.gz",
"platform": null,
"description": "# `MarChie`: a Compact Open Source Tool for Analyzing Discrete **Mar**kov **Ch**ains\n\n[](https://badge.fury.io/py/MarChie)\n[](https://github.com/maxschmaltz/MarChie)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n[](https://www.python.org/)\n\n\n----------\n\n### Contents:\n\n* [Intro](#intro)\n* [Quick Start](#quick-start)\n* [Acknowledgements](#acknowledgements)\n* [License](#license)\n\n----------\n\n\n## Intro\n\nMarkov Chain is a model of a system with $N$ states, that assumes that\ntransition from one state to another is independent of the history of transitions\nand is strictly defined by the probability of such transition (Markov assumption).\n\nAt the beginning moment of time (step $0$), the probabilities of the states are defined by the initial states distribution vector.\nOn each next time step $k$, the system goes from a state $\\xi_k = i$ to a state $\\xi_{k + 1} = j$ with a probability $P(\\xi_{k + 1} = j| \\xi_k = i) \\equiv p_{ij}$, while the history of the transitions does not change this probability (Markov assumption):\n\n$$\nP(\\xi_{k + 1} =j| \\xi_0 = i_0, \\xi_1 = i_1, ..., \\xi_{k - 1} = i_{i - 1}, \\xi_k = i) = P(\\xi_{k + 1} =j| \\xi_k = i) \\equiv p_{ij}\n$$\n\nThus, a discrete Markov Chain is described with 2 components:\n\n1. Initial probability distribution vector $\\pi = (\\pi_0, \\pi_1, ..., \\pi_n)$, where $n$ is the number of states in the system, and $\\pi_i$ is the probability that the system starts in the state $\\xi_0 = i$.\n\n2. Transition probability matrix $P = (p_{ij})$, where $p_{ij}$ is the probability to go to the state $\\xi_{k + 1} = j$ from the state $\\xi_k = i$ in one step.\n\n\nThe vector of an initial states distribution, as well as the rows of a transition matrix, are stochastic (the probabilities should add up to 1) as the events of transitions are mutually exclusive, while the system must make a transition at each step, so the sum of the probabilities of all the transitions must be 1 altogether.\n\nFrom Markov assumption it follows:\n\n$$\n\\forall n \\geq 1, \\forall i_k: \\quad\nP(\\xi_0 = i_0, \\xi_1 = i_1, ..., \\xi_n = i_n) = \\pi_i^{(0)} p_{i_{0} i_{1}} p_{i_{1} i_{2}} ... p_{i_{n - 1} i_{n}}\n$$\n\n<br>\n\nGiven transition probability matrix and (optional) initial state probability distribution,\n`MarChie` does the following:\n\n* computes adjacency matrix;\n* computes reachability matrix (using adjacency matrix);\n* computes transposed reachability matrix (using reachability);\n* computes communication matrix (using reachability and transposed reachability matrices);\n* computes communication matrix complement (using communication);\n* computes classification matrix (using reachability and communication matrix complement);\n* computes classification matrix extension (using classification matrix);\n* computes equivalency classes matrix (using communication matrix and classification matrix extension);\n* defines essential and inessential states;\n* defines equivalency classes and their cyclic subclasses;\n* builds the structure of the chain from where all its states, classes and subclasses are easily accessible;\n* defines properties of the chain;\n* classifies the chain (based on the properties);\n* defines end behavior of the chain (based on the classification).\n\n\n## Quick Start\n\n`March` is a `pip`-installable package. You can access it directly from PyPI:\n\n```bash\npip install MarChie\n```\n\nThe main object that is really intended to be used is `class MarChie.marchie.March`. The class requires only transition probability matrix and (optionally) initial state probability distribution vector as arguments; if you provide no initial distribution vector, it will be generated.\n\n```python\n\n>>> import numpy as np\n>>> from March.marchie import March\n\n>>> trans_mat = np.array([\n [1, 0, 0 ],\n [0.8, 0.2, 0 ],\n [0.3, 0.5, 0.2]\n])\n>>> init_distr = np.array(\n [0.3, 0.2, 0.5] \n)\n>>> marchie = MarChie(\n init_distr=init_distr,\n trans_mat=trans_mat\n)\n\n>>> marchie\n```\n\nOutput:\n```text\nMonoergodic Absorbing Markov Chain\n|\n|___Essential States\n |\n |___Acyclic Equivalency Class 0 : states 0\n|\n|___Inessential States: states 1, 2\n\n[+reducible][-polyergodic][+regular][+absorbing][+strong_convergence]\n```\n\nAll the information is accessible in class / instance variables, which you will learn in details in API_reference.html. Also, make sure to take a look at the demo notebook for relevant examples.\n\n\n## Acknowledgements\n\nI would like to kindly thank Elena Ilyushina (MSU, Faculty of Mechanics and Mathematics) for the course \"Markov Chains and their linguistic applications\" (2021). Even though at the moment, the course was far above my educational stage, I was kindly accepted to take it and, with Elena Ilyushina's help, I was able to understand the basic concepts of Markov Chains Theory thoroughly and solidly, learn to apply the Theory in real-life tasks and found my programming skills useful for efficient Markov Chains analysis.\n\n\n## License\n\n> Copyright 2023 Max Schmaltz: @maxschmaltz\n> \n> Licensed under the Apache License, Version 2.0 (the \"License\"); <br>\n> you may not use this file except in compliance with the License. <br>\n> You may obtain a copy of the License at <br>\n> \n> http://www.apache.org/licenses/LICENSE-2.0 <br>\n> \n> Unless required by applicable law or agreed to in writing, software <br>\n> distributed under the License is distributed on an \"AS IS\" BASIS, <br>\n> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. <br>\n> See the License for the specific language governing permissions and <br>\n> limitations under the License.\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "MarChie: a Compact Open Source Tool for Analyzing Discrete Markov Chains.",
"version": "0.1",
"project_urls": {
"Homepage": "https://github.com/maxschmaltz/MarChie"
},
"split_keywords": [
"markov chain",
"mathematics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "898c5c87d89b069924683cdc544871dbc6f2fa81f7b32f8fdf1e27ee6b83c022",
"md5": "375b83abcd90aa07e1fbad95427080c5",
"sha256": "36b6b2f7260069176a5c8f05ed4aece20ced0a810780bed3da05a441e35e34a5"
},
"downloads": -1,
"filename": "MarChie-0.1.tar.gz",
"has_sig": false,
"md5_digest": "375b83abcd90aa07e1fbad95427080c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27434,
"upload_time": "2023-06-21T23:15:09",
"upload_time_iso_8601": "2023-06-21T23:15:09.731375Z",
"url": "https://files.pythonhosted.org/packages/89/8c/5c87d89b069924683cdc544871dbc6f2fa81f7b32f8fdf1e27ee6b83c022/MarChie-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 23:15:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maxschmaltz",
"github_project": "MarChie",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "marchie"
}
JSON
