Metadata-Version: 2.5
Name: tsetly
Version: 0.0.1
Summary: A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read.
License-Expression: MIT
License-File: LICENSE
Keywords: interpretable machine learning,learning automata,propositional logic,tsetlin machine
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Description-Content-Type: text/markdown

# tsetly

A tiny Tsetlin Machine in NumPy: little automata that learn rules you can read.

```
      forget ◀────────────────┼────────────────▶ remember
             1   2   3  …  N  │  N+1  …  2N
```

A Tsetlin Machine learns AND-rules over bits, like `x0 ∧ ¬x1`. Every rule is a
team of Tsetlin automata, one per bit and one per negated bit. Each automaton
walks along its states as the data rewards or penalises it, and once it crosses
the middle, its bit joins the rule. Rules vote for or against each class, and
the class with the most votes wins. That is the whole machine
([Granmo, 2018](https://arxiv.org/abs/1804.01508)).

## Install

```
pip install tsetly
```

## Learn XOR through noise

Twelve random bits, of which only the first two matter, and a fifth of the
training labels flipped:

```python
import numpy as np
from tsetly import TsetlinMachine

rng = np.random.default_rng(0)
X = rng.integers(0, 2, size=(5000, 12))
y = X[:, 0] ^ X[:, 1]
noisy = np.where(rng.random(5000) < 0.2, 1 - y, y)

tm = TsetlinMachine(clauses=8, T=15, s=3.9, seed=1)
tm.fit(X[:4000], noisy[:4000], epochs=20)

print(tm.score(X[4000:], y[4000:]))  # 1.0
print(tm)
```

```
class 0
   +2  ¬x0 ∧ ¬x1
   +2  x0 ∧ x1
   -2  x0 ∧ ¬x1
   -2  ¬x0 ∧ x1
class 1
   +3  ¬x0 ∧ x1
   +1  x0 ∧ ¬x1
   -3  ¬x0 ∧ ¬x1
   -1  x0 ∧ x1
```

It found XOR, ignored the ten distracting bits, and can tell you so.

## API

| | |
|---|---|
| `TsetlinMachine(clauses=20, T=15, s=3.9, states=100, seed=None)` | `clauses` per class (half vote for, half against), the vote target `T`, the specificity `s`, the states per action |
| `fit(X, y, epochs=10)` | learn from bits `X` (samples × features, 0/1) and labels `y` of any kind |
| `predict(X)` | the class with the most votes |
| `votes(X)` | every class's vote total, samples × classes |
| `score(X, y)` | accuracy |
| `rules(label, names=None)` | a class's rules and their votes, optionally with your feature names |
| `print(tm)` | every rule the machine learned |

## License

MIT
