# mdaviz
Python Qt6 application to visualize mda data.
## Status Badges
CI/CD | Code Quality | Documentation | Package
--- | --- | --- | ---
[](https://github.com/BCDA-APS/mdaviz/actions/workflows/ci.yml) | [](https://github.com/astral-sh/ruff) | [](https://bcda-aps.github.io/mdaviz/) | [](https://badge.fury.io/py/mdaviz) [](https://github.com/BCDA-APS/mdaviz/releases)
Coverage | License | Python | Pre-commit
--- | --- | --- | ---
[](https://codecov.io/gh/BCDA-APS/mdaviz) | [](LICENSE.txt) | [](https://www.python.org/downloads/) | [](https://github.com/pre-commit/pre-commit)
## Features
* **Data Visualization**: Visualize MDA data with support for 1-D and 2D plots (mesh scans) with matplotlib integration.
* **Auto-Load Folders**: Automatically loads the first valid folder from recent folders list (can be disabled in the preferences).
* **Recent Folders**: Remembers recently opened folders for quick access.
* **Lazy Loading**: Efficient folder scanning with progress indicators for large datasets.
* **Curve Management**: Add, remove, and style multiple data curves.
* **Axis Selection**: Select X-axis (positioners), Y-axis (detectors), I0 normalization, and curve unscaling using checkboxes. Axis selection is saved from one file to the next.
* **Curve Unscaling**: Rescale curves to match the range of other Y curves for better comparison.
* **Data Analysis**: Basic statistics, cursor measurements, and curve fitting.
* **Metadata Search**: Searchable metadata to quickly locate specific parameters and settings.
* **Cross-Platform**: Runs on macOS and Linux (Windows TBD).
## Quickstart
### Option 1: Install from PyPI (Recommended for users)
Mdaviz is available on PyPI. We recommend creating a dedicated environment:
```bash
# Create a simple conda environment
conda create -n mdaviz python=3.12
conda activate mdaviz
pip install PyQt6 Qt6
# Install mdaviz
pip install mdaviz
```
Once installed, you can run the application at any time using:
```bash
conda activate mdaviz
mdaviz
```
**Note**:
* PyQt6 and Qt6 are required dependencies that may need to be installed separately via pip as they are not available in conda-forge for all platforms.
* At the APS: PyQt6 requires to install the following library:
```bash
sudo yum install xcb-util-cursor
```
### Option 2: Development setup with conda environment
For development and contributing, it is strongly recommended to use the provided conda environment. This ensures all dependencies (including PyQt6) are available and compatible.
```bash
# Clone the repo first
git clone https://github.com/BCDA-APS/mdaviz.git
cd mdaviz
# Create and activate conda environment
conda env create -f env.yml
conda activate mdaviz
pip install PyQt6 Qt6
# Install in development mode
pip install -e .
```
Once installed, you can run the application at any time using:
```bash
cd mdaviz
conda activate mdaviz
mdaviz
```
Always activate the environment before running, testing, or using pre-commit hooks.
**Note**:
* PyQt6 and Qt6 are required dependencies that may need to be installed separately via pip as they are not available in conda-forge for all platforms.
* At the APS: PyQt6 requires to install the following library:
```bash
sudo yum install xcb-util-cursor
```
## Usage
### Basic Operation
1. **Load Data**: Click "Open" (folder icon) and select an MDA file.
2. **Select Axes**: Use the checkboxes in the data table to select:
- **X**: Positioner for the x-axis (only one can be selected)
- **Y**: Detectors for the y-axis (multiple can be selected)
- **I0**: Normalization detector (only one can be selected)
- **Un**: Unscale curves to match the range of other Y curves (requires Y selection on same row)
3. **Plot Data**: Data will automatically plot based on your selection mode
### Plotting Modes
- **Auto-add**: New curves are added to existing plots
- **Auto-replace**: New curves replace existing plots
- **Auto-off**: Manual plotting using buttons
### Plot Controls
- **Log Scale**: Use the "LogX" and "LogY" checkboxes to switch between linear and logarithmic scales.
- **Curve Styling**: Select different line styles and markers for the selected curve.
- **Data Manipulation**: Apply offset and scaling factors to individual curves.
- **Data Analysis**: Basic statistics, cursor measurements, and curve fitting.
## Development
### Logging and Debugging
**Default Behavior:**
By default, `mdaviz` logs at the WARNING level, showing only warnings, errors and critical messages (quiet mode).
**Command Line Options:**
You can control the logging level using the `--log` argument:
```bash
# Show only errors and critical messages
mdaviz --log error
# Show warnings, errors, critical messages and info (progress messages, file loading status, and important application events).
mdaviz --log info
# Show all messages including debug information
mdaviz --log debug
```
**Log Files:**
Log files are automatically created in `~/.mdaviz/logs/` with timestamps. Old log files (older than 1 day) are automatically cleaned up on startup.
### Testing
Run all tests:
```bash
pytest src/tests
```
Current test status:
- **223 tests passing** with 54% coverage
- **48 skipped tests** (GUI tests in headless environment)
- **0 failed tests** (all tests are now passing!)
### Code Quality
The project uses pre-commit hooks for code quality. Run them before committing:
```bash
pre-commit run --all-files
```
## Contributing
1. Fork and clone the repository.
2. Create a new branch for your feature or bugfix.
3. Make your changes and add tests.
4. Run pre-commit and pytest to ensure all checks pass.
5. Submit a pull request.
For a complete installation guide, see [https://bcda-aps.github.io/mdaviz/](https://bcda-aps.github.io/mdaviz/).
## Acknowledgements
"This product includes software produced by UChicago Argonne, LLC
under Contract No. DE-AC02-06CH11357 with the Department of Energy."
Raw data
{
"_id": null,
"home_page": null,
"name": "mdaviz",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": "Fanny Rodolakis <rodolakis@anl.gov>, Pete Jemian <prjemian@gmail.com>, Rafael Vescovi <ravescovi@anl.gov>, Eric Codrea <ecodrea@anl.gov>",
"keywords": "mda, multidimensional-data, visualization, synchrotron, beamline, EPICS",
"author": null,
"author_email": "Fanny Rodolakis <rodolakis@anl.gov>, Pete Jemian <prjemian@gmail.com>, Rafael Vescovi <ravescovi@anl.gov>, Eric Codrea <ecodrea@anl.gov>",
"download_url": "https://files.pythonhosted.org/packages/42/8d/fbb4c7c3a59f837414ae31ea7c176d07f4f520ca7a906f2018fc3ca83d3d/mdaviz-1.2.3.tar.gz",
"platform": null,
"description": "# mdaviz\n\nPython Qt6 application to visualize mda data.\n\n## Status Badges\n\nCI/CD | Code Quality | Documentation | Package\n--- | --- | --- | ---\n[](https://github.com/BCDA-APS/mdaviz/actions/workflows/ci.yml) | [](https://github.com/astral-sh/ruff) | [](https://bcda-aps.github.io/mdaviz/) | [](https://badge.fury.io/py/mdaviz) [](https://github.com/BCDA-APS/mdaviz/releases)\n\nCoverage | License | Python | Pre-commit\n--- | --- | --- | ---\n[](https://codecov.io/gh/BCDA-APS/mdaviz) | [](LICENSE.txt) | [](https://www.python.org/downloads/) | [](https://github.com/pre-commit/pre-commit)\n\n## Features\n\n* **Data Visualization**: Visualize MDA data with support for 1-D and 2D plots (mesh scans) with matplotlib integration.\n* **Auto-Load Folders**: Automatically loads the first valid folder from recent folders list (can be disabled in the preferences).\n* **Recent Folders**: Remembers recently opened folders for quick access.\n* **Lazy Loading**: Efficient folder scanning with progress indicators for large datasets.\n* **Curve Management**: Add, remove, and style multiple data curves.\n* **Axis Selection**: Select X-axis (positioners), Y-axis (detectors), I0 normalization, and curve unscaling using checkboxes. Axis selection is saved from one file to the next.\n* **Curve Unscaling**: Rescale curves to match the range of other Y curves for better comparison.\n* **Data Analysis**: Basic statistics, cursor measurements, and curve fitting.\n* **Metadata Search**: Searchable metadata to quickly locate specific parameters and settings.\n* **Cross-Platform**: Runs on macOS and Linux (Windows TBD).\n\n## Quickstart\n\n### Option 1: Install from PyPI (Recommended for users)\n\nMdaviz is available on PyPI. We recommend creating a dedicated environment:\n\n```bash\n# Create a simple conda environment\nconda create -n mdaviz python=3.12\nconda activate mdaviz\npip install PyQt6 Qt6\n\n# Install mdaviz\npip install mdaviz\n```\n\nOnce installed, you can run the application at any time using:\n```bash\nconda activate mdaviz\nmdaviz\n```\n**Note**:\n* PyQt6 and Qt6 are required dependencies that may need to be installed separately via pip as they are not available in conda-forge for all platforms.\n* At the APS: PyQt6 requires to install the following library:\n```bash\nsudo yum install xcb-util-cursor\n```\n\n\n### Option 2: Development setup with conda environment\n\nFor development and contributing, it is strongly recommended to use the provided conda environment. This ensures all dependencies (including PyQt6) are available and compatible.\n\n```bash\n# Clone the repo first\ngit clone https://github.com/BCDA-APS/mdaviz.git\ncd mdaviz\n\n# Create and activate conda environment\nconda env create -f env.yml\nconda activate mdaviz\npip install PyQt6 Qt6\n\n# Install in development mode\npip install -e .\n```\n\nOnce installed, you can run the application at any time using:\n```bash\ncd mdaviz\nconda activate mdaviz\nmdaviz\n```\n\nAlways activate the environment before running, testing, or using pre-commit hooks.\n\n\n**Note**:\n* PyQt6 and Qt6 are required dependencies that may need to be installed separately via pip as they are not available in conda-forge for all platforms.\n* At the APS: PyQt6 requires to install the following library:\n```bash\nsudo yum install xcb-util-cursor\n```\n\n\n## Usage\n\n### Basic Operation\n\n1. **Load Data**: Click \"Open\" (folder icon) and select an MDA file.\n2. **Select Axes**: Use the checkboxes in the data table to select:\n - **X**: Positioner for the x-axis (only one can be selected)\n - **Y**: Detectors for the y-axis (multiple can be selected)\n - **I0**: Normalization detector (only one can be selected)\n - **Un**: Unscale curves to match the range of other Y curves (requires Y selection on same row)\n3. **Plot Data**: Data will automatically plot based on your selection mode\n\n### Plotting Modes\n\n- **Auto-add**: New curves are added to existing plots\n- **Auto-replace**: New curves replace existing plots\n- **Auto-off**: Manual plotting using buttons\n\n### Plot Controls\n\n- **Log Scale**: Use the \"LogX\" and \"LogY\" checkboxes to switch between linear and logarithmic scales.\n- **Curve Styling**: Select different line styles and markers for the selected curve.\n- **Data Manipulation**: Apply offset and scaling factors to individual curves.\n- **Data Analysis**: Basic statistics, cursor measurements, and curve fitting.\n\n\n\n## Development\n\n### Logging and Debugging\n\n**Default Behavior:**\nBy default, `mdaviz` logs at the WARNING level, showing only warnings, errors and critical messages (quiet mode).\n\n**Command Line Options:**\nYou can control the logging level using the `--log` argument:\n\n```bash\n# Show only errors and critical messages\nmdaviz --log error\n\n# Show warnings, errors, critical messages and info (progress messages, file loading status, and important application events).\nmdaviz --log info\n\n# Show all messages including debug information\nmdaviz --log debug\n```\n**Log Files:**\nLog files are automatically created in `~/.mdaviz/logs/` with timestamps. Old log files (older than 1 day) are automatically cleaned up on startup.\n\n\n### Testing\n\nRun all tests:\n```bash\npytest src/tests\n```\n\nCurrent test status:\n- **223 tests passing** with 54% coverage\n- **48 skipped tests** (GUI tests in headless environment)\n- **0 failed tests** (all tests are now passing!)\n\n\n### Code Quality\n\nThe project uses pre-commit hooks for code quality. Run them before committing:\n```bash\npre-commit run --all-files\n```\n\n## Contributing\n\n1. Fork and clone the repository.\n2. Create a new branch for your feature or bugfix.\n3. Make your changes and add tests.\n4. Run pre-commit and pytest to ensure all checks pass.\n5. Submit a pull request.\n\nFor a complete installation guide, see [https://bcda-aps.github.io/mdaviz/](https://bcda-aps.github.io/mdaviz/).\n\n## Acknowledgements\n\n\"This product includes software produced by UChicago Argonne, LLC\nunder Contract No. DE-AC02-06CH11357 with the Department of Energy.\"\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Qt6 application to visualize multi-dimensional arrays (MDA) files from synchrotron beamlines.",
"version": "1.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/BCDA-APS/mdaviz/issues",
"Homepage": "https://github.com/BCDA-APS/mdaviz"
},
"split_keywords": [
"mda",
" multidimensional-data",
" visualization",
" synchrotron",
" beamline",
" epics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5bf2ff026f4fbb4fc8b9013c45136cc3d7435f3b8f3088bd946494735d02414",
"md5": "51c5c1ccb4555da8fbeab8ac4aa57caf",
"sha256": "015c566b3bdd3db9e2cc3108a8af7f3214209374144a985813810fe27f9dc7c7"
},
"downloads": -1,
"filename": "mdaviz-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "51c5c1ccb4555da8fbeab8ac4aa57caf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 709812,
"upload_time": "2025-08-23T23:12:27",
"upload_time_iso_8601": "2025-08-23T23:12:27.749601Z",
"url": "https://files.pythonhosted.org/packages/b5/bf/2ff026f4fbb4fc8b9013c45136cc3d7435f3b8f3088bd946494735d02414/mdaviz-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "428dfbb4c7c3a59f837414ae31ea7c176d07f4f520ca7a906f2018fc3ca83d3d",
"md5": "590c4fc9aa8e7c9ea1325cbdfd81e3e8",
"sha256": "0dd5282192d519ff2d8706efcb0eb56260e678fac20d9b5c5b2ea9e243817397"
},
"downloads": -1,
"filename": "mdaviz-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "590c4fc9aa8e7c9ea1325cbdfd81e3e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 4814295,
"upload_time": "2025-08-23T23:12:29",
"upload_time_iso_8601": "2025-08-23T23:12:29.765017Z",
"url": "https://files.pythonhosted.org/packages/42/8d/fbb4c7c3a59f837414ae31ea7c176d07f4f520ca7a906f2018fc3ca83d3d/mdaviz-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 23:12:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BCDA-APS",
"github_project": "mdaviz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdaviz"
}
JSON
