numpy-ml

Numpy-ML: A Readable, Experimental Collection of NumPy-Based Machine Learning Algorithms

Introduction

In the sprawling world of machine learning repositories, numpy-ml stands out with a tongue-in-cheek promise: an intentionally inefficient, but wonderfully legible, collection of algorithms implemented exclusively with NumPy. This project emphasizes clarity, educational value, and rapid prototyping over raw speed. It’s the kind of toolkit you reach for when you want to understand how a model works under the hood, when you crave transparency in the math, and when you enjoy the hands-on experience of tweaking algorithms line by line.

The philosophy behind numpy-ml is simple. It aims to provide a comprehensive set of models and utilities that demonstrate core ideas in machine learning and reinforcement learning using the Python scientific stack. The code is written with the Python standard library in mind, and NumPy is the primary engine driving computation. While performance is not the primary goal, the project’s structure makes it a powerful educational resource: you can follow the data flow from input preprocessing all the way through to the final predictions, losses, and updates, observing how each component transforms data and influences learning.

What you’ll find in numpy-ml ranges from classical statistical models to modern neural techniques, all implemented with a focus on readability and instructional value. If you’re a student, a researcher prototyping ideas, or a curious practitioner who enjoys inspecting every step of the algorithm, numpy-ml offers a welcoming playground. It also serves as a practical platform for experimentation, teaching, and collaboration, inviting contributions that adhere to a clean, well-documented coding style.

Getting Started: How to Install and Try It

For rapid experimentation

If you want a fast path to get your hands dirty and start hacking around, the project supports a workflow tailored for quick prototyping. The process begins by cloning the repository, creating a dedicated virtual environment, and installing development requirements. A typical sequence looks like this:

• Clone the repository: git clone https://github.com/ddbourgin/numpy-ml.git
• Move into the project directory: cd numpy-ml
• Create a virtual environment: virtualenv npml
• Activate the environment: source npml/bin/activate
• Install development requirements: pip3 install -r requirements-dev.txt

This setup gives you an isolated workspace where you can tinker with models, add new experiments, and iterate rapidly without disturbing your main Python installation. It’s also a gentle introduction to the project’s ethos: you can explore the codebase with a clear separation between your experiments and your system’s global state.

As a package

If you don’t plan to modify the source code, you can install numpy-ml as a Python package and start using it directly. The package installation is straightforward:

• Install numpy-ml: pip3 install -u numpy_ml

For users interested in reinforcement learning environments

Numpy-ml includes agents that train on environments defined in OpenAI Gym. If your goal is reinforcement learning experimentation, you can install the Gym integration alongside numpy-ml with:

• Install with gym support: pip3 install -u 'numpy_ml[rl]'

This allows you to explore a variety of RL settings while benefiting from the same readable, NumPy-centered implementation style you’ll find throughout the project.

Documentation and learning resources

Comprehensive documentation is available to help you understand the models, their parameters, and the way data flows through the system. The project’s documentation provides detailed explanations, usage guidelines, and examples to help you get up to speed quickly. You’ll find information on model selection, training procedures, and practical tips for debugging and extending the library. The documentation link is a central hub for learning how to leverage the breadth of models offered by numpy-ml, from linear models to deep learning components and beyond.

Available models at a glance

Gaussian mixture model

• EM training A probabilistic approach to clustering that assumes data come from a mixture of Gaussians. Expectation-Maximization (EM) is used to iteratively refine the mixture parameters, with the goal of maximizing the likelihood of the observed data under the model. This model provides a concrete demonstration of latent variable estimation, responsibility calculations, and parameter re-estimation in a framework that is widely used in unsupervised learning.

Hidden Markov model

• Viterbi decoding
• Likelihood computation
• MLE parameter estimation via Baum-Welch/forward-backward algorithm Hidden Markov models provide a powerful sequence modeling tool. In numpy-ml, you’ll find Viterbi decoding to infer the most likely state sequence, forward-backward to compute likelihoods, and Baum-Welch (an Expectation-Maximization variant) for parameter estimation. These components illustrate how temporal dependencies and latent states can be captured in a clean, NumPy-only implementation.

Latent Dirichlet allocation (topic model)

• Standard model with MLE parameter estimation via variational EM
• Smoothed model with MAP parameter estimation via MCMC LDA brings topic modeling into focus, letting you discover latent topics within a corpus of documents. The standard model uses variational EM for maximum likelihood parameter estimation, while a smoothed variant introduces MAP estimation through Markov Chain Monte Carlo techniques. This dual approach showcases the interplay between deterministic optimization and probabilistic sampling in uncovering topic structure.

Neural networks

• Layers / Layer-wise operations

• Add, Flatten, Multiply

• Softmax

• Fully-connected / Dense

• Sparse evolutionary connections

• LSTM

• Elman-style RNN

• Max + average pooling

• Dot-product attention

• Embedding layer

• Restricted Boltzmann machine (CD-n training)

• 2D deconvolution (padding and stride)

• 2D convolution (padding, dilation, stride)

• 1D convolution (padding, dilation, stride, causality)

• Modules

• Bidirectional LSTM

• ResNet-style residual blocks (identity and convolution)

• WaveNet-style residual blocks with dilated causal convolutions

• Transformer-style multi-headed scaled dot product attention

• Regularizers

• Dropout

• Normalization

• Batch normalization (spatial and temporal)

• Layer normalization (spatial and temporal)

• Optimizers

• SGD with momentum

• AdaGrad

• RMSProp

• Adam

• Learning Rate Schedulers

• Constant

• Exponential

• Noam/Transformer

• Dlib scheduler

• Weight Initializers

• Glorot / Xavier (uniform and normal)

• He / Kaiming (uniform and normal)

• Standard and truncated normal

• Losses

• Cross entropy

• Squared error

• Bernoulli VAE loss

• Wasserstein loss with gradient penalty

• Noise contrastive estimation loss

• Activations

• ReLU, Tanh

• Affine, Sigmoid

• Leaky ReLU, ELU, SELU

• GELU

• Exponential

• Hard Sigmoid

• Softplus

• Models

• Bernoulli variational autoencoder

• Wasserstein GAN with gradient penalty

• Word2Vec encoder with skip-gram and CBOW architectures

• Utilities

• col2im (MATLAB port)

• im2col (MATLAB port)

• conv1D, conv2D, deconv2D

• minibatch A broad spectrum of neural components is included to illustrate how deep learning concepts can be built with pure NumPy. You’ll find layers suitable for stacking into feed-forward networks, recurrent architectures like LSTMs and Elman networks, and even convolutional structures with both 1D and 2D variants. Advanced topics such as attention mechanisms, residual connections, and Transformer-style components appear in the mix, offering educational exposure to modern neural network ideas without requiring a heavier deep learning stack. Regularization, normalization, and a suite of activation functions provide hands-on opportunities to experiment with training dynamics and model performance.

• Models

• Bernoulli variational autoencoder and related generative models help you see how latent variables capture data structure.

• Wasserstein GAN with gradient penalty demonstrates a modern generative modeling approach in a deliberately transparent setting.

• Word2Vec encoder with skip-gram and CBOW architectures offers a beginner-friendly view into distributed representations and shallow NLP models.

• Utilities

• MATLAB-inspired image and signal processing utilities (col2im, im2col) give you a window into how data can be rearranged for efficient convolution-like operations.

• Convolutional and deconvolution utilities (conv1D, conv2D, deconv2D) provide a concrete playground for understanding how spatial structure is manipulated in neural networks.

• Activation and normalization choices

  The included activations and normalization options enable experiments with training stability, gradient flow, and representational richness. By mixing and matching activations with normalization strategies and regularization techniques, you can observe how these choices affect convergence and model behavior in practice.

• Optimizers and learning-rate schedules

  The collection covers a range of optimization strategies—from classic stochastic gradient descent to adaptive methods like AdaGrad, RMSProp, and Adam. Layered with different learning-rate schedulers, you can explore how step sizes evolve over training and how this impacts convergence speed and final accuracy.

• Regularization and loss functions

  Dropout and various loss functions provide practical knobs to control overfitting and guide learning. The inclusion of specialized losses, such as Wasserstein loss with gradient penalty and contrastive estimators, broadens the experimentation landscape beyond standard mean-squared-error and cross-entropy.

• Preprocessing and feature transformations

  The repository also includes preprocessing utilities that are often essential in real-world ML pipelines. They cover a range of feature transformations and encodings, enabling you to prepare data for model training within the same NumPy-centric environment.

• Word and text representations

  The presence of word2vec-enabled architectures emphasizes an educational angle for natural language processing, showing how distributed representations can be learned and deployed in downstream tasks.

Tree-based models

• Decision trees (CART)
• Bagging: Random forests
• Boosting: Gradient-boosted decision trees Tree-based models offer a tangible, interpretable route into machine learning. You’ll see core ideas like splitting criteria and pruning in a pure NumPy setting. Random forests illustrate ensemble learning through bagging, while gradient boosting demonstrates boosting weak learners to build a stronger composite model. These models provide a bridge between classical statistics and modern ensemble methods, making them accessible stepping stones for learners transitioning from linear models to more complex nonlinear learners.

Linear models

• Ridge regression
• Logistic regression
• Ordinary least squares
• Weighted linear regression
• Generalized linear model (log, logit, and identity link)
• Gaussian naive Bayes classifier
• Bayesian linear regression with conjugate priors
• Unknown mean, known variance (Gaussian prior)
• Unknown mean, unknown variance (Normal-Gamma / Normal-Inverse-Wishart prior) Linear models form the backbone of many statistical and machine learning applications. The implementations cover classic regularization (ridge) and robust classification (logistic), alongside probabilistic interpretations (Bayesian linear regression) and natural extensions to generalized linear models and naive Bayes. The breadth of priors and conjugate analyses demonstrates how Bayesian thinking can be integrated into a NumPy-first workflow, offering hands-on exposure to uncertainty quantification in simple, interpretable terms.

n-Gram sequence models

• Maximum likelihood scores
• Additive/Lidstone smoothing
• Simple Good-Turing smoothing n-gram models provide a grounded path into language modeling and sequence analysis. By focusing on maximum likelihood estimates and smoothing techniques, numpy-ml makes it possible to observe how word sequence probabilities are estimated and adjusted for unseen events. This section of the library is particularly valuable for learners exploring the transition from surface-level bag-of-words representations to more nuanced probabilistic sequence models.

Multi-armed bandit models

• UCB1
• LinUCB
• Epsilon-greedy
• Thompson sampling with conjugate priors
• Beta-Bernoulli sampler
• LinUCB Bandit algorithms deliver a practical lens into exploration-exploitation trade-offs. With a collection of strategies—Upper Confidence Bound, LinUCB, epsilon-greedy, Thompson sampling, and Beta-Bernoulli variants—you can study how simple decision rules adapt as data accrues. These models are highly approachable for demonstrations and can serve as a gateway to reinforcement learning concepts without the full complexity of policy optimization.

Reinforcement learning models

• Cross-entropy method agent
• First visit on-policy Monte Carlo agent
• Weighted incremental importance sampling Monte Carlo agent
• Expected SARSA agent
• TD-0 Q-learning agent
• Dyna-Q / Dyna-Q+ with prioritized sweeping The reinforcement learning section showcases agents that operate in environments defined by Gym. The range includes classic, value-based methods (Q-learning variants, SARSA) and model-based planning (Dyna-Q) with modern twists like prioritized sweeping. The cross-entropy method agent adds a gradient-free optimization flavor to policy search, illustrating the diversity of strategies available within a NumPy-centric RL toolkit.

Nonparametric models

• Nadaraya-Watson kernel regression
• k-Nearest neighbors classification and regression
• Gaussian process regression Nonparametric approaches in numpy-ml highlight the flexibility of kernel-based methods and distance-based learning. You’ll explore local averaging, similarity-based predictions, and probabilistic regression via Gaussian processes. This section emphasizes intuition: there’s no fixed parametric form governing the data; instead, predictions emerge from local structure and prior assumptions encoded in kernels.

Matrix factorization

• Regularized alternating least-squares
• Non-negative matrix factorization Matrix factorization demonstrates how to uncover latent structure in matrix data. Regularized ALS provides a straightforward path to factorizing matrices into latent features, while non-negative matrix factorization imposes a positivity constraint that can yield interpretable components. These techniques underpin recommendation systems and collaborative filtering concepts in a transparent, NumPy-driven environment.

Preprocessing

• Discrete Fourier transform (1D signals)
• Discrete cosine transform (type-II) (1D signals)
• Bilinear interpolation (2D signals)
• Nearest neighbor interpolation (1D and 2D signals)
• Autocorrelation (1D signals)
• Signal windowing
• Text tokenization
• Feature hashing
• Feature standardization
• One-hot encoding / decoding
• Huffman coding / decoding
• Byte pair encoding / decoding
• Term frequency-inverse document frequency (TF-IDF) encoding
• MFCC encoding Preprocessing utilities lay the groundwork for successful modeling by transforming raw data into representations that models can learn from effectively. From spectral transforms for signal processing to text tokenization and various encoding schemes, this section offers practical building blocks for preparing diverse data types. You’ll see how feature standardization, one-hot encoding, and TF-IDF encoding feed into downstream models, while more specialized transforms such as MFCCs illuminate audio processing workflows.

Utilities

• Similarity kernels
• Distance metrics
• Priority queue
• Ball tree
• Discrete sampler
• Graph processing and generators Beyond models, numpy-ml provides a suite of utilities that support data processing, similarity assessments, and efficient data organization. You’ll encounter distance metrics and kernels useful for similarity-based learning, a priority queue and ball-tree structures for efficient retrieval, and graph-related generators for experiments that involve structured data. These utilities round out the library, making it easier to assemble end-to-end pipelines within a consistent NumPy-centric codebase.

Contributing and project etiquette

Am I missing your favorite model? Is there something that could be cleaner or less confusing? Do you see a bug or want to propose an enhancement? The project welcomes contributions that maintain a strong emphasis on readability and the use of standard Python libraries, particularly the Python standard library and NumPy. Under special circumstances, SciPy is also permitted. If you’re curious to contribute, you’ll find a detailed contributing guide in the repository that outlines expectations, testing practices, and the process for submitting patches or new models. The community is invited to help refine and expand the collection, making it even more educational and approachable for learners who want to see, step by step, how each algorithm operates under the hood.

Practical tips for using numpy-ml

• Start with linear models to build intuition. They form a solid foundation for understanding regularization, loss functions, and optimization dynamics before diving into more complex neural architectures.
• Use the preprocessing utilities to normalize, encode, and transform data. Clean, well-preprocessed data often unblocks learning and makes comparisons between models fairer.
• Experiment with small toy datasets first. The emphasis on legibility makes it especially easy to trace how a single datapoint influences updates, predictions, and loss values.
• Explore the reinforcement learning modules with Gym environments to observe how agents explore states, learn value functions, and adapt policies over time.
• Compare different optimization algorithms and learning-rate schedules on the same task. Seeing how SGD, AdaGrad, RMSProp, and Adam behave in the same context provides practical insights into convergence behavior.
• Inspect intermediate representations. Because the code is designed for readability, you can step through matrices and vectors to see how probabilities, responsibilities, and latent variables evolve during training.
• Document and annotate your experiments. The project’s emphasis on clarity makes it a great environment for documenting hypotheses, results, and takeaways from each modeling choice.

Images and visual assets

Images used in this post

No images were provided in the input. If you have specific diagrams, plots, or screenshots you’d like to include, you can attach them or provide links, and they can be incorporated to illustrate model workflows, data transformations, or training progress.

Conclusion: why numpy-ml matters as a learning and prototyping tool

Numpy-ml is not about squeezing the last drop of performance from your models. It’s about understanding, teaching, and exploring machine learning concepts with full visibility into the inner workings. By implementing a broad array of models—from Gaussian mixtures and hidden Markov models to topic models, neural architectures, and reinforcement learning agents—within a NumPy-first framework, the project makes abstract ideas tangible. The emphasis on readability, documentation, and a straightforward development workflow lowers barriers to experimentation and collaboration.

If you’re a student who wants to see how a particular algorithm is built from the ground up, a researcher prototyping ideas and wanting to test conceptual variations quickly, or a curious practitioner looking for a transparent reference implementation, numpy-ml offers a compelling space to explore. Its collection of models, preprocessing tools, and evaluation utilities provides a cohesive environment in which you can learn by doing, compare approaches on common tasks, and grow your intuition about how different components interact across a full ML pipeline.

Images: none provided in the input. If you’d like to enrich this description with visuals, share the assets and I’ll weave them in to illustrate model architectures, data flows, and training dynamics in an engaging, accessible way.

Final thoughts

Numpy-ml invites you to engage deeply with machine learning concepts through clear, NumPy-based implementations. It’s a resource for learning, experimentation, and collaboration—an educational toolkit that balances breadth with depth. By offering a wide spectrum of models and utilities within a coherent, approachable codebase, it supports both the curiosity-driven exploration of ideas and the practical needs of prototyping. Whether you’re teaching a class, preparing a research notebook, or simply satisfying your desire to see every step of an algorithm laid bare, numpy-ml provides a uniquely transparent canvas on which to paint your ML experiments.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/numpy-ml?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)