RosettaSciIO

Common errors

• ModuleNotFoundError: No module named 'dask'

  cause Attempting to use a feature (e.g., lazy loading, specific file format readers like Gatan DM) that relies on `dask` without it being installed. `dask` is an optional dependency.
  fix Install `rosettasciio` with the necessary extras, for example, `pip install "rosettasciio[gatan-dm]"` or `pip install "rosettasciio[all]"`.

• ValueError: No reader found for file_format: dm3

  cause Trying to read a file format (e.g., `.dm3`, advanced `.tif`) for which the required backend library is not installed, or the format is simply not supported by any available reader.
  fix Check if the format is supported by `rosettasciio`. If it is, install `rosettasciio` with the relevant optional dependencies. For example, for `.dm3` files, use `pip install "rosettasciio[gatan-dm]"`.

• PermissionError: [Errno 13] Permission denied: 'my_output_file.hdf5'

  cause The user account running the script does not have write permissions to the specified output directory when trying to save a file, or read permissions when trying to open.
  fix Change the output directory to one where the user has write permissions, or adjust the file system permissions for the target path or file.

Warnings

• gotcha Many advanced features or support for specific file formats (e.g., Gatan DM3/DM4, advanced TIFF, lazy loading with Dask, HyperSpy integration) require *optional* dependencies. These are not installed by default.
  Fix: Install `rosettasciio` with the necessary extras, for example, `pip install "rosettasciio[gatan-dm]"` for Gatan files, `pip install "rosettasciio[tifffile]"` for advanced TIFF, or `pip install "rosettasciio[all]"` for all optional features.
• breaking `rosettasciio` requires Python 3.10 or newer. Attempting to use older Python versions will lead to installation failures or runtime errors due to syntax or dependency incompatibilities.
  Fix: Ensure your Python environment is running Python 3.10 or later. Consider using `pyenv` or `conda` to manage Python versions.
• gotcha For efficient handling of very large files and distributed lazy loading, `dask` and often `hyperspy` are required optional dependencies. Without them, large files might be fully loaded into memory, potentially causing memory exhaustion.
  Fix: Install `rosettasciio` with the `dask` and `hspy` extras (e.g., `pip install "rosettasciio[hspy]"` or `pip install "rosettasciio[all]"`). When reading, check documentation for lazy loading options relevant to your file format.
• gotcha While `rsciio.read` can often return a `numpy.ndarray` by default, full integration with `hyperspy` signals for advanced analysis requires `hyperspy` to be installed.
  Fix: If you intend to work with `hyperspy` signals, install `hyperspy` as an optional dependency: `pip install "rosettasciio[hspy]"`.

Install

• pip install rosettasciio Basic installation
• pip install "rosettasciio[all]" Install with all optional dependencies

Imports

• read

  from rsciio import read

• write

  from rsciio import write

Quickstart

This quickstart demonstrates how to save a NumPy array to a common image format (PNG) and then read it back using RosettaSciIO. This leverages the `Pillow` dependency, which is installed by default.

import rsciio
import numpy as np
import os

# Create a dummy NumPy array (e.g., a simple image)
data_to_save = np.arange(100).reshape(10, 10).astype(np.uint8)
filename_png = "my_dummy_data.png"

print(f"Saving data to {filename_png} using rsciio.write...")
# rsciio.write handles numpy arrays and uses Pillow (a core dependency) for PNG.
rsciio.write(data_to_save, filename_png)
print(f"Successfully saved data to {filename_png}")

print(f"Reading data from {filename_png} using rsciio.read...")
# rsciio.read returns a numpy array by default
read_data = rsciio.read(filename_png)
print(f"Successfully read data from {filename_png}. Shape: {read_data.shape}")
print(f"Data type: {read_data.dtype}")

# Clean up the dummy file
os.remove(filename_png)
print(f"Cleaned up {filename_png}")