# xarray-nanonis
**Extending xarray to read Nanonis files with coordinates and metadata.**
`xarray-nanonis` is a Python package that integrates Nanonis data files into the xarray ecosystem. It provides support for reading `.sxm`, `.dat`, and `.3ds` files directly into xarray Datasets, complete with proper dimensions, units, coordinate information, and metadata preservation.
## Features
- **Xarray integration**: Load Nanonis files directly as xarray Datasets using `open_dataset()`
- **Full metadata preservation**: Header information is preserved as Dataset attributes
- **Proper dimensions and coordinates**: Spatial (x, y) and energy (bias) coordinates with units
- **Multi-channel support**: Multiple measurement channels can be retrieved from datasets easily
- **Unit handling**: Automatic parsing and assignment of physical units
- **Scan direction support**: Forward/backward scan data for `.sxm` files
- **Advanced spectroscopy features**: Support for Multi-Linear Segments (MLS) bias sweeps
## Installation
Install from PyPI:
```bash
pip install xarray-nanonis
```
## Quick Start
### Loading Nanonis files with xarray
Once installed, you can load Nanonis files directly using xarray's `open_dataset()`:
```python
import xarray as xr
# Load a topography scan
ds_topo = xr.open_dataset('topography.sxm')
# or
ds_topo = xr.open_dataset('topography.sxm', engine='nanonis')
# Load point spectroscopy data
ds_spec = xr.open_dataset('spectrum.dat')
# or
ds_spec = xr.open_dataset('spectrum.dat', engine='nanonis')
# Load grid spectroscopy data
ds_grid = xr.open_dataset('grid_spectroscopy.3ds')
# or
ds_grid = xr.open_dataset('grid_spectroscopy.3ds', engine='nanonis')
```
## Usage Examples
### Topography Data (.sxm files)
```python
import xarray as xr
import matplotlib.pyplot as plt
# Load topography data
ds = xr.open_dataset('topography.sxm', engine='nanonis')
# The dataset contains multi-channel data
print(ds.data_vars) # Shows available channels (e.g., 'Z', 'Current', etc.)
# Metadata is stored in attributes
print(ds.attrs) # Contains scan parameters, bias, etc.
# Plot topography
ds['Z'].sel(dir='forward').plot.pcolormesh() # Forward scan topography
plt.title(f"Topography - Bias: {ds.attrs['BIAS']} V")
plt.show()
# Access scan parameters
print(f"Scan size: {ds.attrs['SCAN_RANGE']} m")
print(f"Pixels: {ds.attrs['SCAN_PIXELS']}")
```
### Point Spectroscopy (.dat files)
```python
# Load I-V spectroscopy
ds = xr.open_dataset('dIdV_spectrum.dat', engine='nanonis')
# Plot dI/dV vs bias
ds['LI_Demod_1_X'].plot(x='bias')
plt.show()
```
### Grid Spectroscopy (.3ds files)
```python
# Load grid spectroscopy data
ds = xr.open_dataset('grid_spectroscopy.3ds', engine='nanonis')
# Access spectroscopy grid
dIdV_map = ds['LI_Demod_1_X'] # Shape: (bias, y, x)
# Plot dI/dV map at specific bias
dIdV_map.sel(bias=0.1, method='nearest').plot.pcolormesh()
plt.show()
```
### Advanced: Custom voltage divider
For systems with voltage dividers, you can specify the division factor:
```python
# For a system with 10:1 voltage divider
ds = xr.open_dataset('data.sxm', engine='nanonis', divider=10)
```
However, this only works for coordinates, not metadata.
## Data Structure
All Nanonis files are loaded as xarray Datasets with:
- **Coordinates**: Spatial (x, y) and energy (bias) dimensions with units
- **Data variables**: Measurement channels (Current, Topography, Lock-in signals, etc.)
- **Attributes**: Complete header information
- **Units**: Proper unit handling for all variables and coordinates
Example dataset structure:
```
<xarray.Dataset>
Dimensions: (x: 256, y: 256, dir: 2)
Coordinates:
* x (x) float64 0.0 1.95e-10 3.91e-10 ... 4.98e-08 5.0e-08
* y (y) float64 0.0 1.95e-10 3.91e-10 ... 4.98e-08 5.0e-08
* dir (dir) <U8 'forward' 'backward'
Data variables:
Z (dir, y, x) float32 ...
Current (dir, y, x) float32 ...
Attributes:
SCAN_PIXELS: 512 512
SCAN_RANGE: 5.0e-08 5.0e-08
BIAS: 0.1
...
```
## Requirements
- Python ≥ 3.9
- xarray
- numpy
- pandas
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
This package extends the functionality of [xarray](https://xarray.pydata.org/) for the scanning probe microscopy community. Special thanks to the [xarray](https://xarray.pydata.org/) development team for creating such a powerful and flexible data analysis toolkit, and to the [nanonispy](https://github.com/underchemist/nanonispy) project for providing the foundation for parsing Nanonis file formats.
Raw data
{
"_id": null,
"home_page": null,
"name": "xarray-nanonis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Hao Zhang <zhanghao3859@hotmail.com>",
"keywords": "xarray, nanonis, scanning probe microscopy, SPM, STM, AFM, data analysis",
"author": null,
"author_email": "Hao Zhang <zhanghao3859@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/54/ef/895b4ea23e564d28c5d441ea7ecb07a36605877ece78b294d5058b6de52b/xarray_nanonis-2025.10.0.tar.gz",
"platform": null,
"description": "# xarray-nanonis\n\n**Extending xarray to read Nanonis files with coordinates and metadata.**\n\n`xarray-nanonis` is a Python package that integrates Nanonis data files into the xarray ecosystem. It provides support for reading `.sxm`, `.dat`, and `.3ds` files directly into xarray Datasets, complete with proper dimensions, units, coordinate information, and metadata preservation.\n\n## Features\n\n- **Xarray integration**: Load Nanonis files directly as xarray Datasets using `open_dataset()`\n- **Full metadata preservation**: Header information is preserved as Dataset attributes\n- **Proper dimensions and coordinates**: Spatial (x, y) and energy (bias) coordinates with units\n- **Multi-channel support**: Multiple measurement channels can be retrieved from datasets easily\n- **Unit handling**: Automatic parsing and assignment of physical units\n- **Scan direction support**: Forward/backward scan data for `.sxm` files\n- **Advanced spectroscopy features**: Support for Multi-Linear Segments (MLS) bias sweeps\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install xarray-nanonis\n```\n\n## Quick Start\n\n### Loading Nanonis files with xarray\n\nOnce installed, you can load Nanonis files directly using xarray's `open_dataset()`:\n\n```python\nimport xarray as xr\n\n# Load a topography scan\nds_topo = xr.open_dataset('topography.sxm')\n# or\nds_topo = xr.open_dataset('topography.sxm', engine='nanonis')\n\n# Load point spectroscopy data \nds_spec = xr.open_dataset('spectrum.dat')\n# or\nds_spec = xr.open_dataset('spectrum.dat', engine='nanonis')\n\n# Load grid spectroscopy data\nds_grid = xr.open_dataset('grid_spectroscopy.3ds')\n# or \nds_grid = xr.open_dataset('grid_spectroscopy.3ds', engine='nanonis')\n```\n\n## Usage Examples\n\n### Topography Data (.sxm files)\n\n```python\nimport xarray as xr\nimport matplotlib.pyplot as plt\n\n# Load topography data\nds = xr.open_dataset('topography.sxm', engine='nanonis')\n\n# The dataset contains multi-channel data\nprint(ds.data_vars) # Shows available channels (e.g., 'Z', 'Current', etc.)\n\n# Metadata is stored in attributes\nprint(ds.attrs) # Contains scan parameters, bias, etc.\n\n# Plot topography\nds['Z'].sel(dir='forward').plot.pcolormesh() # Forward scan topography\nplt.title(f\"Topography - Bias: {ds.attrs['BIAS']} V\")\nplt.show()\n\n# Access scan parameters\nprint(f\"Scan size: {ds.attrs['SCAN_RANGE']} m\")\nprint(f\"Pixels: {ds.attrs['SCAN_PIXELS']}\")\n```\n\n### Point Spectroscopy (.dat files)\n\n```python\n# Load I-V spectroscopy\nds = xr.open_dataset('dIdV_spectrum.dat', engine='nanonis')\n\n# Plot dI/dV vs bias\nds['LI_Demod_1_X'].plot(x='bias')\nplt.show()\n```\n\n### Grid Spectroscopy (.3ds files)\n\n```python\n# Load grid spectroscopy data\nds = xr.open_dataset('grid_spectroscopy.3ds', engine='nanonis')\n\n# Access spectroscopy grid\ndIdV_map = ds['LI_Demod_1_X'] # Shape: (bias, y, x)\n\n# Plot dI/dV map at specific bias\ndIdV_map.sel(bias=0.1, method='nearest').plot.pcolormesh()\nplt.show()\n```\n\n### Advanced: Custom voltage divider\n\nFor systems with voltage dividers, you can specify the division factor:\n\n```python\n# For a system with 10:1 voltage divider\nds = xr.open_dataset('data.sxm', engine='nanonis', divider=10)\n```\n\nHowever, this only works for coordinates, not metadata.\n\n## Data Structure\n\nAll Nanonis files are loaded as xarray Datasets with:\n\n- **Coordinates**: Spatial (x, y) and energy (bias) dimensions with units\n- **Data variables**: Measurement channels (Current, Topography, Lock-in signals, etc.)\n- **Attributes**: Complete header information\n- **Units**: Proper unit handling for all variables and coordinates\n\nExample dataset structure:\n```\n<xarray.Dataset>\nDimensions: (x: 256, y: 256, dir: 2)\nCoordinates:\n * x (x) float64 0.0 1.95e-10 3.91e-10 ... 4.98e-08 5.0e-08\n * y (y) float64 0.0 1.95e-10 3.91e-10 ... 4.98e-08 5.0e-08 \n * dir (dir) <U8 'forward' 'backward'\nData variables:\n Z (dir, y, x) float32 ...\n Current (dir, y, x) float32 ...\nAttributes:\n SCAN_PIXELS: 512 512\n SCAN_RANGE: 5.0e-08 5.0e-08\n BIAS: 0.1\n ...\n```\n\n## Requirements\n\n- Python \u2265 3.9\n- xarray\n- numpy \n- pandas\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nThis package extends the functionality of [xarray](https://xarray.pydata.org/) for the scanning probe microscopy community. Special thanks to the [xarray](https://xarray.pydata.org/) development team for creating such a powerful and flexible data analysis toolkit, and to the [nanonispy](https://github.com/underchemist/nanonispy) project for providing the foundation for parsing Nanonis file formats.\n",
"bugtrack_url": null,
"license": null,
"summary": "Extending xarray to read Nanonis files with coordinates and metadata",
"version": "2025.10.0",
"project_urls": {
"Bug Tracker": "https://github.com/John3859/xarray-nanonis/issues",
"Documentation": "https://github.com/John3859/xarray-nanonis#readme",
"Homepage": "https://github.com/John3859/xarray-nanonis",
"Repository": "https://github.com/John3859/xarray-nanonis"
},
"split_keywords": [
"xarray",
" nanonis",
" scanning probe microscopy",
" spm",
" stm",
" afm",
" data analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a7e09fe97bafc5a4ede9b2919380db33fa123221a0385fcd310efbe4ed8de713",
"md5": "e946ac4ffcf1daf5eb3942eae88f03fb",
"sha256": "ba86f2a61ef87cd051949b86ca4a0483ca2677f73d0b1864d5f039d41967742f"
},
"downloads": -1,
"filename": "xarray_nanonis-2025.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e946ac4ffcf1daf5eb3942eae88f03fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15850,
"upload_time": "2025-10-27T10:22:36",
"upload_time_iso_8601": "2025-10-27T10:22:36.984514Z",
"url": "https://files.pythonhosted.org/packages/a7/e0/9fe97bafc5a4ede9b2919380db33fa123221a0385fcd310efbe4ed8de713/xarray_nanonis-2025.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "54ef895b4ea23e564d28c5d441ea7ecb07a36605877ece78b294d5058b6de52b",
"md5": "581a238e801c4939915bb32fc498f93e",
"sha256": "74d569874fccf7c81aec29078dd6182abc59b14e9c5851e69cf92738015f9ea3"
},
"downloads": -1,
"filename": "xarray_nanonis-2025.10.0.tar.gz",
"has_sig": false,
"md5_digest": "581a238e801c4939915bb32fc498f93e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 52840,
"upload_time": "2025-10-27T10:22:38",
"upload_time_iso_8601": "2025-10-27T10:22:38.332602Z",
"url": "https://files.pythonhosted.org/packages/54/ef/895b4ea23e564d28c5d441ea7ecb07a36605877ece78b294d5058b6de52b/xarray_nanonis-2025.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 10:22:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "John3859",
"github_project": "xarray-nanonis",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xarray-nanonis"
}
JSON
