User Guide#
Getting Started#
mdaviz is a Python Qt6 application for visualizing MDA (Measurement Data Acquisition) data with advanced curve fitting capabilities.
Installation#
For installation instructions, see install.
Running the Application#
After installation, you can run mdaviz in several ways:
From PyPI installation: .. code-block:: bash
conda activate mdaviz mdaviz
From source installation: .. code-block:: bash
git clone BCDA-APS/mdaviz.git cd mdaviz pip install -e .[dev] python -m mdaviz.app
With debug logging: .. code-block:: bash
python -m mdaviz.app –log debug
Basic Usage#
Opening Data#
Auto-Load: The application automatically loads the first valid folder from your recent folders list
Manual Open: Use the folder dropdown to select a different folder or click “Open…” to browse
Recent Folders: The dropdown shows your recently opened folders for quick access
Data Visualization#
Plot Mode: Choose between Auto-replace, Auto-add, or Auto-off modes
Data Selection: Use the checkbox columns to control what’s plotted: - X: Select the independent variable (only one allowed) - Y: Select dependent variables to plot (multiple allowed) - I0: Select for normalization (divide Y data by this field, only one allowed) - Un: Unscale curves to match the range of other Y curves (requires Y selection on same row)
Interactive Plot: Use matplotlib’s interactive features for zooming, panning, and data exploration
Data Processing Options: - I0 Normalization: Divide Y data by the selected I0 field to normalize intensity - Curve Unscaling: Rescale selected curves to match the range of other Y curves - Combined Processing: Apply both I0 normalization and unscaling for complex data analysis
Curve Fitting#
mdaviz provides advanced curve fitting capabilities with 7 mathematical models:
Select Curve: Choose the curve to fit from the dropdown
Choose Model: Select from Gaussian, Lorentzian, Linear, Exponential, Quadratic, Cubic, or Error Function
Set Range (optional): Use cursors to define a specific x-range for fitting
Perform Fit: Click “Fit” to analyze the data
View Results: Examine fit parameters, uncertainties, and quality metrics
Available Models: - Gaussian: Peak analysis, spectroscopy data - Lorentzian: Resonance peaks, spectral lines - Linear: Trend analysis, calibration curves - Exponential: Decay processes, growth curves - Quadratic: Curved trends, parabolic data - Cubic: Complex curved trends - Error Function: Step functions, cumulative distributions
Cursor Utilities#
Cursor 1: Middle-click to set the first cursor position
Cursor 2: Right-click to set the second cursor position
Range Selection: Use cursors to define fitting ranges
Data Analysis: View mathematical information between cursor positions
Advanced Features#
Curve Unscaling#
The “Un” column allows you to rescale curves to match the range of other Y curves:
How it works: - Select both “Y” and “Un” on the same row to unscale that curve - The unscaling formula: g(x) = ((f1(x) - m1) / (M1 - m1)) * (M23 - m23) + m23
m1, M1: min/max of the curve being unscaled
m23, M23: global min/max of other Y curves (excluding unscaled ones)
Use cases: - Range Matching: Scale curves with different ranges to the same scale for comparison - All Curves Unscaled: When all Y curves are selected for unscaling, they’re scaled to 0-1 range - Mixed Processing: Combine with I0 normalization for complex data analysis
Selection Rules: - “Un” requires “Y” selection on the same row - “Un” cannot be selected with “X” on the same row - “Un” cannot be selected with “I0” on the same row - Multiple “Un” selections allowed across different rows
Visual Indicators: - Unscaled curves show [unscaled] in their labels - Combined I0 + unscaling shows [norm, unscaled] in labels
Lazy Loading#
For large datasets, mdaviz uses lazy loading to improve performance: - Progress indicators show scanning status - Efficient folder scanning with configurable batch sizes - Automatic handling of large directories
Data Caching#
The application includes an LRU cache system for improved performance: - Frequently accessed data is cached in memory - Automatic cache management for large datasets - Configurable cache size limits
Recent Folders#
mdaviz remembers your recently opened folders: - Quick access to frequently used directories - Automatic folder list management - Clear recent folders option
Troubleshooting#
Common Issues#
Application won’t start: - Ensure PyQt6 is properly installed: pip install PyQt6 Qt6 - Check conda environment is activated: conda activate mdaviz - Verify Python version (3.10+ required)
No data displayed: - Check that the selected folder contains MDA files - Verify file permissions - Try refreshing the folder view
Fitting fails: - Ensure sufficient data points (at least 3 per parameter) - Try a different fit model - Check for invalid data values
Performance issues: - Large datasets may take time to load - Use lazy loading for directories with many files - Consider reducing cache size for memory-constrained systems
Command-line Options#
You can run mdaviz with command-line options:
python -m mdaviz.app --log debug
Available options: - –log LEVEL: Set logging level (debug, info, warning, error)
Testing & Development#
To run all tests:
pytest src/tests
To run code quality checks:
pre-commit run --all-files
Contributing#
Fork the repository and create a branch for your feature or bugfix.
Add or update tests for your changes.
Run pre-commit and pytest to ensure all checks pass.
Submit a pull request on GitHub.
For detailed contributing guidelines, see the project’s GitHub repository.