lammpskit.plotting.timeseries_plots module

Centralized plotting functions for time series analysis. This module provides reusable plotting functions for creating standardized time series and dual-axis plots with consistent styling and configuration management.

Key Functions

The module provides functions for:

  • Time series plot creation with publication-ready defaults

  • Dual-axis plotting for correlating different physical quantities

  • Figure management with save and close functionality

  • Statistical labeling for data summary integration

  • Configuration classes for consistent plot styling

Configuration System

The module uses dataclasses for centralized plot configuration:

TimeSeriesPlotConfig

Controls single-axis time series plots with options for line/scatter combinations, transparency, and typography.

DualAxisPlotConfig

Extends time series configuration for dual-axis plots with independent color schemes and legend positioning.

Default Configuration Values

# Standard time series plot defaults
TimeSeriesPlotConfig(
    alpha=0.55,           # Semi-transparent for overlay visualization
    linewidth=0.1,        # Thin lines for dense time series
    markersize=5,         # Readable markers without overcrowding
    marker='^',           # Triangle markers for distinctiveness
    include_line=True,    # Show trend lines
    include_scatter=True, # Show data points
    format='pdf'          # Vector output for publications
)

Usage Examples

Basic time series plot:

import numpy as np
from lammpskit.plotting import create_time_series_plot, TimeSeriesPlotConfig

# Generate temporal data
time = np.linspace(0, 100, 200)  # Time in picoseconds
connectivity = np.random.rand(200) * 100  # Connectivity percentage

# Create standardized plot
fig, ax = create_time_series_plot(
    x_data=time,
    y_data=connectivity,
    title='Filament Connectivity Evolution',
    xlabel='Time (ps)',
    ylabel='Connectivity (%)',
    stats_label='Mean: 45.2%, Std: 12.1%'
)

Customized time series with configuration:

# Custom configuration for presentation
config = TimeSeriesPlotConfig(
    alpha=0.8,
    linewidth=0.5,
    markersize=8,
    marker='o',
    format='svg'
)

fig, ax = create_time_series_plot(
    x_data=time,
    y_data=temperature,
    title='Temperature Evolution',
    xlabel='Time (ps)',
    ylabel='Temperature (K)',
    stats_label='Mean: 315.4K, Std: 25.8K',
    config=config,
    ylim=(280, 350)  # Custom axis limits
)

Dual-axis comparative analysis:

from lammpskit.plotting import create_dual_axis_plot, DualAxisPlotConfig

# Configure dual-axis plot
config = DualAxisPlotConfig(
    primary_color='tab:red',
    secondary_color='tab:blue',
    primary_legend_loc='upper right',
    secondary_legend_loc='lower right'
)

# Create dual-axis plot for correlation analysis
fig, ax1, ax2 = create_dual_axis_plot(
    x_data=time,
    primary_y_data=connectivity,
    secondary_y_data=temperature,
    title='Connectivity vs Temperature Evolution',
    xlabel='Time (ps)',
    primary_ylabel='Connectivity (%)',
    secondary_ylabel='Temperature (K)',
    primary_stats_label='Connectivity: 45.2±12.1%',
    secondary_stats_label='Temperature: 315.4±25.8K',
    config=config
)

Statistical label generation:

from lammpskit.plotting import calculate_mean_std_label, calculate_frequency_label

# Automatic statistical labeling
data = np.random.normal(50, 10, 1000)
stats_label = calculate_mean_std_label(data, 'Connectivity', precision=1)
print(stats_label)  # "Connectivity: Mean=50.1%, Std=9.8%"

# Frequency analysis labeling
binary_data = np.random.choice([0, 1], 1000, p=[0.3, 0.7])
freq_label = calculate_frequency_label(
    binary_data, 1, 'Connected: {frequency:.1f}%', precision=1)
print(freq_label)  # "Connected: 70.2%"

Font Control Examples

Individual font size control:

fig, ax = create_time_series_plot(
    x_data=time, y_data=data,
    title='Custom Typography',
    xlabel='Time', ylabel='Value',
    stats_label='Statistics',
    fontsize_title=12,    # Larger title
    fontsize_labels=10,   # Medium labels
    fontsize_ticks=8,     # Small tick labels
    fontsize_legend=9     # Medium legend
)

Configuration-based font control:

config = TimeSeriesPlotConfig(
    fontsize_title=14,
    fontsize_labels=12,
    fontsize_ticks=10,
    fontsize_legend=11
)

Performance Considerations

Rendering Performance:

  • Transparent plots (alpha < 1.0) may slow rendering for large datasets

  • Vector formats maintain quality but increase file size

  • Line+scatter combination doubles rendering operations

Memory Management:

  • Use save_and_close_figure() for automatic memory cleanup

  • Figure objects are returned for additional customization before saving

  • Large time series (>10⁴ points) benefit from reduced marker density

Optimization Strategies:

  • Set include_line=False for pure scatter analysis

  • Set include_scatter=False for smooth trend visualization

  • Use alpha=1.0 for faster rendering of simple plots

Common Applications

Filament Evolution Analysis:

  • Connectivity state over time

  • Gap distance evolution

  • Cluster size distribution temporal changes

Electrochemical Device Analysis:

  • Current vs. voltage temporal relationships

  • Temperature vs. resistance correlations

  • Ion mobility temporal patterns

General MD Analysis:

  • Property evolution during equilibration

  • Temperature/pressure control validation

  • Energy conservation monitoring

Module Documentation

Centralized plotting functions for time series analysis.

This module provides reusable plotting functions for creating standardized time series and dual-axis plots with consistent styling and configuration. These functions are general-purpose and can be used for any time series data, not just filament analysis.

class lammpskit.plotting.timeseries_plots.TimeSeriesPlotConfig(alpha=0.55, linewidth=0.1, markersize=5, marker='^', include_line=True, include_scatter=True, format='pdf', fontsize_title=8, fontsize_labels=8, fontsize_ticks=8, fontsize_legend=8)[source]

Bases: object

Configuration class for standardized time series plotting with publication-ready defaults.

Provides centralized control over plot styling, elements, and output formatting for consistent scientific visualization across LAMMPSKit analysis workflows. Supports both line plots and scatter plots with flexible element combination.

alpha

Transparency level for plot elements. Range [0.0, 1.0] where 0.0 is fully transparent and 1.0 is fully opaque. Balanced for overlay visualization.

Type:

float, default=0.55

linewidth

Line thickness for connected plots. Thin lines prevent visual clutter in dense time series data. Use higher values (0.5-2.0) for presentation plots.

Type:

float, default=0.1

markersize

Size of scatter plot markers. Optimized for readability without overcrowding. Scale proportionally for different figure sizes.

Type:

float, default=5

marker

Matplotlib marker style for scatter plots. Options: ‘o’ (circle), ‘s’ (square), ‘^’ (triangle), ‘*’ (star), ‘+’ (plus), ‘x’ (cross), ‘D’ (diamond).

Type:

str, default=’^’

include_line

Whether to draw connecting lines between data points. Useful for trend visualization in temporal data. Disable for pure scatter analysis.

Type:

bool, default=True

include_scatter

Whether to draw individual data point markers. Essential for discrete data visualization. Disable for smooth trend-only plots.

Type:

bool, default=True

format

Output file format for saved figures. Options: ‘pdf’ (vector, publication), ‘svg’ (web-compatible vector), ‘png’ (raster), ‘eps’ (LaTeX-compatible).

Type:

str, default=’pdf’

fontsize_title

Font size for plot titles in points. Optimized for compact scientific layout. Use None to disable title font control.

Type:

int, default=8

fontsize_labels

Font size for axis labels in points. Consistent with scientific journal standards. Use None to use matplotlib defaults.

Type:

int, default=8

fontsize_ticks

Font size for axis tick labels in points. Maintains readability at small sizes. Use None to use matplotlib defaults.

Type:

int, default=8

fontsize_legend

Font size for legend text in points. Balanced for information density. Use None to use matplotlib defaults.

Type:

int, default=8

Notes

Configuration Design Philosophy: - Publication-ready defaults minimize post-processing - Centralized font control ensures consistency across figures - Flexible element control (line/scatter) supports diverse data types - Conservative styling prevents visual clutter in complex analyses

Performance Considerations: - Transparent plots (alpha < 1.0) may slow rendering for large datasets - Vector formats (PDF/SVG) maintain quality but increase file size - Font rendering overhead is minimal for typical scientific plots

Examples

Default configuration for temporal analysis:

>>> config = TimeSeriesPlotConfig()
>>> print(f"Using marker: {config.marker}, alpha: {config.alpha}")

Custom configuration for presentation plots:

>>> config = TimeSeriesPlotConfig(
...     linewidth=1.0,
...     markersize=8,
...     alpha=0.8,
...     fontsize_title=12,
...     fontsize_labels=10
... )

Scatter-only configuration for statistical analysis:

>>> config = TimeSeriesPlotConfig(
...     include_line=False,
...     include_scatter=True,
...     marker='o',
...     markersize=3
... )

High-contrast configuration for printing:

>>> config = TimeSeriesPlotConfig(
...     alpha=1.0,
...     linewidth=0.8,
...     format='eps'
... )
Parameters:
alpha: float = 0.55
linewidth: float = 0.1
markersize: float = 5
marker: str = '^'
include_line: bool = True
include_scatter: bool = True
format: str = 'pdf'
fontsize_title: Optional[int] = 8
fontsize_labels: Optional[int] = 8
fontsize_ticks: Optional[int] = 8
fontsize_legend: Optional[int] = 8
__init__(alpha=0.55, linewidth=0.1, markersize=5, marker='^', include_line=True, include_scatter=True, format='pdf', fontsize_title=8, fontsize_labels=8, fontsize_ticks=8, fontsize_legend=8)
Parameters:
class lammpskit.plotting.timeseries_plots.DualAxisPlotConfig(alpha=0.55, linewidth=0.1, markersize=5, marker='^', primary_color='tab:red', secondary_color='tab:blue', format='pdf', primary_legend_loc='upper right', secondary_legend_loc='lower right', legend_framealpha=0.75, tight_layout=True, fontsize_title=8, fontsize_labels=8, fontsize_ticks=8, fontsize_legend=8)[source]

Bases: object

Configuration class for dual-axis plots supporting simultaneous visualization of two data series.

Enables comparison of time series data with different units or scales on a single figure. Essential for correlating physical quantities like temperature-displacement or connectivity-time relationships in scientific analysis. Provides independent color control and legend positioning for clear data interpretation.

alpha

Transparency level for both data series. Range [0.0, 1.0]. Moderate transparency allows underlying grid and axis lines to remain visible.

Type:

float, default=0.55

linewidth

Line thickness for both axes data. Thin lines prevent visual dominance of either dataset. Increase for presentation or when clarity is critical.

Type:

float, default=0.1

markersize

Marker size for scatter points on both axes. Consistent sizing maintains visual balance between primary and secondary data series.

Type:

float, default=5

marker

Marker style for secondary axis (right). Primary axis uses default scatter markers. Options: ‘o’, ‘s’, ‘^’, ‘*’, ‘+’, ‘x’, ‘D’, ‘v’, ‘<’, ‘>’.

Type:

str, default=’^’

primary_color

Color for primary (left) y-axis data and axis labels. Matplotlib tab colors provide good contrast. Options: ‘tab:blue’, ‘tab:orange’, ‘tab:green’, etc.

Type:

str, default=’tab:red’

secondary_color

Color for secondary (right) y-axis data and axis labels. Should contrast with primary_color for clear visual separation.

Type:

str, default=’tab:blue’

format

Output file format. Dual-axis plots benefit from vector formats to maintain text and line clarity at different scales.

Type:

str, default=’pdf’

primary_legend_loc

Legend position for primary axis data. Standard matplotlib locations: ‘upper/lower/center’ + ‘left/right/center’, or ‘best’ for automatic.

Type:

str, default=’upper right’

secondary_legend_loc

Legend position for secondary axis data. Should not overlap with primary legend. Consider ‘upper left’, ‘lower left’, or ‘center left’.

Type:

str, default=’lower right’

legend_framealpha

Background transparency for legend boxes. Range [0.0, 1.0]. Semi-transparent frames prevent complete data occlusion while maintaining readability.

Type:

float, default=0.75

tight_layout

Whether to apply matplotlib tight_layout for automatic spacing adjustment. Prevents axis label cutoff in dual-axis configurations.

Type:

bool, default=True

fontsize_title

Font size for plot title. Centered above both axes.

Type:

int, default=8

fontsize_labels

Font size for both primary and secondary axis labels.

Type:

int, default=8

fontsize_ticks

Font size for tick labels on both axes.

Type:

int, default=8

fontsize_legend

Font size for both legend boxes.

Type:

int, default=8

Notes

Dual-Axis Design Principles: - Color coding clearly distinguishes data series and corresponding axes - Legend positioning prevents data occlusion while maintaining clarity - Consistent marker sizing maintains visual balance between series - Semi-transparent legends allow underlying data visibility

Common Use Cases: - Temperature vs. displacement over time - Connectivity percentage vs. cluster size evolution - Voltage vs. current relationships in device characterization - Statistical metrics vs. physical properties correlation

Performance Considerations: - Dual-axis rendering requires additional matplotlib operations - Legend placement calculations may slow complex figures - Vector output formats recommended for text clarity

Examples

Default configuration for scientific analysis:

>>> config = DualAxisPlotConfig()
>>> print(f"Colors: {config.primary_color}, {config.secondary_color}")

Custom color scheme for publication:

>>> config = DualAxisPlotConfig(
...     primary_color='tab:green',
...     secondary_color='tab:purple',
...     primary_legend_loc='upper left',
...     secondary_legend_loc='upper right'
... )

High-contrast configuration for presentations:

>>> config = DualAxisPlotConfig(
...     alpha=0.9,
...     linewidth=0.5,
...     markersize=8,
...     legend_framealpha=0.9,
...     fontsize_title=12,
...     fontsize_labels=10
... )

Minimal styling for technical reports:

>>> config = DualAxisPlotConfig(
...     primary_color='black',
...     secondary_color='gray',
...     tight_layout=True,
...     format='eps'
... )
Parameters:
alpha: float = 0.55
linewidth: float = 0.1
markersize: float = 5
marker: str = '^'
primary_color: str = 'tab:red'
secondary_color: str = 'tab:blue'
format: str = 'pdf'
primary_legend_loc: str = 'upper right'
secondary_legend_loc: str = 'lower right'
legend_framealpha: float = 0.75
tight_layout: bool = True
fontsize_title: Optional[int] = 8
fontsize_labels: Optional[int] = 8
fontsize_ticks: Optional[int] = 8
fontsize_legend: Optional[int] = 8
__init__(alpha=0.55, linewidth=0.1, markersize=5, marker='^', primary_color='tab:red', secondary_color='tab:blue', format='pdf', primary_legend_loc='upper right', secondary_legend_loc='lower right', legend_framealpha=0.75, tight_layout=True, fontsize_title=8, fontsize_labels=8, fontsize_ticks=8, fontsize_legend=8)
Parameters:
lammpskit.plotting.timeseries_plots.create_time_series_plot(x_data, y_data, title, xlabel, ylabel, stats_label, config=None, ylim=None, fontsize_title=None, fontsize_labels=None, fontsize_ticks=None, fontsize_legend=None)[source]

Create standardized time series plots with flexible line and scatter element control.

Generates publication-ready time series visualizations with configurable styling and centralized font management. Supports pure line plots, pure scatter plots, or combined visualizations based on configuration. Essential for temporal analysis workflows including filament evolution tracking, statistical time series, and experimental data visualization.

Parameters:

  • x_data (np.ndarray) – X-axis values, typically representing time or sequential measurements. Shape: (n_points,). Units depend on analysis context (e.g., timesteps, seconds, frames).

  • y_data (np.ndarray) – Y-axis values for plotting. Shape: (n_points,). Must match x_data length. Examples: displacement values, connectivity percentages, statistical measures.

  • title (str) – Plot title displayed above the figure. Include units and context for clarity. Example: ‘Filament Evolution Over Time’, ‘Temperature vs. Timestep’

  • xlabel (str) – X-axis label with units. Standard format: ‘Property (units)’. Examples: ‘Time (ps)’, ‘Timestep’, ‘Frame Number’, ‘Voltage Cycle’

  • ylabel (str) – Y-axis label with units. Standard format: ‘Property (units)’. Examples: ‘Displacement (Å)’, ‘Connectivity (%)’, ‘Temperature (K)’

  • stats_label (str) – Statistical summary or description for legend entry. Often includes computed metrics like mean, standard deviation, or frequency. Example: ‘Mean: 2.34 ± 0.15’

  • config (TimeSeriesPlotConfig, optional) – Plot configuration object controlling styling, elements, and output format. If None, uses default configuration optimized for scientific visualization.

  • ylim (tuple of float, optional) – Y-axis limits as (ymin, ymax). Useful for consistent scaling across multiple related plots or for focusing on specific data ranges.

  • fontsize_title (int, optional) – Override configuration title font size. Useful for presentation adaptation without modifying the base configuration object.

  • fontsize_labels (int, optional) – Override configuration axis label font size. Maintains consistency while allowing figure-specific adjustments.

  • fontsize_ticks (int, optional) – Override configuration tick label font size. Important for readability when figures are scaled for different contexts.

  • fontsize_legend (int, optional) – Override configuration legend font size. Critical for maintaining legend readability in complex multi-series plots.

Return type:

Tuple[Figure, Axes]

Returns:

  • fig (plt.Figure) – Matplotlib figure object containing the plot. Can be further customized, saved, or displayed using standard matplotlib operations.

  • ax (plt.Axes) – Matplotlib axes object for the plot. Provides access for additional annotations, reference lines, or styling modifications.

Raises:

  • ValueError – If x_data and y_data have mismatched lengths or contain invalid values.

  • TypeError – If data arrays are not numpy arrays or convertible to arrays.

Notes

Plot Element Control: - include_line=True, include_scatter=True: Connected scatter plot (default) - include_line=True, include_scatter=False: Pure line plot for trends - include_line=False, include_scatter=True: Pure scatter plot for discrete data - include_line=False, include_scatter=False: Empty plot (not recommended)

Performance Characteristics: - Memory usage: O(n_points) for data storage, minimal for plot objects - Rendering time: O(n_points) for line plots, O(n_points) for scatter plots - File size: Vector formats scale with data complexity, raster formats are fixed

Statistical Integration: - Use calculate_mean_std_label() for automated statistical summaries - Use calculate_frequency_label() for discrete event analysis - Legend automatically includes stats_label for quantitative context

Examples

Basic time series plot with default configuration:

>>> import numpy as np
>>> from lammpskit.plotting.timeseries_plots import create_time_series_plot
>>> time = np.arange(0, 100, 1)
>>> displacement = np.random.normal(2.0, 0.5, 100)
>>> fig, ax = create_time_series_plot(
...     time, displacement,
...     'Atomic Displacement Evolution',
...     'Time (ps)', 'Displacement (Å)',
...     'Mean: 2.0 ± 0.5 Å'
... )

Custom configuration for presentation:

>>> from lammpskit.plotting.timeseries_plots import TimeSeriesPlotConfig
>>> config = TimeSeriesPlotConfig(
...     linewidth=1.0, markersize=8, alpha=0.8, format='png'
... )
>>> fig, ax = create_time_series_plot(
...     time, displacement,
...     'High-Visibility Displacement Plot',
...     'Time (ps)', 'Displacement (Å)',
...     'N=100 points', config=config
... )

Scatter-only plot for statistical analysis:

>>> config = TimeSeriesPlotConfig(include_line=False, marker='o')
>>> fig, ax = create_time_series_plot(
...     time, displacement,
...     'Discrete Displacement Measurements',
...     'Time (ps)', 'Displacement (Å)',
...     'σ = 0.5 Å', config=config
... )

Controlled y-axis range for comparison plots:

>>> fig, ax = create_time_series_plot(
...     time, displacement,
...     'Constrained Range Analysis',
...     'Time (ps)', 'Displacement (Å)',
...     'Range: 0-5 Å', ylim=(0, 5)
... )

Font size override for manuscript figures:

>>> fig, ax = create_time_series_plot(
...     time, displacement,
...     'Publication Figure',
...     'Time (ps)', 'Displacement (Å)',
...     'Experimental data',
...     fontsize_title=14, fontsize_labels=12, fontsize_legend=10
... )
lammpskit.plotting.timeseries_plots.create_dual_axis_plot(x_data, primary_y_data, secondary_y_data, title, xlabel, primary_ylabel, secondary_ylabel, primary_stats_label, secondary_stats_label, config=None, primary_ylim=None, secondary_ylim=None, fontsize_title=None, fontsize_labels=None, fontsize_ticks=None, fontsize_legend=None)[source]

Create dual-axis plots for simultaneous visualization of two correlated data series.

Generates publication-ready figures with independent y-axes supporting different units, scales, or physical quantities. Essential for comparative analysis of time-dependent properties where direct correlation visualization is critical. Features automatic color coordination, independent axis control, and optimized legend positioning.

Parameters:

  • x_data (np.ndarray) – Shared x-axis values for both data series. Shape: (n_points,). Typically represents time, voltage cycles, or sequential measurements.

  • primary_y_data (np.ndarray) – Left y-axis data series. Shape: (n_points,). Must match x_data length. Examples: displacement values, temperature measurements, primary properties.

  • secondary_y_data (np.ndarray) – Right y-axis data series. Shape: (n_points,). Must match x_data length. Examples: connectivity percentages, statistical measures, derived properties.

  • title (str) – Plot title displayed above both axes. Should indicate the relationship being explored. Example: ‘Temperature vs Connectivity Evolution’

  • xlabel (str) – Shared x-axis label with units. Standard format: ‘Property (units)’. Examples: ‘Time (ps)’, ‘Voltage Cycle’, ‘Timestep Number’

  • primary_ylabel (str) – Left y-axis label with units. Standard format: ‘Property (units)’. Color-coded to match primary_color in configuration.

  • secondary_ylabel (str) – Right y-axis label with units. Standard format: ‘Property (units)’. Color-coded to match secondary_color in configuration.

  • primary_stats_label (str) – Statistical summary for primary data legend entry. Often includes mean, standard deviation, or characteristic values. Example: ‘Temp: 300 ± 50 K’

  • secondary_stats_label (str) – Statistical summary for secondary data legend entry. Should complement primary statistics. Example: ‘Connected: 23.4% of time’

  • config (DualAxisPlotConfig, optional) – Dual-axis configuration controlling colors, legend positioning, and styling. If None, uses default configuration optimized for scientific visualization.

  • primary_ylim (tuple of float, optional) – Primary (left) y-axis limits as (ymin, ymax). Useful for consistent scaling across multiple related plots or for highlighting specific data ranges.

  • secondary_ylim (tuple of float, optional) – Secondary (right) y-axis limits as (ymin, ymax). Independent control enables optimal visualization of secondary data regardless of primary axis scaling.

  • fontsize_title (int, optional) – Override configuration title font size. Useful for presentation adaptation without modifying the base configuration object.

  • fontsize_labels (int, optional) – Override configuration axis label font size. Applies to both primary and secondary axis labels simultaneously.

  • fontsize_ticks (int, optional) – Override configuration tick label font size. Affects both axes tick labels for consistent appearance.

  • fontsize_legend (int, optional) – Override configuration legend font size. Applies to both legend boxes.

Return type:

Tuple[Figure, Axes, Axes]

Returns:

  • fig (plt.Figure) – Matplotlib figure object containing the dual-axis plot. Can be further customized, saved, or displayed using standard matplotlib operations.

  • ax1 (plt.Axes) – Primary (left) y-axis axes object. Provides access for additional annotations, reference lines, or primary data modifications.

  • ax2 (plt.Axes) – Secondary (right) y-axis axes object. Enables independent secondary axis customization, additional data series, or specialized annotations.

Raises:

  • ValueError – If data arrays have mismatched lengths or contain invalid values.

  • TypeError – If data arrays are not numpy arrays or convertible to arrays.

Notes

Dual-Axis Design Principles: - Color coordination ensures clear association between data and corresponding axes - Independent axis scaling optimizes visualization of disparate data ranges - Legend positioning minimizes data occlusion while maintaining readability - Automatic tight layout prevents axis label cutoff in complex configurations

Visual Hierarchy: - Primary data (left axis) uses warm colors (red) for visual prominence - Secondary data (right axis) uses cool colors (blue) for complementary contrast - Legend transparency allows underlying data visibility - Consistent marker sizing maintains visual balance

Performance Considerations: - Dual-axis rendering requires additional matplotlib twinx() operations - Legend placement calculations may impact rendering time for complex data - Vector output formats recommended for maintaining text and line clarity - Memory usage: O(n_points) for data, minimal overhead for dual axes

Common Applications: - Process parameter correlation (temperature vs. pressure over time) - Statistical trend analysis (mean vs. variance evolution) - Performance monitoring (throughput vs. error rate) - Multi-scale temporal analysis (short-term vs. long-term trends)

Examples

Basic dual-axis plot with default configuration:

>>> import numpy as np
>>> from lammpskit.plotting.timeseries_plots import create_dual_axis_plot
>>> time = np.arange(0, 100, 1)
>>> temperature = 300 + 50 * np.sin(time * 0.1)
>>> connectivity = 50 + 30 * np.cos(time * 0.05)
>>> fig, ax1, ax2 = create_dual_axis_plot(
...     time, temperature, connectivity,
...     'Temperature-Connectivity Correlation',
...     'Time (ps)', 'Temperature (K)', 'Connectivity (%)',
...     'T = 300 ± 50 K', 'C = 50 ± 30%'
... )

Custom configuration for presentation:

>>> from lammpskit.plotting.timeseries_plots import DualAxisPlotConfig
>>> config = DualAxisPlotConfig(
...     primary_color='tab:green',
...     secondary_color='tab:purple',
...     primary_legend_loc='upper left',
...     secondary_legend_loc='lower right',
...     alpha=0.8
... )
>>> fig, ax1, ax2 = create_dual_axis_plot(
...     time, temperature, connectivity,
...     'Custom Color Analysis',
...     'Time (ps)', 'Property A', 'Property B',
...     'Series A', 'Series B', config=config
... )

Controlled axis ranges for comparison:

>>> fig, ax1, ax2 = create_dual_axis_plot(
...     time, temperature, connectivity,
...     'Fixed Range Comparison',
...     'Time (ps)', 'Temperature (K)', 'Connectivity (%)',
...     'Controlled range', 'Fixed scale',
...     primary_ylim=(250, 350), secondary_ylim=(0, 100)
... )

High-contrast configuration for printing:

>>> config = DualAxisPlotConfig(
...     primary_color='black',
...     secondary_color='gray',
...     alpha=1.0,
...     legend_framealpha=1.0,
...     format='eps'
... )
>>> fig, ax1, ax2 = create_dual_axis_plot(
...     time, temperature, connectivity,
...     'Print-Optimized Dual Plot',
...     'Time (ps)', 'Primary', 'Secondary',
...     'Data A', 'Data B', config=config
... )

Font override for manuscript figures:

>>> fig, ax1, ax2 = create_dual_axis_plot(
...     time, temperature, connectivity,
...     'Publication Figure',
...     'Time (ps)', 'Temperature (K)', 'Connectivity (%)',
...     'Experimental', 'Calculated',
...     fontsize_title=16, fontsize_labels=14, fontsize_legend=12
... )
lammpskit.plotting.timeseries_plots.save_and_close_figure(fig, output_dir, filename, file_format='pdf')[source]

Save matplotlib figure to disk with automatic directory creation and memory cleanup.

Provides standardized figure output handling for scientific visualization workflows. Automatically creates output directories, handles filename formatting, and closes figures to prevent memory accumulation during batch processing. Essential for automated analysis pipelines generating multiple plots.

Parameters:

  • fig (plt.Figure) – Matplotlib figure object to save. Can be any figure created with plt.figure(), plt.subplots(), or plotting functions returning figure objects.

  • output_dir (str) – Target directory for saved figure. Created automatically if it doesn’t exist. Supports both absolute and relative paths. Use ‘.’ for current directory.

  • filename (str) – Base filename without extension. Extension is added automatically based on file_format parameter. Should be descriptive of plot content for organization.

  • file_format (str, optional, default='pdf') – Output file format determining quality and compatibility: - ‘pdf’: Vector format, publication-ready, scalable - ‘svg’: Web-compatible vector format, editable - ‘png’: Raster format, good for web display - ‘eps’: LaTeX-compatible vector format - ‘jpg’/’jpeg’: Compressed raster, smaller files

Raises:

  • OSError – If output directory cannot be created due to permissions or disk space.

  • ValueError – If file_format is not supported by matplotlib backend.

Return type:

None

Notes

Memory Management: - Automatically closes figure after saving to prevent memory leaks - Critical for batch processing workflows generating many plots - Use plt.show() before calling this function if display is also needed

Directory Handling: - Creates nested directory structures automatically - Preserves existing directories and files - No error if output_dir already exists

Performance Considerations: - Vector formats (PDF, SVG, EPS) maintain quality but may be larger - Raster formats (PNG, JPG) have fixed resolution but smaller files - PDF recommended for scientific publications and presentations - PNG recommended for web display and documentation

Examples

Save figure with automatic directory creation:

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> fig, ax = plt.subplots()
>>> x = np.linspace(0, 10, 100)
>>> ax.plot(x, np.sin(x))
>>> save_and_close_figure(fig, 'output/plots', 'sine_wave')
# Saves as 'output/plots/sine_wave.pdf'

Save in different formats for various uses:

>>> save_and_close_figure(fig, 'manuscript/figures', 'analysis', 'eps')
>>> save_and_close_figure(fig, 'web/images', 'analysis', 'png')
>>> save_and_close_figure(fig, 'presentations', 'analysis', 'svg')

Organized output structure:

>>> base_dir = 'results/experiment_2024'
>>> save_and_close_figure(fig, f'{base_dir}/temperature', 'temp_vs_time')
>>> save_and_close_figure(fig, f'{base_dir}/displacement', 'disp_evolution')

Current directory output:

>>> save_and_close_figure(fig, '.', 'quick_analysis', 'png')
# Saves as './quick_analysis.png'

Batch processing workflow:

>>> figures = [fig1, fig2, fig3]
>>> names = ['temperature', 'pressure', 'density']
>>> for fig, name in zip(figures, names):
...     save_and_close_figure(fig, 'output/timeseries', name)
lammpskit.plotting.timeseries_plots.calculate_mean_std_label(data, label_prefix, precision=2)[source]

Generate standardized statistical summary labels for plot legends and annotations.

Computes mean and standard deviation of input data and formats as publication-ready label string. Essential for automated legend generation in scientific plots where quantitative summaries enhance data interpretation. Supports flexible precision control for different measurement scales and reporting requirements.

Parameters:

  • data (np.ndarray) – Input data array for statistical calculation. Shape: (n_points,). Supports any numeric data type. NaN values are handled by numpy functions.

  • label_prefix (str) – Descriptive text preceding the statistical values. Should include property name and units for clarity. Example: ‘Temperature (K)’, ‘Displacement (Å)’

  • precision (int, optional, default=2) – Number of decimal places for formatting statistical values. Range: 0-15. Use 0-1 for large values, 2-4 for typical scientific measurements, 5+ for high-precision requirements.

Returns:

Formatted label string in standard “prefix = mean ± std” format. Uses Unicode ± symbol for professional appearance. Compatible with matplotlib legend and annotation functions.

Return type:

str

Raises:

  • ValueError – If precision is negative or data array is empty.

  • TypeError – If data is not array-like or label_prefix is not string.

Notes

Statistical Calculations: - Mean: Arithmetic average computed with np.mean() - Standard deviation: Sample standard deviation with np.std() (N-1 denominator) - NaN handling: Follows numpy conventions (NaN propagation)

Formatting Standards: - Uses Unicode ± (U+00B1) for professional appearance - Precision applies to both mean and standard deviation - No scientific notation; adjust precision for extreme values

Performance Characteristics: - Computational complexity: O(n) for statistical calculations - Memory usage: O(1) additional memory beyond input array - String formatting: Minimal overhead for typical legend use

Applications: - Time series analysis summary statistics - Experimental data characterization - Model validation metrics - Comparative analysis legend entries

Examples

Basic temperature data summarization:

>>> import numpy as np
>>> temperatures = np.array([298.2, 301.5, 299.8, 300.1, 302.3])
>>> label = calculate_mean_std_label(temperatures, 'Temperature (K)')
>>> print(label)
'Temperature (K) = 300.38 ± 1.52'

Displacement analysis with high precision:

>>> displacements = np.random.normal(2.345, 0.123, 1000)
>>> label = calculate_mean_std_label(displacements, 'Displacement (Å)', precision=4)
>>> print(label)
'Displacement (Å) = 2.3451 ± 0.1234'

Large-scale data with low precision:

>>> particle_counts = np.random.poisson(1e6, 100)
>>> label = calculate_mean_std_label(particle_counts, 'Count', precision=0)
>>> print(label)
'Count = 1000023 ± 1000'

Percentage data with appropriate precision:

>>> percentages = np.array([23.45, 24.12, 22.89, 23.78, 24.56])
>>> label = calculate_mean_std_label(percentages, 'Connectivity (%)', precision=1)
>>> print(label)
'Connectivity (%) = 23.8 ± 0.6'

Integration with plotting workflows:

>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> ax.plot(range(len(temperatures)), temperatures, label=label)
>>> ax.legend()  # Automatically uses formatted statistical label
lammpskit.plotting.timeseries_plots.calculate_frequency_label(data, target_value, label_template, precision=2)[source]

Calculate occurrence frequency of specific values and generate formatted labels.

Computes percentage frequency of target value occurrence in data arrays and formats using customizable template strings. Essential for binary state analysis, event detection summaries, and categorical data visualization. Supports flexible label formatting for diverse scientific reporting contexts.

Parameters:

  • data (np.ndarray) – Input data array for frequency analysis. Shape: (n_points,). Supports any data type that supports equality comparison (int, float, bool, str).

  • target_value (any) – Specific value to count occurrences of. Must be comparable to data elements using == operator. Examples: 1, 0, True, ‘connected’, specific float values.

  • label_template (str) – Format string template with {frequency} placeholder for percentage insertion. Supports all Python string formatting options. Example: ‘Active {frequency:.1f}% of time’

  • precision (int, optional, default=2) – Decimal places for frequency percentage formatting. Range: 0-10. Note: This parameter is currently unused; precision controlled by template format specifiers.

Returns:

Formatted label string with frequency percentage substituted into template. Percentage calculated as (occurrences / total_points) * 100.

Return type:

str

Raises:

  • ValueError – If data array is empty or label_template missing {frequency} placeholder.

  • TypeError – If target_value type incompatible with data elements for comparison.

  • KeyError – If label_template contains invalid format specifications.

Notes

Frequency Calculation: - Uses element-wise equality (==) for counting matches - Percentage = (matches / total_elements) * 100 - Range: 0.0% (no matches) to 100.0% (all matches) - Floating-point precision handled by template format specifiers

Template Formatting: - Supports all Python str.format() capabilities - Use {frequency:.1f} for 1 decimal place, {frequency:.0f} for integers - Can include additional text, units, and formatting - Multiple {frequency} references allowed in single template

Performance Characteristics: - Computational complexity: O(n) for equality comparison - Memory usage: O(1) additional memory beyond input array - Boolean array creation for comparison may temporarily double memory

Common Applications: - Binary state analysis (connected/disconnected, active/inactive) - Event detection (threshold crossings, state changes) - Categorical data summaries (phase classification, state distribution) - Time-based occurrence rates (duty cycles, sampling frequencies)

Examples

Binary connectivity analysis:

>>> import numpy as np
>>> connectivity = np.array([1, 1, 0, 1, 0, 1, 1, 0, 1, 1])
>>> label = calculate_frequency_label(connectivity, 1, "Connected {frequency:.1f}% of time")
>>> print(label)
'Connected 70.0% of time'

Boolean state analysis:

>>> active_states = np.array([True, False, True, True, False])
>>> label = calculate_frequency_label(active_states, True, "Active: {frequency:.0f}%")
>>> print(label)
'Active: 60%'

Threshold crossing analysis:

>>> temperatures = np.array([298, 305, 310, 295, 307, 312, 290])
>>> over_threshold = temperatures > 300
>>> label = calculate_frequency_label(over_threshold, True, "Above 300K: {frequency:.1f}%")
>>> print(label)
'Above 300K: 57.1%'

Categorical state distribution:

>>> phases = np.array(['A', 'B', 'A', 'A', 'C', 'B', 'A'])
>>> label_A = calculate_frequency_label(phases, 'A', "Phase A: {frequency:.1f}%")
>>> label_B = calculate_frequency_label(phases, 'B', "Phase B: {frequency:.1f}%")
>>> print(label_A, '|', label_B)
'Phase A: 57.1%' | 'Phase B: 28.6%'

Multiple format references:

>>> successes = np.array([1, 0, 1, 1, 0])
>>> label = calculate_frequency_label(
...     successes, 1,
...     "Success rate: {frequency:.1f}% ({frequency:.2f}% precise)"
... )
>>> print(label)
'Success rate: 60.0% (60.00% precise)'

Integration with time series plotting:

>>> connectivity_data = np.random.choice([0, 1], 1000, p=[0.3, 0.7])
>>> stats_label = calculate_frequency_label(
...     connectivity_data, 1, "Connected {frequency:.1f}% of simulation"
... )
>>> # Use stats_label in create_time_series_plot() for automatic legend generation