UsefsUFE

Learn Neural Networks, Deep Learning and NLP step by step.

UsefsUFE is two things in one package:

1. A desktop app where you click Next ▶ and watch an algorithm work, one step at a time. Every step shows a picture and explains in plain English what just happened, with the real numbers filled into the formulas.
2. A Python library written from scratch in NumPy: a Perceptron, neural networks with hand-written backpropagation, and uf.nlp, an NLTK-compatible NLP toolkit (tokenizers, stemmers, WordNet, POS tagging, chunking, parsing, language models, VADER sentiment, word2vec, BLEU and more) with the same names as NLTK.

It needs only NumPy and Matplotlib, and works fully offline: everything it needs is bundled (Iris, handwritten digits, public-domain books, a treebank sample, WordNet, the VADER lexicon, 80 teaching reviews). Sources and licences: data/DATA_LICENSES.md.

Install and run

pip install usefsufe
usefsufe

The first command installs the package and its dependencies. The second opens the app. You can also start it with python -m usefsufe.

In Google Colab or Jupyter (no desktop window there), use the notebook player:

!pip install -q usefsufe
from usefsufe.notebook import browse
browse()

See examples/UsefsUFE_Colab.ipynb and the full usage guide for every function, setting and command.

Windows: Tkinter comes with the standard Python installer from python.org. If the app says Tkinter is missing, re-run the installer and tick "tcl/tk and IDLE".

Start screen, Code Reference and Tips

The app opens on a start screen: pick a course (Neural Networks, Deep Learning or NLP), open the Code Reference, or read the Tips & Summaries. The Home button (or Esc) always brings you back.

• Code Reference - every function grouped and searchable, each with when to use it, its signature, a one-line example you can Run (plots open in a window) or Copy, the NLTK / scikit-learn equivalent and a link to the related lesson. The same reference works without the app: uf.menu(), uf.menu("pos_tag"), uf.menu(search="stem") or uf.menu(interactive=True).
• Tips & Summaries - per course, a when to use what table and every lesson's key points on one page. Inside each lesson, the Summary tab shows the same without pressing Next.

The lessons

Each step shows a picture and one or two lines of explanation; More ▾ opens the full explanation with every number. The Summary tab shows the whole lesson on one page.

Every lesson has settings on the left (learning rate, number of neurons, your own text…). Change one and the lesson recomputes, staying on the same step. Settings that have no effect on the current step are greyed out. Every sentence that describes a result ("the loss has flattened", "they differ") is computed from the actual numbers, never hard-coded.

Code tab: every lesson shows the Python code that does the same thing with the library, filled in with your current settings. Copy it or save it as a .py file.

Controls: ◀ Back, Next ▶, Reset. Keyboard: ← and → to step. Save picture exports the current plot as PNG or PDF.

Use it from Python

import numpy as np
from usefsufe.core import Perceptron, MLP
from usefsufe.core.datasets import load_iris, make_moons, train_test_split
from usefsufe.core import text

# Perceptron on Iris (setosa vs the rest), like the NN lab
X, species, names = load_iris()
y = np.where(species == "Iris-setosa", 1, -1)
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.25)
model = Perceptron(eta=0.1, n_iter=10).fit(X_tr, y_tr)
print(model.errors_, model.score(X_te, y_te))

# A deep network on two moons, like the DL lab
X, y = make_moons(400, noise=0.2)
net = MLP([2, 16, 16, 1], activation="relu", lr=0.01, l2=0.001).fit(X, y, epochs=300)
print(net.score(X, y))

# The NLP lab's tools, without downloading anything
print(text.word_tokenize("Battery isn't bad!"))        # ['Battery', 'is', "n't", 'bad', '!']
print(text.clean("Battery isn't bad!", expand=True))   # 'battery is not bad'
print(text.remove_stopwords(["not", "good"]))          # ['good']   <- the pitfall
print(text.remove_stopwords(["not", "good"], keep_negations=True))

Watch a training run step by step:

for info in Perceptron(eta=0.1, n_iter=2).fit_steps(X_tr, y_tr):
    if info["update"] != 0:
        print(info["epoch"], info["w_before"], "->", info["w_after"])

The NLP toolkit (NLTK names) and the deep learning library (Keras and PyTorch style):

import usefsufe as uf

tokens = uf.nlp.word_tokenize("The battery isn't bad, but the screen is AMAZING!")
uf.nlp.pos_tag(tokens)
uf.nlp.SentimentIntensityAnalyzer().polarity_scores("The battery isn't bad!")
uf.nlp.WordNetLemmatizer().lemmatize("better", "a")          # 'good'

from usefsufe.dl import Sequential, Dense
model = Sequential([Dense(16, activation="relu"), Dense(1, activation="sigmoid")])
model.compile(optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"])
model.fit(X, y, epochs=50)
print(uf.metrics.classification_report(y, model.predict_classes(X)))

uf.menu()            # browse every function with an example

Step through a lesson in a Jupyter notebook (pictures and explanations, step by step):

from usefsufe.lessons import get_lesson
get_lesson("linearity_trap").show_steps(epochs=200)

How it is built

src/usefsufe/
  core/        the lesson maths: activations, Perceptron, MLP (backprop), softmax, autograd, text basics
  nlp/         NLTK-style NLP from scratch (tokenizers, stemmers, WordNet, taggers, parsers, LMs, VADER...)
  dl/          deep learning from scratch: layers, losses, optimizers, Sequential, callbacks, data
  metrics.py   classification and regression metrics
  lessons/     each lesson is a generator that yields Steps (short text, full text, data to draw)
  catalog.py   the code reference: every function with "when to use it" and a runnable example
  menu.py      uf.menu(): the code reference in a terminal or notebook
  tips.py      "when to use what" tables and lesson summaries
  app/         the Tkinter app: start screen, course pages, Code Reference, Tips
  notebook.py  the lesson player for Jupyter / Colab (ipywidgets)
  data/        bundled datasets and models (see DATA_LICENSES.md)
tools/build_data.py   rebuilds the bundled data (developers only)

The app contains no maths. Each lesson computes one step, pauses, and waits for Next. That is why heavy training happens gradually and Back is instant.

Development

python -m venv .venv
.venv\Scripts\activate            # Windows   (Linux/macOS: source .venv/bin/activate)
pip install -e ".[dev]"
pytest                             # 360 tests: maths vs. the lab results, NLTK / scikit-learn comparisons, gradient checks, every lesson, every code-reference example, the app
usefsufe

License

MIT. See LICENSE.

Lesson content follows the Neural Networks, Deep Learning and NLP labs at Université Française d'Égypte (UFE).