Hystorian Documentation

Hystorian is a Python package based on h5py, designed for scientists to help manage, archive, and analyze data from Scanning Probe Microscopy (SPM) experiments and related sources.

Overview

Hystorian provides a unified framework for:

• Storing experimental data in HDF5 format for efficient access and archiving.

• Converting raw data files from common SPM instruments (e.g., GSF, IBW, Nanoscope, ARDF) into HDF5.

• Extracting, processing, and analyzing experimental datasets.

• Applying advanced image alignment and distortion correction algorithms.

• Managing experiment metadata, results, and reproducibility.

• Extensible processing: apply custom and built-in processing functions to datasets.

Key Features

• Data Conversion: Import and convert raw files from various SPM instruments.

• Unified Data Storage: Organize and archive data using HDF5, supporting metadata and hierarchical structures.

• Distortion Correction: Correct image distortions for accurate quantitative analysis.

• Experiment Management: Tools for handling experiment metadata, results, and reproducibility.

• Extensible Processing: Apply custom and built-in processing functions to datasets.

Installation

pip install hystorian

Quick Start

from hystorian.io.hyFile import HyFile
with HyFile('mydata.hdf5', 'r+') as f:
    f.extract_data('/path/to/file.ibw')

API Reference

This section provides a comprehensive overview of the Hystorian Python package API, organized by module. Use the links below to explore the available classes, functions, and utilities for data management, conversion, processing, and experiment analysis.

Core Modules

• HyFile — HDF5 file management and data extraction

• File Conversion (i/o) — Raw file conversion utilities

• Processing — Distortion correction and data processing

• Experiments — Experiment organization and analysis

How to Use

Here is a short working example:

# Open and extract data from an HDF5 file
from hystorian.io.hyFile import HyFile
with HyFile('data.hdf5', 'r+') as f:
    f.extract_data('/path/to/raw/file.ibw')

# Apply processing functions
from hystorian.processing.distortion import find_transform_ecc
warp_matrix = find_transform_ecc(reference_image, image_to_align)

If you want a more detailed walkthrough go to Walkthrough: How Does Hystorian Works?.

Documentation Contents

• HyFile
  • HyApply
  • HyFile
  • HyPath
  • Example: Extract and process data
• File Conversion (i/o)
  • HyConvertedData
  • Conversion Functions
  • Example: Convert a raw file
• Experiments
  • extract_hysteresis()
• Processing
  • Distortion Correction
  • General Correction
  • SPM Utilities
  • Operations
• Walkthrough: How Does Hystorian Works?
  • 1. How to extract the data?
  • 2. How to read the data?
  • 3. How to modify the data?

Publication Source

For a detailed description of the concepts and algorithms implemented in Hystorian, see:

Loïc Musy, Ralph Bulanadi, Iaroslav Gaponenko, Patrycja Paruch, Hystorian: A processing tool for scanning probe microscopy and other n-dimensional datasets Ultramicroscopy, Volume 228, 2021 https://www.sciencedirect.com/science/article/pii/S0304399121001273

Note

This project is under active development.