matplotlibx 0.1.0__py3-none-any.whl

matplotlibx-0.1.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: matplotlibx
+Version: 0.1.0
+Summary: Enhanced Matplotlib wrapper with publication-quality styling and colorblind accessibility
+Author-email: Igor Sokolov <sokolov.igor.ch@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/isokolov/pltx
+Project-URL: Bug Tracker, https://github.com/isokolov/pltx/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: all
+Requires-Dist: seaborn>=0.11.0; extra == "all"
+Dynamic: license-file
+
+# pltx - Enhanced Matplotlib for Scientific Visualization
+
+**A matplotlib wrapper with publication-quality styling and colorblind accessibility features.**
+
+
+<img src="img/pltx.png" alt="pltx visualization" width="400">
+
+
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+<!-- [![License](https://img.shields.io/badge/license-APACHE-green.svg)](LICENSE) -->
+
+---
+
+I got bored to always create some custom formatting for my plots, run into reviewers asking for improving readability.
+I want just to import and use it with minor modifications. Here I made something one can install and have pretty looking plots ready to go (just some personal styling on top of matplotlib).
+
+
+Credits to Mathieu Garrigues for Pasqal colormap.
+
+## Key Features
+
+- **Colorblind Accessible** - Progressive line width variation distinguishes lines by thickness AND color
+- **Journal-Ready Presets** - Nature, presentation, and poster styles in one function call
+- **Line Visibility** - Optional outlines and centerlines for better contrast
+- **Drop-in Replacement** - Works with all matplotlib plot types
+- **Auto Color Cycling** - Intelligent palette management with intensity control
+
+## Example Gallery
+
+<img src="img/showcase.png" alt="pltx visualization" width="600">
+
+
+## Quick Start
+
+```python
+import pltx.pyplot as plt
+import numpy as np
+
+# Enable colorblind-friendly progressive widths
+plt.initialize_style(
+    palette_name='pasqal',
+    vary_linewidth=True,              # Lines get progressively thicker
+    linewidth_progression_factor=1.3  # 30% increase per line
+)
+
+# Plot with automatic styling
+x = np.linspace(0, 10, 100)
+for i in range(5):
+    plt.plot_styled(x, np.sin(x + i*0.5),
+                   color_idx=i,
+                   centerline=True,  # Add thin line on top
+                   label=f'Line {i+1}')
+
+plt.setup_axis(xlabel='x', ylabel='y', grid=True)
+plt.legend()
+plt.savefig('plot.png', dpi=300)
+```
+
+<img src="img/plot.png" alt="pltx visualization" width="600">
+
+Some other examples of the colormaps for which you can use `examples/generate_readme_images.py` script.
+
+<img src="img/pasqal_heatmaps.png" alt="pltx visualization" width="600">
+<img src="img/pasqal_swatches.png" alt="pltx visualization" width="600">
+<img src="img/pasqal_sine_cosine.png" alt="pltx visualization" width="600">
+
+
+## Installation
+
+```bash
+pip install pltx
+
+# With optional seaborn support for extended palettes
+pip install pltx[all]
+```
+
+## Key Features in Detail
+
+### 1. Progressive Line Width (Colorblind Accessible)
+
+Each line automatically gets thicker - distinguishable by both color and width:
+
+```python
+plt.initialize_style(
+    vary_linewidth=True,
+    base_linewidth=2.0,
+    linewidth_progression_factor=1.3  # 1.2=gentle, 1.3=moderate, 1.5=strong
+)
+```
+
+**Result:** Line 0: 2.0pt -> Line 1: 2.6pt -> Line 2: 3.4pt -> Line 3: 4.4pt
+
+### 2. Line Enhancements
+
+```python
+# Outline (thick line behind)
+plt.plot_styled(x, y, color_idx=0, outline=True)
+
+# Centerline (thin line on top)
+plt.plot_styled(x, y, color_idx=0, centerline=True)
+
+# Both (maximum contrast)
+plt.plot_styled(x, y, color_idx=0, outline=True, centerline=True)
+```
+
+### 3. Journal Presets
+
+```python
+from pltx.rcparams import apply_style_preset
+
+apply_style_preset('nature')        # Nature journal (Arial, 7-9pt, 3.5")
+apply_style_preset('presentation')  # Slides (16-18pt, thick lines)
+apply_style_preset('poster')        # Posters (24-28pt)
+```
+
+### 4. Works with All Plot Types
+
+```python
+from pltx.colors import get_color
+
+# Bar plots
+colors = [get_color(i) for i in range(5)]
+plt.bar(categories, values, color=colors)
+
+# Scatter plots
+plt.plot_styled(x, y, marker='o', linestyle='', color_idx=0)
+
+# All matplotlib functions available!
+```
+
+## Real-World Example
+
+### Nature Journal Submission
+
+```python
+from pltx.rcparams import apply_style_preset
+import pltx.pyplot as plt
+
+# Apply Nature style + accessibility
+apply_style_preset('nature')
+plt.initialize_style(
+    vary_linewidth=True,
+    base_linewidth=1.0,
+    linewidth_progression_factor=1.3
+)
+
+# Single column figure
+fig, ax = plt.subplots(figsize=(3.5, 2.6))
+
+for i in range(4):
+    plt.plot_styled(x, data[i],
+                   color_idx=i,
+                   centerline=True,  # Better in print
+                   label=labels[i])
+
+plt.setup_axis(xlabel='Time (s)', ylabel='Amplitude (a.u.)')
+plt.legend()
+plt.savefig('figure1.pdf', dpi=300)
+```
+
+## Documentation
+
+- **[FULL_DOCUMENTATION.md](FULL_DOCUMENTATION.md)** - Complete API reference and detailed guide
+- **[examples/](examples/)** - Working examples (demo.py, showcase.py, simple_example.py)
+- 12 test PDFs demonstrating all features
+
+## Quick Reference
+
+| Feature | Command |
+|---------|---------|
+| Progressive width | `vary_linewidth=True` |
+| Outline | `outline=True` |
+| Centerline | `centerline=True` |
+| Nature style | `apply_style_preset('nature')` |
+| Color cycling | `color_idx=i` |
+| Axis setup | `setup_axis(xlabel=..., ylabel=...)` |
+
+## Feature Comparison
+
+| Feature | matplotlib | pltx |
+|---------|-----------|------|
+| Colorblind accessible | Manual | `vary_linewidth=True` |
+| Line visibility | Complex code | `outline=True` |
+| Journal styles | Research guidelines | One function call |
+| Color palettes | Manual setup | Automatic |
+
+## Progressive Width Factors
+
+| Factor | Increase | Best For |
+|--------|----------|----------|
+| 1.2 | 20% | 8-10 lines |
+| 1.3 | 30% | 4-6 lines (DEFAULT) |
+| 1.5 | 50% | 2-4 lines |
+
+## Style Presets
+
+| Preset | Fonts | Figure Size | Use Case |
+|--------|-------|-------------|----------|
+| nature | 7-9pt | 3.5"x2.6" | Nature journal |
+| presentation | 16-18pt | 10"x6" | Slides |
+| poster | 24-28pt | 12"x8" | Posters |
+| default | 12-13pt | 6"x4" | General |
+
+## Dependencies
+
+**Required:**
+- matplotlib >= 3.5.0
+- numpy >= 1.20.0
+
+**Optional:**
+- seaborn >= 0.11.0 (for extended palettes; falls back to matplotlib colormaps)
+
+## Why pltx?
+
+- **Accessible** - Works for colorblind viewers (~8% of males)
+- **Publication-Ready** - Journal-specific presets
+- **Easy to Use** - Drop-in replacement for matplotlib
+- **Flexible** - Works with all plot types
+- **Well-Documented** - Comprehensive guides and examples
+
+## Quick Tips
+
+1. **Always use** `vary_linewidth=True` for multi-line plots
+2. **Choose factor** based on number of lines (1.2 for many, 1.5 for few)
+3. **Test in grayscale** to verify accessibility
+4. **Use presets** to match your target medium
+5. **Combine features** for maximum effect
+
+## Testing
+
+The package includes a comprehensive test suite using `pytest`.
+
+```bash
+# Install test dependencies
+pip install pytest
+
+# Run all tests
+pytest tests
+```
+
+The test suite covers color palette logic, style initialization, enhanced plotting functions, and style context management.
+
+
+---
+
+**Version:** 0.1.0
+**Python:** 3.10+
+**Created:** 2026-01-09
+**Author:** Igor Sokolov
+
+For complete documentation, see [FULL_DOCUMENTATION.md](FULL_DOCUMENTATION.md)

matplotlibx-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+matplotlibx-0.1.0.dist-info/licenses/LICENSE,sha256=wb8wd58mXxEg2_oT9igF1MDuWtT68qfPCh8L7bTVjwc,1069
+pltx/__init__.py,sha256=8sTnid4l5tkZvUKIddWrBykbC51d0iqsa_jO4cqV_l0,86
+pltx/colors.py,sha256=v_bXazCiIFzd_Xpi_QV5d6tOXS7TrYWTXU_9PoNvHf4,8485
+pltx/pyplot.py,sha256=ePyqwf11b7Tt1CtTMKOnsBcQO5f9jlQbtG5gcPM22Bc,14239
+pltx/rcparams.py,sha256=zEl70LP1QNf7Ee0Se4b0kZJatL3zSN4wIGmYAaFSOfc,8919
+pltx/style.py,sha256=8eW3WwKensMZKL_QmCI3Km4V8rIVTHUywnuGY4wLBts,24473
+matplotlibx-0.1.0.dist-info/METADATA,sha256=S4KlJKD9W1YdlfmgyX6EEWz9x_0pcy9N1Qdfg7UVAIQ,7976
+matplotlibx-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+matplotlibx-0.1.0.dist-info/top_level.txt,sha256=jpElzOmUpfFC4IoEBFvyUA9zYKlg9RPr59Iv14MrzFc,5
+matplotlibx-0.1.0.dist-info/RECORD,,

matplotlibx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

matplotlibx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Sokolov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matplotlibx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pltx

pltx/__init__.py

@@ -0,0 +1,3 @@
+"""pltx - Enhanced Matplotlib for Scientific Visualization."""
+
+__version__ = "0.1.0"

pltx/colors.py

@@ -0,0 +1,335 @@
+"""Color palettes and utilities for pltx."""
+
+from typing import List, Tuple
+import numpy as np
+import matplotlib.pyplot as plt
+
+try:
+    import seaborn as sns
+    HAS_SEABORN = True
+except ImportError:
+    HAS_SEABORN = False
+
+# Type alias for RGB color
+Color = Tuple[float, float, float]
+
+
+class ColorPalette:
+    """Manages color palettes for scientific visualizations."""
+
+    # Default palettes - easily customizable
+    DEFAULT_PALETTE = "plasma_r"
+    DEFAULT_SIZE = 10
+
+    # Predefined palette collections
+    SEQUENTIAL_PALETTES = [
+        "plasma_r",
+        "viridis",
+        "mako_r",
+        "rocket_r",
+        "crest",
+    ]
+
+    DIVERGING_PALETTES = [
+        "coolwarm",
+        "RdBu_r",
+        "vlag",
+        "icefire",
+    ]
+
+    CATEGORICAL_PALETTES = [
+        "tab10",
+        "Set2",
+        "husl",
+        "Paired",
+    ]
+
+    def __init__(
+        self,
+        palette_name: str = DEFAULT_PALETTE,
+        palette_size: int = DEFAULT_SIZE,
+    ):
+        """Initialize color palette.
+
+        Parameters
+        ----------
+        palette_name : str
+            Name of the seaborn or matplotlib color palette
+        palette_size : int
+            Number of colors in the palette
+        """
+        self.palette_name = palette_name
+        self.palette_size = palette_size
+        self._palette = self._create_palette(palette_name, palette_size)
+
+    @staticmethod
+    def _create_palette(palette_name: str, palette_size: int) -> List[Color]:
+        """Create color palette using seaborn if available, else matplotlib.
+
+        If seaborn is available but doesn't know the palette name (e.g. it is
+        a registered matplotlib colormap such as 'pasqal'), we fall back to
+        sampling the matplotlib colormap directly.
+
+        Parameters
+        ----------
+        palette_name : str
+            Name of the color palette (seaborn palette or mpl colormap name)
+        palette_size : int
+            Number of colors
+
+        Returns
+        -------
+        List[Color]
+            List of RGB tuples
+        """
+        if HAS_SEABORN:
+            try:
+                return sns.color_palette(palette_name, palette_size)
+            except (ValueError, KeyError):
+                # palette_name is not a seaborn palette — try it as an mpl
+                # colormap (e.g. a custom one registered via mpl.colormaps)
+                pass
+
+        # Sample from matplotlib colormap
+        try:
+            cmap = plt.get_cmap(palette_name)
+        except (ValueError, KeyError):
+            # Last resort: fall back to viridis
+            cmap = plt.get_cmap('viridis')
+
+        # Sample colors evenly across the colormap
+        colors = [
+            cmap(i / max(palette_size - 1, 1))
+            for i in range(palette_size)
+        ]
+        # Convert to RGB tuples (drop alpha channel)
+        return [(c[0], c[1], c[2]) for c in colors]
+
+    @property
+    def palette(self) -> List[Color]:
+        """Get the current color palette."""
+        return self._palette
+
+    def get_color(self, idx: int) -> Color:
+        """Get a color from the palette by index.
+
+        Parameters
+        ----------
+        idx : int
+            Index of the color in the palette
+
+        Returns
+        -------
+        Color
+            RGB color tuple
+
+        Raises
+        ------
+        IndexError
+            If index is out of range
+        """
+        if idx < 0 or idx >= len(self._palette):
+            raise IndexError(
+                f"Color index {idx} out of range "
+                f"for palette of size {len(self._palette)}"
+            )
+        return self._palette[idx]
+
+    def get_colors(self, indices: List[int]) -> List[Color]:
+        """Get multiple colors from the palette.
+
+        Parameters
+        ----------
+        indices : List[int]
+            Indices of colors to retrieve
+
+        Returns
+        -------
+        List[Color]
+            List of RGB color tuples
+        """
+        return [self.get_color(idx) for idx in indices]
+
+    def cycle_color(self, idx: int) -> Color:
+        """Get a color with automatic wrapping for large indices.
+
+        Parameters
+        ----------
+        idx : int
+            Index (will be wrapped if >= palette_size)
+
+        Returns
+        -------
+        Color
+            RGB color tuple
+        """
+        return self._palette[idx % len(self._palette)]
+
+    @staticmethod
+    def adjust_intensity(
+        color: Color,
+        intensity: float,
+    ) -> Color:
+        """Adjust color intensity (brightness).
+
+        Parameters
+        ----------
+        color : Color
+            RGB color tuple
+        intensity : float
+            Intensity factor (0.0-1.0). Lower values make colors lighter.
+
+        Returns
+        -------
+        Color
+            Adjusted RGB color tuple
+        """
+        intensity = np.clip(intensity, 0.0, 1.0)
+        return tuple(c * intensity + (1 - intensity) for c in color)
+
+    @staticmethod
+    def adjust_alpha(
+        color: Color,
+        alpha: float,
+    ) -> Tuple[float, float, float, float]:
+        """Add alpha channel to RGB color.
+
+        Parameters
+        ----------
+        color : Color
+            RGB color tuple
+        alpha : float
+            Alpha value (0.0-1.0)
+
+        Returns
+        -------
+        Tuple[float, float, float, float]
+            RGBA color tuple
+        """
+        alpha = np.clip(alpha, 0.0, 1.0)
+        return (*color, alpha)
+
+    @staticmethod
+    def create_gradient(
+        color1: Color,
+        color2: Color,
+        n_steps: int,
+    ) -> List[Color]:
+        """Create a gradient between two colors.
+
+        Parameters
+        ----------
+        color1 : Color
+            Starting color
+        color2 : Color
+            Ending color
+        n_steps : int
+            Number of steps in the gradient
+
+        Returns
+        -------
+        List[Color]
+            List of colors forming the gradient
+        """
+        gradient = []
+        for i in range(n_steps):
+            t = i / (n_steps - 1)
+            color = tuple(
+                c1 * (1 - t) + c2 * t
+                for c1, c2 in zip(color1, color2)
+            )
+            gradient.append(color)
+        return gradient
+
+    def set_palette(
+        self,
+        palette_name: str,
+        palette_size: int = None,
+    ) -> None:
+        """Change the current palette.
+
+        Parameters
+        ----------
+        palette_name : str
+            Name of the seaborn or matplotlib color palette
+        palette_size : int, optional
+            Number of colors. If None, uses current palette_size.
+        """
+        self.palette_name = palette_name
+        if palette_size is not None:
+            self.palette_size = palette_size
+        self._palette = self._create_palette(self.palette_name, self.palette_size)
+
+    def __len__(self) -> int:
+        """Return the number of colors in the palette."""
+        return len(self._palette)
+
+    def __getitem__(self, idx: int) -> Color:
+        """Get a color by index."""
+        return self.get_color(idx)
+
+    def __iter__(self):
+        """Iterate over colors in the palette."""
+        return iter(self._palette)
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"ColorPalette('{self.palette_name}', size={self.palette_size})"
+
+
+# Global default color palette
+_default_palette = ColorPalette()
+
+
+def get_default_palette() -> ColorPalette:
+    """Get the global default color palette."""
+    return _default_palette
+
+
+def set_default_palette(
+    palette_name: str,
+    palette_size: int = ColorPalette.DEFAULT_SIZE,
+) -> None:
+    """Set the global default color palette.
+
+    Parameters
+    ----------
+    palette_name : str
+        Name of the seaborn color palette
+    palette_size : int
+        Number of colors in the palette
+    """
+    global _default_palette
+    _default_palette = ColorPalette(palette_name, palette_size)
+
+
+def get_color(idx: int) -> Color:
+    """Get a color from the default palette.
+
+    Parameters
+    ----------
+    idx : int
+        Color index
+
+    Returns
+    -------
+    Color
+        RGB color tuple
+    """
+    return _default_palette.get_color(idx)
+
+
+def cycle_color(idx: int) -> Color:
+    """Get a color from the default palette with automatic wrapping.
+
+    Parameters
+    ----------
+    idx : int
+        Color index (will wrap if >= palette size)
+
+    Returns
+    -------
+    Color
+        RGB color tuple
+    """
+    return _default_palette.cycle_color(idx)