{"id":9284,"library":"rosettasciio","title":"RosettaSciIO","description":"RosettaSciIO is a Python library for reading and writing various scientific file formats, designed with a focus on ease of use and integration with scientific data analysis tools like HyperSpy. It supports a wide range of formats including HDF5, TIFF, DigitalMicrograph (DM3/DM4), and more, often leveraging optional backend libraries. The current version is 0.13.0, and new minor releases occur every few months, introducing new features and format support.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/hyperspy/rosettasciio","tags":["scientific","file-formats","io","hyperspy","materials-science","microscopy"],"install":[{"cmd":"pip install rosettasciio","lang":"bash","label":"Basic installation"},{"cmd":"pip install \"rosettasciio[all]\"","lang":"bash","label":"Install with all optional dependencies"}],"dependencies":[{"reason":"Required for HDF5-based formats.","package":"h5py"},{"reason":"Required for XML-based metadata and formats.","package":"lxml"},{"reason":"Required for MRC/MRCZ file formats.","package":"mrcz"},{"reason":"Fundamental for array manipulation and data representation.","package":"numpy"},{"reason":"Required for common image formats (PNG, JPEG, BMP).","package":"Pillow"},{"reason":"Required for handling physical units.","package":"pint"},{"reason":"Required for various scientific computing tasks and some formats (e.g., MAT files).","package":"scipy"}],"imports":[{"symbol":"read","correct":"from rsciio import read"},{"symbol":"write","correct":"from rsciio import write"}],"quickstart":{"code":"import rsciio\nimport numpy as np\nimport os\n\n# Create a dummy NumPy array (e.g., a simple image)\ndata_to_save = np.arange(100).reshape(10, 10).astype(np.uint8)\nfilename_png = \"my_dummy_data.png\"\n\nprint(f\"Saving data to {filename_png} using rsciio.write...\")\n# rsciio.write handles numpy arrays and uses Pillow (a core dependency) for PNG.\nrsciio.write(data_to_save, filename_png)\nprint(f\"Successfully saved data to {filename_png}\")\n\nprint(f\"Reading data from {filename_png} using rsciio.read...\")\n# rsciio.read returns a numpy array by default\nread_data = rsciio.read(filename_png)\nprint(f\"Successfully read data from {filename_png}. Shape: {read_data.shape}\")\nprint(f\"Data type: {read_data.dtype}\")\n\n# Clean up the dummy file\nos.remove(filename_png)\nprint(f\"Cleaned up {filename_png}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Python environment is running Python 3.10 or later. Consider using `pyenv` or `conda` to manage Python versions.","message":"`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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.12.0"},{"fix":"If you intend to work with `hyperspy` signals, install `hyperspy` as an optional dependency: `pip install \"rosettasciio[hspy]\"`.","message":"While `rsciio.read` can often return a `numpy.ndarray` by default, full integration with `hyperspy` signals for advanced analysis requires `hyperspy` to be installed.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `rosettasciio` with the necessary extras, for example, `pip install \"rosettasciio[gatan-dm]\"` or `pip install \"rosettasciio[all]\"`.","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.","error":"ModuleNotFoundError: No module named 'dask'"},{"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]\"`.","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.","error":"ValueError: No reader found for file_format: dm3"},{"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.","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.","error":"PermissionError: [Errno 13] Permission denied: 'my_output_file.hdf5'"}]}