Refactor Examples: Extract Plotting Code and Convert Print Statements to Comments #34

Enhance visualization and utility functions

- Updated BenchmarkVisualizer to use custom color maps for throughput and execution time bar plots.
- Refactored visualize_metrics_comparison to simplify bar plotting logic and improve error handling.
- Improved SoftBitEnsembleThresholder to handle weight normalization more robustly.
- Added validation for code_length and code_dimension in LDPCCodeEncoder, ensuring proper error messages for missing parameters.
- Introduced PlottingUtils class for centralized plotting utilities, including functions for LDPC matrix comparison, BER performance, and more.
- Added comprehensive plotting functions for signal analysis, channel effects, and capacity analysis.

Author: selimfirat

.pre-commit-config.yaml

@@ -82,12 +82,19 @@ repos:
 
   # Type checking with mypy (fixed)
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.15.0
+    rev: v1.16.0
     hooks:
       - id: mypy
         # Removed problematic types-all and added specific type stubs
         additional_dependencies:
-          [types-requests, types-PyYAML, types-toml, types-setuptools]
+          [
+            types-requests,
+            types-PyYAML,
+            types-toml,
+            types-setuptools,
+            types-tqdm,
+            types-seaborn,
+          ]
         exclude: "^tests/"
 
   # Python security linter

docs/api_reference.rst

@@ -721,6 +721,7 @@ General utility functions for the Kaira library.
    :nosignatures:
 
    CapacityAnalyzer
+   PlottingUtils
 
 
 .. currentmodule:: kaira.utils

docs/examples/example_utils/index.rst

@@ -0,0 +1,36 @@
+:orphan:
+
+Example Utils
+=============
+
+Examples for example utils.
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the :class:`kaira.utils.CapacityAnalyzer` to analyze the capacity of various modulation schemes and channel models. Channel capacity is a fundamental concept in information theory that represents the maximum rate at which information can be reliably transmitted over a communication channel. It was first introduced by Claude Shannon :cite:`shannon1948mathematical`. .. note:: This example requires matplotlib for visualization and seaborn for enhanced styling. To run faster, set the FAST_MODE flag to True below.">
+
+.. only:: html
+
+    .. image:: /auto_examples/example_utils/images/thumb/sphx_glr_plot_capacity_analyzer_thumb.png
+      :alt: Channel Capacity Analysis with Kaira
+
+    :ref:`sphx_glr_auto_examples_example_utils_plot_capacity_analyzer.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Channel Capacity Analysis with Kaira</div>
+    </div>
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree:
+   :hidden:
+
+   /auto_examples/example_utils/plot_capacity_analyzer

docs/examples/modulation/index.rst

@@ -159,10 +159,10 @@ Digital modulation schemes and their characteristics in Kaira. These examples sh
 
 .. only:: html
 
-    .. image:: /auto_examples/modulation/images/thumb/sphx_glr_plot_qam_modulation_thumb.png
+    .. image:: /auto_examples/modulation/images/thumb/sphx_glr_plot_qam_modulation_refactored_thumb.png
       :alt: Quadrature Amplitude Modulation (QAM)
 
-    :ref:`sphx_glr_auto_examples_modulation_plot_qam_modulation.py`
+    :ref:`sphx_glr_auto_examples_modulation_plot_qam_modulation_refactored.py`
 
 .. raw:: html
 
@@ -186,4 +186,4 @@ Digital modulation schemes and their characteristics in Kaira. These examples sh
    /auto_examples/modulation/plot_pam_modulation
    /auto_examples/modulation/plot_pi4qpsk_modulation
    /auto_examples/modulation/plot_psk_modulation
-   /auto_examples/modulation/plot_qam_modulation
+   /auto_examples/modulation/plot_qam_modulation_refactored

examples/benchmarks/plot_ldpc_codes_comparison.py

@@ -21,6 +21,7 @@
 import time
 from typing import Any, Dict, List, Tuple
 
+import matplotlib.cm as cm
 import matplotlib.pyplot as plt
 import numpy as np
 import seaborn as sns
@@ -652,7 +653,7 @@ def simulate_ldpc_performance(ldpc_config: Dict[str, Any], snr_db_values: np.nda
     if standard_counts:
         standards = list(standard_counts.keys())
         counts = list(standard_counts.values())
-        colors = plt.cm.get_cmap("Set3")(np.linspace(0, 1, len(standards)))
+        colors = cm.get_cmap("Set3")(np.linspace(0, 1, len(standards)))
 
         wedges, texts, autotexts = ax4.pie(counts, labels=standards, colors=colors, autopct="%1.0f", startangle=90)
         ax4.set_title("Professional: Standards\nCompliance", fontsize=12, fontweight="bold")
@@ -884,7 +885,7 @@ def simulate_ldpc_performance(ldpc_config: Dict[str, Any], snr_db_values: np.nda
     ax1 = fig_standards.add_subplot(gs_standards[0, 0])
     standards_names = list(standards_data.keys())
     standards_counts = [len(codes) for codes in standards_data.values()]
-    colors = plt.cm.get_cmap("Set3")(np.linspace(0, 1, len(standards_names)))
+    colors = cm.get_cmap("Set3")(np.linspace(0, 1, len(standards_names)))
 
     wedges, texts, autotexts = ax1.pie(standards_counts, labels=standards_names, colors=colors, autopct="%1.0f", startangle=90)
     ax1.set_title("Standards Distribution\nin Benchmark", fontsize=12, fontweight="bold")

examples/channels/plot_awgn_channel.py

@@ -18,14 +18,12 @@
 import numpy as np
 import torch
 
-from examples.utils.plotting import (
-    setup_plotting_style,
+from examples.example_utils.plotting import (
     plot_signal_noise_comparison,
     plot_snr_psnr_comparison,
     plot_snr_vs_mse,
-    plot_noise_level_analysis
+    setup_plotting_style,
 )
-
 from kaira.channels import AWGNChannel
 from kaira.metrics.image import PSNR
 from kaira.metrics.signal import SNR
@@ -114,11 +112,10 @@
 
 # Visualization: Signal Degradation with Noise
 # ============================================
-# Compare the original clean signal with signals processed through 
+# Compare the original clean signal with signals processed through
 # AWGN channels at different SNR levels to observe noise effects.
 
-fig = plot_signal_noise_comparison(t, signal, outputs, measured_metrics, 
-                                 "AWGN Channel Effects on Signal Transmission")
+fig = plot_signal_noise_comparison(t, signal, outputs, measured_metrics, "AWGN Channel Effects on Signal Transmission")
 fig.show()
 
 # %%

examples/channels/plot_binary_channels.py

@@ -21,14 +21,13 @@
 import numpy as np
 import torch
 
-from examples.utils.plotting import (
-    setup_plotting_style,
+from examples.example_utils.plotting import (
     plot_binary_channel_comparison,
+    plot_channel_capacity_analysis,
     plot_channel_error_rates,
     plot_transition_matrices,
-    plot_channel_capacity_analysis
+    setup_plotting_style,
 )
-
 from kaira.channels import BinaryErasureChannel, BinarySymmetricChannel, BinaryZChannel
 
 # Set random seed for reproducibility
@@ -75,7 +74,7 @@
 
     bsc_outputs.append((p, output, error_rate))
     # BSC Channel Analysis Results
-    # ===========================  
+    # ===========================
     # BSC (p={p}): Errors: {errors}/{num_bits}, Error rate: {error_rate:.4f}
 
 # %%
@@ -152,7 +151,7 @@
     bsc_output = bsc(binary_data).numpy()[0]
 channel_outputs.append(("BSC", bsc_output, bsc_p))
 
-# BEC output (high erasure probability for visibility)  
+# BEC output (high erasure probability for visibility)
 bec_p = 0.2
 bec = BinaryErasureChannel(erasure_prob=bec_p)
 with torch.no_grad():
@@ -168,9 +167,7 @@
 
 # Visualize channel effects
 original_data = binary_data[0].numpy()
-fig = plot_binary_channel_comparison(original_data, channel_outputs, 
-                                   segment_start, segment_length,
-                                   "Binary Channel Effects Comparison")
+fig = plot_binary_channel_comparison(original_data, channel_outputs, segment_start, segment_length, "Binary Channel Effects Comparison")
 fig.show()
 
 # %%
@@ -180,25 +177,23 @@
 
 # Channel Error Rate Analysis
 # ===========================
-# Compare theoretical vs observed error rates across different 
+# Compare theoretical vs observed error rates across different
 # channel types to validate the implementation accuracy.
 
 # Prepare BSC error rate data
 theoretical_bsc = error_probs  # Theoretical error rate equals p
 observed_bsc = [err_rate for _, _, err_rate in bsc_outputs]
 
 # Plot BSC error rates
-fig1 = plot_channel_error_rates(error_probs, theoretical_bsc, observed_bsc, 
-                               ["BSC"], "Binary Symmetric Channel Error Rates")
+fig1 = plot_channel_error_rates(error_probs, theoretical_bsc, observed_bsc, ["BSC"], "Binary Symmetric Channel Error Rates")
 fig1.show()
 
-# Prepare BEC erasure rate data  
+# Prepare BEC erasure rate data
 theoretical_bec = erasure_probs  # Theoretical erasure rate equals p
 observed_bec = [erasure_rate for _, _, erasure_rate in bec_outputs]
 
 # Plot BEC erasure rates
-fig2 = plot_channel_error_rates(erasure_probs, theoretical_bec, observed_bec,
-                               ["BEC"], "Binary Erasure Channel Erasure Rates") 
+fig2 = plot_channel_error_rates(erasure_probs, theoretical_bec, observed_bec, ["BEC"], "Binary Erasure Channel Erasure Rates")
 fig2.show()
 
 # Prepare Z-Channel error rate data
@@ -208,8 +203,7 @@
 observed_z = [err_rate * p_one for _, _, err_rate in z_outputs]
 
 # Plot Z-Channel error rates
-fig3 = plot_channel_error_rates(z_error_probs, theoretical_z, observed_z,
-                               ["Z-Channel"], "Z-Channel Error Rates")
+fig3 = plot_channel_error_rates(z_error_probs, theoretical_z, observed_z, ["Z-Channel"], "Z-Channel Error Rates")
 fig3.show()
 
 # %%
@@ -234,11 +228,7 @@
 z_matrix = np.array([[1, 0], [p_z, 1 - p_z]])
 
 # Plot transition matrices
-matrices = [
-    ("Binary Symmetric Channel", bsc_matrix, p_bsc),
-    ("Binary Erasure Channel", bec_matrix, p_bec),
-    ("Z-Channel", z_matrix, p_z)
-]
+matrices = [("Binary Symmetric Channel", bsc_matrix, p_bsc), ("Binary Erasure Channel", bec_matrix, p_bec), ("Z-Channel", z_matrix, p_z)]
 
 fig4 = plot_transition_matrices(matrices, "Binary Channel Transition Matrices")
 fig4.show()
@@ -256,40 +246,39 @@
 # Parameter ranges for capacity analysis
 p_range = np.linspace(0, 1, 51)
 
+
 # Calculate capacities for each channel type
 def calculate_bsc_capacity(p):
     """Calculate BSC capacity: C = 1 - H(p)"""
     if p == 0 or p == 1:
         return 1.0 if p == 0 else 0.0
     return 1 + p * np.log2(p) + (1 - p) * np.log2(1 - p)
 
+
 def calculate_bec_capacity(p):
     """Calculate BEC capacity: C = 1 - p"""
     return 1 - p
 
+
 def calculate_z_capacity(p):
-    """Calculate Z-channel capacity"""
+    """Calculate Z-channel capacity."""
     if p == 0:
         return 1.0
     if p == 1:
         return 0.0
     # Z-channel capacity formula
     return 1 + (1 - p) * np.log2(1 - p) + p * np.log2(p)
 
+
 # Calculate capacities
 bsc_capacities = np.array([calculate_bsc_capacity(p) for p in p_range])
 bec_capacities = np.array([calculate_bec_capacity(p) for p in p_range])
 z_capacities = np.array([calculate_z_capacity(p) for p in p_range])
 
 # Plot capacity analysis
-capacities = {
-    "BSC": bsc_capacities,
-    "BEC": bec_capacities,
-    "Z-Channel": z_capacities
-}
-
-fig5 = plot_channel_capacity_analysis(p_range, capacities, 
-                                    "Binary Channel Capacity Analysis")
+capacities = {"BSC": bsc_capacities, "BEC": bec_capacities, "Z-Channel": z_capacities}
+
+fig5 = plot_channel_capacity_analysis(p_range, capacities, "Binary Channel Capacity Analysis")
 fig5.show()
 
 # %%

examples/channels/plot_fading_channels.py

@@ -12,20 +12,19 @@
 magnitude of fading.
 """
 
+import matplotlib.pyplot as plt
 import numpy as np
 import torch
 from scipy import signal
 
+# Plotting imports
+from examples.example_utils.plotting import setup_plotting_style
 from kaira.channels import AWGNChannel, FlatFadingChannel, PerfectChannel
 from kaira.metrics.signal import BitErrorRate
 from kaira.modulations import QPSKModulator
 from kaira.modulations.utils import calculate_theoretical_ber
 from kaira.utils import snr_to_noise_power
 
-# Plotting imports
-from examples.utils.plotting import setup_plotting_style
-import matplotlib.pyplot as plt
-
 setup_plotting_style()
 
 # %%
@@ -43,7 +42,7 @@
 # ------------------------------------
 # QPSK Signal Generation
 # =====================
-# 
+#
 # Let's use Kaira's QPSKModulator to generate QPSK symbols.
 
 # Create a QPSK modulator
@@ -90,7 +89,7 @@
 # ------------------------------------------
 # Channel Configuration and Setup
 # ===============================
-# 
+#
 # We'll compare a perfect channel (no distortion), an AWGN channel (noise only),
 # and a flat fading channel (fading + noise).
 

examples/constraints/plot_basic_constraints.py

@@ -12,19 +12,18 @@
 # ----------------------------------------------------------
 # We start by importing the necessary modules and setting up the environment.
 
+import matplotlib.pyplot as plt
 import numpy as np
 import torch
 
-from kaira.constraints import AveragePowerConstraint, PAPRConstraint, TotalPowerConstraint
-from kaira.constraints.utils import measure_signal_properties
-
 # Plotting imports
-from examples.utils.plotting import (
-    setup_plotting_style,
+from examples.example_utils.plotting import (
     plot_constraint_comparison,
-    plot_signal_properties_comparison
+    plot_signal_properties_comparison,
+    setup_plotting_style,
 )
-import matplotlib.pyplot as plt
+from kaira.constraints import AveragePowerConstraint, PAPRConstraint, TotalPowerConstraint
+from kaira.constraints.utils import measure_signal_properties
 
 setup_plotting_style()