AFMReader

A library for loading various Atomic Force Microscopy (AFM) file formats into Python. This library is primarily intended for use with TopoStats.

Supported file formats

| File format | Description | |-----------------|---------------------------------------------------| | .asd | High-speed AFM | | .gwy | Gwydion | | .h5-jpk | Bruker | | .ibw | WaveMetrics | | .jpk-qi-image | Bruker | | .jpk | Bruker | | .spm | Bruker's Format | | .stp | WSXM AFM software files | | .top | .stp variant | | .topostats | TopoStats |

Support for the following additional formats is planned. Some of these are already supported in TopoStats and are awaiting refactoring to move their functionality into AFMReader these are denoted in bold below.

| File format | Description | Status | |-------------|---------------------------------------------------------|--------------------------------------------| | .nhf | Nanosurf | To Be Implemented. | | .aris | Imaris Oxford Instruments | To Be Implemented. | | .tiff | Park Systems | To Be Implemented. |

Usage

If you wish to process AFM images supported by AFMReader it is recommend you use TopoStats to do so, however the library can be used on its own.

.topostats

You can open .topostats files using the load_topostats function. Just pass in the path to the file.

```python from AFMReader.topostats import load_topostats

image, pixeltonanometrescalingfactor, metadata = loadtopostats(filepath="./mytopostatsfile.topostats") ```

.spm

You can open .spm files using the load_spm function. Just pass in the path to the file and the channel name that you want to use. (If in doubt use one of the following: "Height", "ZSensor", "Height Sensor").

```python from AFMReader.spm import load_spm

image, pixeltonanometrescalingfactor = loadspm(filepath="./myspmfile.spm", channel="Height") ```

.gwy

You can open .gwy files using the load_gwy function. Just pass in the path to the file and the channel name that you want to use. (If in doubt use one one of the following: "Height", "ZSensor", "Height Sensor").

```python from AFMReader.gwy import load_gwy

image, pixeltonanometrescalingfactor = loadgwy(filepath="./mygwyfile.gwy", channel="Height") ```

.asd

You can open .asd files using the load_asd function. Just pass in the path to the file and the channel name that you want to use. (If in doubt use the "TP" topography channel).

Note: For .asd files, there seem to only ever be two channels in one file. "TP" (topography) is the main one you will want to use unless you know you specifically want something else.

Other channels: "ER" - Error, "PH" - Phase

```python from AFMReader.asd import load_asd

frames, pixeltonanometrescalingfactor, metadata = loadasd(filepath="./myasdfile.asd", channel="TP") ```

.ibw

You can open .ibw files using the load_ibw function. Just pass in the path to the file and the channel name that you want to use. (If in doubt, use HeightTracee (yes, with the extra 'e'), ZSensorTrace, or ZSensor).

```python from AFMReader.ibw import load_ibw

image, pixeltonanometrescalingfactor = loadibw(filepath="./myibwfile.ibw", channel="HeightTracee") ```

.jpk

You can open .jpk files using the load_jpk function. Just pass in the path to the file and the channel name you want to use. (If in doubt, use height_trace or measuredHeight_trace).

```python from AFMReader.jpk import load_jpk

image, pixeltonanometrescalingfactor = loadjpk(filepath="./myjpkfile.jpk", channel="height_trace") ```

.h5-jpk

You can open .h5-jpk files using the load_h5jpk function. Just pass in the path to the file and the channel name you want to use. (If in doubt, use height_trace or measuredHeight_trace).

Note: Since .h5-jpk stores timeseries AFM data a dictionary of timestamps for each frame is also returned.

```python from AFMReader.h5jpk import loadh5jpk

frames, pixeltonanometrescalingfactor, timestampdict = loadh5jpk(filepath="./myjpkfile.jpk", channel="heighttrace") ```

.stp

You can open .stp files using the load_stp function. Just pass in the path to the file you want to use.

```python from AFMReader.stp import load_stp

image, pixeltonanometrescalingfactor = loadstp(filepath="./mystpfile.stp") ```

.top

You can open .top files using the load_top function. Just pass in the path to the file you want to use.

```python from AFMReader.top import load_top

image, pixeltonanometrescalingfactor = loadtop(filepath="./mytopfile.top") ```

Contributing

Bug reports and feature requests are welcome. Please search for existing issues, if none relating to your bug/feature are found then feel free to create a new issue detailing what went wrong or the feature you would like to see implemented.

Pull requests are also welcome, please note that we have a Code of Conduct.

Setup

We use pre-commit to apply linting via ruff and pylint pre-commit hooks and use the Black and Flake8 code styles. To set yourself up for contributing after cloning the package and creating a Python virtual environment you should install the development dependencies and pre-commit as shown below.

``` bash

Activate your virtual environment, this will depend on which system you use e.g. conda or virtualenvwrapper

Clone the repository

git clone git@github.com:AFM-SPM/AFMReader.git

Change directories into the newly cloned directory

cd AFMReader

Install the package along with the optional development (dev) dependencies

pip install -e .[dev]

Install pre-commit

pre-commit install ```

This will ensure that any commits and pull requests you make will pass the Pre-commit Continuous Integration. Where possible ruff will correct the changes it can, but it may require you to address some issues manually, before adding any changes and attempting to commit again.

Citing

If you use or depend on AFMReader in your software please consider citing it in any derivative work that is published. Citation details can be found in the CITATION.cff file in this repository.

Also, please let us know if you use AFMReader in your software. You can either make a Pull Request to add it to the list below or you can email us at topostats@sheffield.ac.uk with details of your package.

Used By

AFMReader is a dependency of the following packages.

• pNanoLocz
• TopoStats