figrecipe 0.5.0__py3-none-any.whl

figrecipe/_utils/_diff.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Utilities for comparing default vs passed values."""
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+
+def is_default_value(value: Any, default: Any) -> bool:
+    """Check if value equals the default.
+
+    Parameters
+    ----------
+    value : Any
+        Value to check.
+    default : Any
+        Default value.
+
+    Returns
+    -------
+    bool
+        True if value equals default.
+    """
+    # Handle None
+    if value is None and default is None:
+        return True
+
+    # Handle numpy arrays
+    if isinstance(value, np.ndarray) or isinstance(default, np.ndarray):
+        try:
+            return np.array_equal(value, default)
+        except (TypeError, ValueError):
+            return False
+
+    # Handle callables
+    if callable(value) or callable(default):
+        return value is default
+
+    # Standard comparison
+    try:
+        return value == default
+    except (TypeError, ValueError):
+        return False
+
+
+def get_non_default_kwargs(
+    passed_kwargs: Dict[str, Any],
+    signature_defaults: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Filter kwargs to only include non-default values.
+
+    Parameters
+    ----------
+    passed_kwargs : dict
+        Kwargs that were passed to the function.
+    signature_defaults : dict, optional
+        Default values from function signature.
+
+    Returns
+    -------
+    dict
+        Only kwargs that differ from defaults.
+    """
+    if signature_defaults is None:
+        # If no defaults provided, return all kwargs
+        return passed_kwargs.copy()
+
+    non_default = {}
+    for key, value in passed_kwargs.items():
+        default = signature_defaults.get(key)
+        if not is_default_value(value, default):
+            non_default[key] = value
+
+    return non_default
+
+
+def merge_with_defaults(
+    stored_kwargs: Dict[str, Any],
+    signature_defaults: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Merge stored kwargs with defaults for reproduction.
+
+    Parameters
+    ----------
+    stored_kwargs : dict
+        Non-default kwargs that were stored.
+    signature_defaults : dict
+        Default values from function signature.
+
+    Returns
+    -------
+    dict
+        Complete kwargs for function call.
+    """
+    merged = signature_defaults.copy()
+    merged.update(stored_kwargs)
+    return merged

figrecipe/_utils/_image_diff.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Image comparison utilities for roundtrip testing."""
+
+from pathlib import Path
+from typing import Tuple, Union
+
+import numpy as np
+
+
+def load_image(path: Union[str, Path]) -> np.ndarray:
+    """Load image as numpy array.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to image file.
+
+    Returns
+    -------
+    np.ndarray
+        Image as (H, W, C) array with values 0-255.
+    """
+    from PIL import Image
+    img = Image.open(path).convert('RGB')
+    return np.array(img)
+
+
+def compute_diff(
+    img1: np.ndarray,
+    img2: np.ndarray,
+) -> Tuple[float, np.ndarray]:
+    """Compute pixel-level difference between two images.
+
+    Parameters
+    ----------
+    img1 : np.ndarray
+        First image (H, W, C).
+    img2 : np.ndarray
+        Second image (H, W, C).
+
+    Returns
+    -------
+    mse : float
+        Mean squared error (0 = identical).
+    diff_img : np.ndarray
+        Difference image (absolute difference).
+    """
+    # Ensure same shape
+    if img1.shape != img2.shape:
+        raise ValueError(
+            f"Image shapes differ: {img1.shape} vs {img2.shape}"
+        )
+
+    # Compute difference
+    diff = np.abs(img1.astype(float) - img2.astype(float))
+    mse = np.mean(diff ** 2)
+
+    # Normalize diff for visualization
+    diff_img = (diff / diff.max() * 255).astype(np.uint8) if diff.max() > 0 else diff.astype(np.uint8)
+
+    return mse, diff_img
+
+
+def compare_images(
+    path1: Union[str, Path],
+    path2: Union[str, Path],
+    diff_path: Union[str, Path] = None,
+) -> dict:
+    """Compare two image files.
+
+    Parameters
+    ----------
+    path1 : str or Path
+        Path to first image.
+    path2 : str or Path
+        Path to second image.
+    diff_path : str or Path, optional
+        If provided, save difference image here.
+
+    Returns
+    -------
+    dict
+        Comparison results:
+        - identical: bool (True if MSE == 0)
+        - mse: float (mean squared error)
+        - psnr: float (peak signal-to-noise ratio, inf if identical)
+        - max_diff: float (maximum pixel difference)
+        - size1: tuple (H, W) of first image
+        - size2: tuple (H, W) of second image
+        - same_size: bool (True if dimensions match)
+        - file_size1: int (file size in bytes)
+        - file_size2: int (file size in bytes)
+    """
+    import os
+
+    img1 = load_image(path1)
+    img2 = load_image(path2)
+
+    # File sizes
+    file_size1 = os.path.getsize(path1)
+    file_size2 = os.path.getsize(path2)
+
+    # Check if same size
+    same_size = img1.shape == img2.shape
+
+    if same_size:
+        mse, diff_img = compute_diff(img1, img2)
+    else:
+        # Can't compute pixel diff for different sizes
+        mse = float('nan')
+        diff_img = None
+
+    # Peak signal-to-noise ratio
+    if mse == 0:
+        psnr = float('inf')
+    elif np.isnan(mse):
+        psnr = float('nan')
+    else:
+        psnr = 10 * np.log10(255**2 / mse)
+
+    # Max difference
+    if same_size:
+        max_diff = np.max(np.abs(img1.astype(float) - img2.astype(float)))
+    else:
+        max_diff = float('nan')
+
+    # Save diff image if requested
+    if diff_path is not None and diff_img is not None:
+        from PIL import Image
+        Image.fromarray(diff_img).save(diff_path)
+
+    return {
+        'identical': mse == 0,
+        'mse': float(mse),
+        'psnr': float(psnr),
+        'max_diff': float(max_diff),
+        'size1': (img1.shape[0], img1.shape[1]),
+        'size2': (img2.shape[0], img2.shape[1]),
+        'same_size': img1.shape == img2.shape,
+        'file_size1': file_size1,
+        'file_size2': file_size2,
+    }
+
+
+def create_comparison_figure(
+    original_path: Union[str, Path],
+    reproduced_path: Union[str, Path],
+    output_path: Union[str, Path],
+    title: str = "Roundtrip Comparison",
+):
+    """Create a side-by-side comparison figure.
+
+    Parameters
+    ----------
+    original_path : str or Path
+        Path to original image.
+    reproduced_path : str or Path
+        Path to reproduced image.
+    output_path : str or Path
+        Path to save comparison figure.
+    title : str
+        Title for the comparison.
+    """
+    import matplotlib.pyplot as plt
+
+    img1 = load_image(original_path)
+    img2 = load_image(reproduced_path)
+
+    try:
+        mse, diff_img = compute_diff(img1, img2)
+    except ValueError:
+        # Different sizes, just show side by side
+        fig, axes = plt.subplots(1, 2, figsize=(12, 5))
+        axes[0].imshow(img1)
+        axes[0].set_title('Original')
+        axes[0].axis('off')
+        axes[1].imshow(img2)
+        axes[1].set_title('Reproduced')
+        axes[1].axis('off')
+        fig.suptitle(f'{title}\n(Different sizes)', fontsize=14)
+        fig.savefig(output_path, dpi=150, bbox_inches='tight', facecolor='white')
+        plt.close(fig)
+        return
+
+    fig, axes = plt.subplots(1, 3, figsize=(15, 5))
+
+    axes[0].imshow(img1)
+    axes[0].set_title('Original')
+    axes[0].axis('off')
+
+    axes[1].imshow(img2)
+    axes[1].set_title('Reproduced')
+    axes[1].axis('off')
+
+    axes[2].imshow(diff_img)
+    axes[2].set_title(f'Difference (MSE: {mse:.2f})')
+    axes[2].axis('off')
+
+    status = "IDENTICAL" if mse == 0 else f"MSE: {mse:.2f}"
+    fig.suptitle(f'{title}\n{status}', fontsize=14, fontweight='bold')
+
+    fig.savefig(output_path, dpi=150, bbox_inches='tight', facecolor='white')
+    plt.close(fig)

figrecipe/_utils/_numpy_io.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""NumPy array I/O utilities for figrecipe."""
+
+import csv
+from pathlib import Path
+from typing import Literal, Union
+
+import numpy as np
+
+
+# Threshold for inline vs file storage (in elements)
+INLINE_THRESHOLD = 100
+
+# Data format type
+DataFormat = Literal["csv", "npz", "inline"]
+
+
+def should_store_inline(data: np.ndarray) -> bool:
+    """Determine if array should be stored inline or as file.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Array to check.
+
+    Returns
+    -------
+    bool
+        True if array is small enough for inline storage.
+    """
+    return data.size <= INLINE_THRESHOLD
+
+
+def save_array(
+    data: np.ndarray,
+    path: Union[str, Path],
+    data_format: DataFormat = "csv",
+) -> Path:
+    """Save numpy array to file.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Array to save.
+    path : str or Path
+        Output file path (extension will be set based on format).
+    data_format : str
+        Format to use: 'csv' (default), 'npz', or 'inline'.
+
+    Returns
+    -------
+    Path
+        Path to saved file.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if data_format == "csv":
+        path = path.with_suffix(".csv")
+        save_array_csv(data, path)
+    elif data_format == "npz":
+        path = path.with_suffix(".npz")
+        np.savez_compressed(path, data=data)
+    else:
+        path = path.with_suffix(".npy")
+        np.save(path, data)
+
+    return path
+
+
+def save_array_csv(data: np.ndarray, path: Union[str, Path]) -> Path:
+    """Save numpy array to CSV file with dtype header.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Array to save.
+    path : str or Path
+        Output CSV file path.
+
+    Returns
+    -------
+    Path
+        Path to saved file.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f)
+        # Write header with dtype info
+        writer.writerow([f"# dtype: {data.dtype}"])
+        # Write data
+        if data.ndim == 1:
+            for val in data:
+                writer.writerow([val])
+        else:
+            for row in data:
+                writer.writerow(row if hasattr(row, "__iter__") else [row])
+
+    return path
+
+
+def load_array_csv(path: Union[str, Path]) -> np.ndarray:
+    """Load numpy array from CSV file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to CSV file.
+
+    Returns
+    -------
+    np.ndarray
+        Loaded array.
+    """
+    path = Path(path)
+    dtype = None
+    data_rows = []
+
+    with open(path, "r", newline="") as f:
+        reader = csv.reader(f)
+        for row in reader:
+            if row and row[0].startswith("# dtype:"):
+                dtype_str = row[0].replace("# dtype:", "").strip()
+                dtype = np.dtype(dtype_str)
+            else:
+                data_rows.append(row)
+
+    # Parse data
+    if not data_rows:
+        return np.array([], dtype=dtype)
+
+    # Check if 1D (single column)
+    if all(len(row) == 1 for row in data_rows):
+        data = [row[0] for row in data_rows]
+    else:
+        data = data_rows
+
+    return np.array(data, dtype=dtype)
+
+
+def load_array(path: Union[str, Path]) -> np.ndarray:
+    """Load numpy array from file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Path to .npy, .npz, or .csv file.
+
+    Returns
+    -------
+    np.ndarray
+        Loaded array.
+    """
+    path = Path(path)
+
+    if path.suffix == ".npz":
+        with np.load(path) as f:
+            return f["data"]
+    elif path.suffix == ".csv":
+        return load_array_csv(path)
+    else:
+        return np.load(path)
+
+
+def to_serializable(data) -> Union[list, dict]:
+    """Convert numpy array to serializable format for inline storage.
+
+    Parameters
+    ----------
+    data : array-like
+        Data to convert.
+
+    Returns
+    -------
+    list or dict
+        Serializable representation.
+    """
+    if hasattr(data, "tolist"):
+        return data.tolist()
+    elif hasattr(data, "values"):  # pandas
+        return data.values.tolist()
+    else:
+        return list(data)
+
+
+def from_serializable(data, dtype=None) -> np.ndarray:
+    """Convert serializable format back to numpy array.
+
+    Parameters
+    ----------
+    data : list
+        Serializable data.
+    dtype : dtype, optional
+        Target dtype.
+
+    Returns
+    -------
+    np.ndarray
+        Numpy array.
+    """
+    return np.array(data, dtype=dtype)

figrecipe/_utils/_units.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Unit conversion utilities for figrecipe.
+
+Provides conversions between millimeters, inches, and points for precise
+figure layout control.
+
+Constants:
+    - 1 inch = 25.4 mm
+    - 1 inch = 72 points (PostScript points)
+    - 1 mm = 72/25.4 points
+"""
+
+__all__ = ["mm_to_inch", "inch_to_mm", "mm_to_pt", "pt_to_mm", "mm_to_scatter_size", "normalize_color"]
+
+from typing import List, Tuple, Union
+
+# Conversion constants
+MM_PER_INCH = 25.4
+PT_PER_INCH = 72.0
+
+
+def mm_to_inch(mm: float) -> float:
+    """Convert millimeters to inches.
+
+    Parameters
+    ----------
+    mm : float
+        Value in millimeters
+
+    Returns
+    -------
+    float
+        Value in inches
+
+    Examples
+    --------
+    >>> mm_to_inch(25.4)
+    1.0
+    >>> mm_to_inch(40)  # Nature figure width
+    1.5748031496062993
+    """
+    return mm / MM_PER_INCH
+
+
+def inch_to_mm(inch: float) -> float:
+    """Convert inches to millimeters.
+
+    Parameters
+    ----------
+    inch : float
+        Value in inches
+
+    Returns
+    -------
+    float
+        Value in millimeters
+
+    Examples
+    --------
+    >>> inch_to_mm(1.0)
+    25.4
+    """
+    return inch * MM_PER_INCH
+
+
+def mm_to_pt(mm: float) -> float:
+    """Convert millimeters to points (PostScript points).
+
+    Parameters
+    ----------
+    mm : float
+        Value in millimeters
+
+    Returns
+    -------
+    float
+        Value in points (1 pt = 1/72 inch)
+
+    Examples
+    --------
+    >>> mm_to_pt(0.2)  # Typical line thickness
+    0.5669291338582677
+    >>> mm_to_pt(0.8)  # Typical tick length
+    2.267716535433071
+    """
+    return mm * PT_PER_INCH / MM_PER_INCH
+
+
+def pt_to_mm(pt: float) -> float:
+    """Convert points to millimeters.
+
+    Parameters
+    ----------
+    pt : float
+        Value in points
+
+    Returns
+    -------
+    float
+        Value in millimeters
+
+    Examples
+    --------
+    >>> pt_to_mm(1.0)
+    0.3527777777777778
+    """
+    return pt * MM_PER_INCH / PT_PER_INCH
+
+
+def mm_to_scatter_size(diameter_mm: float) -> float:
+    """Convert mm diameter to matplotlib scatter 's' parameter.
+
+    matplotlib's scatter() uses 's' as marker AREA in points².
+    This function converts a desired diameter in mm to the correct
+    's' value for circular markers.
+
+    Parameters
+    ----------
+    diameter_mm : float
+        Desired marker diameter in millimeters
+
+    Returns
+    -------
+    float
+        Value for scatter's 's' parameter (area in points²)
+
+    Examples
+    --------
+    >>> import figrecipe as fr
+    >>> # 0.8mm diameter markers (matches tick length)
+    >>> s = fr.mm_to_scatter_size(0.8)
+    >>> ax.scatter(x, y, s=s)
+
+    >>> # Use style's marker size
+    >>> style = fr.load_style()
+    >>> s = fr.mm_to_scatter_size(style.markers.size_mm)
+    >>> ax.scatter(x, y, s=s)
+
+    Notes
+    -----
+    For a circle: area = π * r² = π * (d/2)²
+    where d is diameter in points.
+    """
+    import math
+    diameter_pt = mm_to_pt(diameter_mm)
+    return math.pi * (diameter_pt / 2) ** 2
+
+
+def normalize_color(
+    color: Union[List[int], Tuple[int, ...], str]
+) -> Union[Tuple[float, ...], str]:
+    """Normalize color to matplotlib-compatible format.
+
+    Converts RGB [0-255] values to normalized [0-1] tuples.
+    Hex strings and named colors are passed through unchanged.
+
+    Parameters
+    ----------
+    color : list, tuple, or str
+        Color in various formats:
+        - RGB list/tuple [0-255]: [0, 128, 192] -> (0.0, 0.5, 0.75)
+        - Hex string: "#0080C0" -> "#0080C0"
+        - Named color: "blue" -> "blue"
+
+    Returns
+    -------
+    tuple or str
+        Matplotlib-compatible color specification
+
+    Examples
+    --------
+    >>> normalize_color([0, 128, 192])
+    (0.0, 0.5019607843137255, 0.7529411764705882)
+    >>> normalize_color("#0080C0")
+    '#0080C0'
+    >>> normalize_color("blue")
+    'blue'
+    """
+    if isinstance(color, str):
+        return color
+    if isinstance(color, (list, tuple)):
+        # Check if already normalized (values <= 1)
+        if all(c <= 1.0 for c in color):
+            return tuple(color)
+        # Normalize 0-255 to 0-1
+        return tuple(c / 255.0 for c in color)
+    return color
+
+
+if __name__ == "__main__":
+    # Test conversions
+    print("Unit conversion tests:")
+    print(f"  25.4 mm = {mm_to_inch(25.4):.4f} inch")
+    print(f"  1 inch = {inch_to_mm(1.0):.1f} mm")
+    print(f"  0.2 mm = {mm_to_pt(0.2):.4f} pt")
+    print(f"  1 pt = {pt_to_mm(1.0):.4f} mm")
+    print(f"\nColor normalization:")
+    print(f"  [0, 128, 192] -> {normalize_color([0, 128, 192])}")
+    print(f"  '#0080C0' -> {normalize_color('#0080C0')}")