Skip to main content

AliasingAtlas

Interactive Educational Tool for Visualizing Digital Signal Processing Concepts

License: MIT Python Version Tests Quality Open In Colab

Try it in your browser, with no install: open the notebook in Google Colab, run the Setup and Launch cells, and follow the seven guided experiments.

Features • Installation • Quick Start • Documentation

Overview

AliasingAtlas is an interactive educational tool designed to visualize the fundamental principles of the Nyquist-Shannon sampling theorem and digital signal processing (DSP). By simulating the sampling, quantization, and reconstruction of various waveforms in real-time, it provides an intuitive platform for exploring signal fidelity, aliasing effects, and core DSP concepts.

The tool combines:

  • Real-time interactive visualization with matplotlib
  • Multiple signal models (sine, square, sawtooth, triangle, modulated, chirp)
  • Configurable sampling parameters (rate, quantization, filtering, reconstruction)
  • Pedagogical presets for guided learning
  • Export capabilities for reproducibility and analysis

Perfect for students, educators, and signal processing practitioners who want to deeply understand how signals behave when sampled, quantized, and reconstructed.

Features

🎯 Core Functionality

  • Interactive GUI with 2×2 subplot layout:

    • Time-domain view of continuous and sampled signals
    • Frequency-domain FFT spectrum analysis
    • Phase spectrum visualization
    • Quantization error plot with metrics
  • Multiple Signal Models:

    • Basic waveforms: Sine, Square, Sawtooth, Triangle
    • Modulated signals: AM (Amplitude Modulation), FM (Frequency Modulation)
    • Chirp (frequency sweep) for time-varying bandwidth analysis
    • Fourier series synthesis with configurable harmonic count
  • Comprehensive Sampling Control:

    • Adjustable sampling rate (5–1500 Hz range)
    • Anti-alias filtering (None, Ideal brick-wall, Butterworth IIR)
    • Multiple reconstruction methods (FFT-based, First-Order Hold)
    • Spectral windowing (Hamming, Hann)
    • Quantization (4–16 bits)
  • Real-time Analysis Metrics:

    • Signal-to-Noise Ratio (SNR) calculation
    • Reconstruction error (MAE, RMSE)
    • Alias detection and folded frequency calculation
    • Zero-Order Hold and FFT reconstruction comparison

🎓 Pedagogical Features

  • Preset Scenarios: One-click loading of curated learning examples:

    • Safe Nyquist (10×oversampling)
    • Near Nyquist (boundary conditions)
    • Aliasing (undersampling demonstration)
    • AM Sidebands (modulation analysis)
  • Guided Learning Mode: Context-aware hints that explain:

    • Why aliasing is occurring and how to fix it
    • Quantization noise and bit-depth tradeoffs
    • Anti-alias filter necessity and placement
    • Reconstruction method differences

💾 Export & Reproducibility

  • JSON Configuration Export: Save simulator state for reproducibility
  • WAV Audio Export: Standard PCM16 mono files at configurable sample rates
  • Timestamp-based Organization: Automatic file naming and directory management

🌍 Multi-Platform Support

  • Jupyter Notebook (AliasingAtlas.ipynb) with Google Colab support
  • Desktop CLI: aliasing-atlas command
  • Python Module: python -m aliasing_atlas
  • Works on Windows, macOS, and Linux

Installation

Prerequisites

  • Python 3.10 or later
  • pip and the Python venv module

On Debian or Ubuntu, install the venv module if creating an environment fails:

sudo apt install python3-venv

From PyPI

python3 -m pip install "aliasing-atlas[audio]"
aliasing-atlas

Drop [audio] if you don't need desktop playback. Use [notebook] for Jupyter.

From Source

For Windows PowerShell, replace .venv/bin/python with .venv\Scripts\python and source .venv/bin/activate with .venv\Scripts\Activate.ps1 in the commands below.

git clone https://github.com/Boussetta/NyquistNavigator.git
cd NyquistNavigator
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[audio]"

The audio extra installs sounddevice for desktop playback; on Linux it also needs the PortAudio library (sudo apt install libportaudio2). Without it, everything except the Play Audio button works.

Then launch:

.venv/bin/python -m aliasing_atlas

For Development

Clone the repository and install in editable mode:

git clone https://github.com/Boussetta/NyquistNavigator.git
cd NyquistNavigator
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"

To activate the environment for the current shell instead:

source .venv/bin/activate

Quick Start

GUI Application

With the virtual environment activated, run:

aliasing-atlas

Or run without activating it:

.venv/bin/python -m aliasing_atlas

Jupyter Notebook

For local Jupyter, install the notebook dependencies and launch Jupyter:

.venv/bin/python -m pip install jupyter -e ".[notebook]"
.venv/bin/python -m jupyter notebook AliasingAtlas.ipynb

For Google Colab, use the Open in Colab badge above. The Setup cell installs the package from GitHub (pin REF to a release tag for a reproducible classroom setup) and enables the interactive ipympl backend. The Launch cell shows the figure with an output panel underneath, where Play Audio shows a browser audio player and Export CFG / Export WAV show download links. The notebook then walks through seven guided experiments (aliasing, the Nyquist limit, anti-alias filters, bit depth, AM sidebands, leakage/windows, audio).

In your own notebooks, pass an ipywidgets.Output to get the same behaviour:

import ipywidgets as widgets
from aliasing_atlas import AliasingToolbox

panel = widgets.Output()
toolbox = AliasingToolbox(output=panel)   # figsize=(11, 8.2) by default
widgets.VBox([toolbox.fig.canvas, panel])

Programmatic Usage

from aliasing_atlas import AliasingToolbox
import matplotlib.pyplot as plt

# Create and display the interactive tool
toolbox = AliasingToolbox()
plt.show()

# Or use DSP functions directly:
from aliasing_atlas import SignalRegistry, compute_spectrum, sample_signal
import numpy as np

t = np.linspace(0, 1, 1000)
y = SignalRegistry.create_signal('Sine', t, f_sig=10, f_harm=20, a_harm=0.0, phase=0)
t_sampled, y_sampled = sample_signal(t, y, f_samp=30, duration=1.0)
freq, magnitude, phase = compute_spectrum(y_sampled, f_samp=30)

Understanding the Visualization

Time-Domain Plot (Top-Left)

  • Blue Dashed Line: Original continuous signal (ideal reference)
  • Yellow Line: Anti-alias filtered version (if filtering enabled)
  • Green Line: FFT-based reconstruction (smooth curve)
  • Red Staircase: Zero-Order Hold reconstruction
  • Dark Red Dots: Actual sample points

Frequency-Domain Plots (Right)

  • Magnitude Spectrum: Frequency components of the signal

    • Blue Line: Original signal spectrum
    • Orange Dashed: Nyquist limit (fs/2)
    • Magenta Dashed: Predicted alias frequency
    • Black Dashed: Anti-alias filter response
  • Phase Spectrum: Phase angle at each frequency

Quantization Plot (Bottom-Left)

  • Residual error between quantized and ideal signal
  • Larger errors indicate coarse quantization (low bit-depth)

Status Bar

Real-time information:

  • Alias status (active/inactive)
  • SNR and reconstruction metrics
  • Active filter and modulation parameters

Pedagogical Scenarios

Safe Nyquist

  • Signal: 10 Hz sine
  • Sampling: 100 Hz (10× Nyquist)
  • Purpose: Demonstrates high-fidelity sampling with no aliasing
  • Observation: Perfect reconstruction; zoom in on quantization effects

Near Nyquist

  • Signal: 10 Hz sine
  • Sampling: 22 Hz (just above 2×f_sig)
  • Purpose: Boundary conditions at Nyquist limit
  • Observation: Small reduction in fidelity; small phase distortion

Aliasing

  • Signal: 10 Hz sine
  • Sampling: 15 Hz (below 2×f_sig)
  • Purpose: Classic aliasing demonstration
  • Observation: Apparent alias at 5 Hz; reconstruction artifact

AM Sidebands

  • Signal: 25 Hz carrier, 3 Hz modulation (70% depth)
  • Sampling: 180 Hz
  • Purpose: Modulated signal bandwidth expansion
  • Observation: Spectral sidebands at 22 Hz and 28 Hz

DSP Functions (Pure API)

All DSP operations are available as pure functions for integration into other projects:

from aliasing_atlas.dsp import (
    sample_signal,
    quantize_signal,
    apply_anti_alias_filter,
    reconstruct_fft,
    reconstruct_foh,
    compute_spectrum,
    is_aliased,
    folded_alias_frequency,
)

# Example: Full pipeline
import numpy as np

# 1. Generate signal
t_cont = np.linspace(0, 0.3, 3000)
y_cont = np.sin(2*np.pi*10*t_cont)

# 2. Apply anti-alias filter
y_filt, _, _, _ = apply_anti_alias_filter(y_cont, t_cont, f_samp=30, aaf_type='Ideal')

# 3. Sample
t_samp, y_samp = sample_signal(t_cont, y_filt, f_samp=30, duration=0.3)

# 4. Quantize
y_quant = quantize_signal(y_samp, bits=8)

# 5. Reconstruct to a dense output grid
y_recon = reconstruct_fft(y_quant, num_output_points=len(t_cont))

# 6. Analyze
freq, mag, phase = compute_spectrum(y_quant, f_samp=30)
aliased = is_aliased(max_freq=10, f_samp=30)
alias_freq = folded_alias_frequency(max_freq=10, f_samp=30)

Testing

Run the comprehensive test suite:

.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q --cov=aliasing_atlas --cov-report=term-missing
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypy src/aliasing_atlas --ignore-missing-imports

Pull requests and pushes to main run the same tests, linting, type checking, notebook validation, and package build checks through GitHub Actions.

Test coverage includes:

  • DSP functions (sampling, quantization, filtering, reconstruction)
  • Signal generation (Fourier series, modulation, chirp)
  • Preset scenarios and pedagogical modes
  • Export functionality (JSON, WAV)

Project Structure

sinewave-sampling/
├── src/aliasing_atlas/              # Main package
│   ├── __init__.py                  # Version & public API
│   ├── __main__.py                  # CLI entry point
│   ├── app.py                       # Interactive GUI and orchestration
│   ├── dsp.py                       # Pure DSP functions
│   ├── signals.py                   # Signal generation models
│   ├── presets.py                   # Pedagogical presets
│   ├── learning.py                  # Learning hint engine
│   └── exporting.py                 # Export utilities
├── tests/                           # Test suite
│   ├── test_logic.py
│   ├── test_dsp.py
│   ├── test_presets.py
│   ├── test_phase4.py
│   └── test_exporting.py
├── AliasingAtlas.ipynb              # Interactive Jupyter notebook
├── pyproject.toml                   # Build configuration (PEP 517/518)
├── CONTRIBUTING.md                  # Contribution guidelines
├── GOVERNANCE.md                    # Project governance
├── SECURITY.md                      # Security policy
├── CHANGELOG.md                     # Release notes
└── README.md                        # This file

Documentation

Release Status

AliasingAtlas is published on PyPI. Releases are built and published automatically from version tags after tests, lint, and type checks pass; see RELEASING.md and CHANGELOG.md.

Examples

Example 1: Observing Aliasing

  1. Set Signal Frequency to 10 Hz
  2. Set Sampling Rate to 15 Hz (below 2×10=20 Hz Nyquist)
  3. Observe the predicted alias frequency (5 Hz) in status bar
  4. Notice the green FFT reconstruction shows a 5 Hz sine instead of 10 Hz
  5. Gradually increase sampling rate and watch the alias frequency decrease to zero

Example 2: Quantization Effects

  1. Set Bit Depth to 4 bits (16 levels)
  2. Observe heavy staircase patterns in time-domain plot
  3. Notice large error residuals in quantization plot
  4. Gradually increase bit depth and watch noise decrease
  5. At 16 bits, quantization noise becomes imperceptible

Example 3: Modulation

  1. Select "AM" waveform from Waveform selector
  2. Set Harmonic Frequency to 3 Hz and Harmonic Amp to 0.7
  3. Observe sidebands at ±3 Hz around carrier frequency in spectrum
  4. Toggle Anti-Alias to see filter response relative to modulation bandwidth
  5. Try FM for comparison of bandwidth and spectral characteristics

References

Textbooks

  • Oppenheim & Schafer, "Discrete-Time Signal Processing" (3rd ed.)
  • Proakis & Salehi, "Digital Signal Processing" (4th ed.)
  • Lyons, "Understanding Digital Signal Processing" (3rd ed.)

Standards

License

This project is licensed under the MIT License - see LICENSE for details.

Citation

If you use AliasingAtlas in academic research or teaching, please cite:

@software{aliasingatlas2024,
  author = {Wissem Boussetta},
  title = {AliasingAtlas: Interactive Tool for Visualizing Sampling and Aliasing},
  year = {2026},
  url = {https://github.com/Boussetta/NyquistNavigator}
}

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

  • Code of conduct
  • Development setup
  • Pull request guidelines
  • Coding standards
  • Testing requirements

Acknowledgments

  • Inspired by educational signal processing visualizations
  • Built with matplotlib for interactive visualization
  • NumPy/SciPy for numerical computation
  • Sounddevice and IPython for audio integration

Troubleshooting

"Module not found" when importing

Ensure package is installed:

python3 -m pip install -e .

If you are using Google Colab, run the Setup cell in AliasingAtlas.ipynb first; it installs the package from GitHub. If the sliders don't respond, use Runtime → Restart session and then Run all.

Audio not playing in Colab

The tool automatically detects the environment:

  • Desktop: Uses sounddevice for audio output (install with pip install -e ".[audio]")
  • Jupyter/Colab: Uses IPython.display.Audio with HTML5 playback

If audio still doesn't play, check browser speaker settings and console for warnings.

Slow rendering on large displays

Reduce num_continuous_points in code or use a lower resolution preset scenario.

Contact & Support


Made with ❤️ for signal processing education

Metadata

Release files for aliasing-atlas 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aliasing-atlas 2.0.0
File Size Uploaded Provenance Actions
aliasing_atlas-2.0.0.tar.gz 45.3 kB With provenance Details for aliasing_atlas-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aliasing-atlas 2.0.0
File Interpreter ABI Platform Actions
aliasing_atlas-2.0.0-py3-none-any.whl Python 3 none any Details for aliasing_atlas-2.0.0-py3-none-any.whl

Total release size: 81.0 kB

Release files / aliasing_atlas-2.0.0.tar.gz

Download URL aliasing_atlas-2.0.0.tar.gz
Size 45.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3655ed37245b381761cc92e6c8c846a9ed97ae5a08851ceccc6eb3dd3c9ea87e
BLAKE2b-256 checksum
How to use checksums
f0d22f226f905f4656e27a1a4ac3225060a149e2d0e699ac0b54eefc77f236a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / aliasing_atlas-2.0.0-py3-none-any.whl

Download URL aliasing_atlas-2.0.0-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
55ebbba7c7d3c4e5945090d4c7bce3537dac16b9b67ff0a7066b30e4eaf793db
BLAKE2b-256 checksum
How to use checksums
257feb44681d22f5d6ef9e8b51eed166a187bf0430282911bfaf2f4be2d231a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for aliasing-atlas 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aliasing_atlas-2.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page