SDF Force: A wrapper for force curve specific SDF files

Introduction

In general, SDF files are supposed to be independent of any particular instrument or measurement type. In working group practice, some specific file formats are more relevant than others. Their internal structure has, to some extent, become standard vocabulary around users of a particular measurement method.

Here, we want to focus on force curve data that have been generated by AFM instruments, where the two most important manufactures appearing are JPK and MFP.

As JPK nomenclature for data lines and parameters seems to be accepted by most as standard, it makes sense to define a subset of SDF specifically designed for force curve data. These subset SDF files are still legal SDF in every sense. They introduce, however, a structure and set of standard data lines and parameters, that are expected to be in every force curve. A special converter designed for this purpose scans appropriate SDF files, extracts needed data lines, renames them wherever a discrepancy to the standard names appears, and saves these files to the new SDF subset format, which we will give the conventional name of .force.sdf. Some standard data lines which may for example not be present in files provided by JPK but can be calculated from data lines present together with parameters given will be calculated and included in these files.

This approach, of course, requires special knowledge of the inner workings of (possibly) proprietary file formats from specific manufacturers. It also decreases the user’s possibility to freely choose an inner format for their SDF files. We believe, that the ubiquity of force curve data within some working groups warrants this decrease in freedom for the purpose of a unified interface for these files.

While .force.SDF are created from standard SDF files, they will only contain a subset of parameters and data lines, the conversion is thus lossy. For archive purposes, the originally created SDF file should be kept, not the resulting .force.SDF file.

File structure

• File: <workspace> with name ForceSDF [...]

  • Global parameters: <instrument> with name parameters

  • N segments: <workspace> with name segment i, with index i from 0 to N-1

    • Segment parameters: <instrument> with name segment-parameters

    • M Segment data channels: <dataset type="sc"> with name [channel name] and one 1D array

      <data>

Global parameters

• required

  • sensitivity: number, preferred unit: m/V

  • spring_constant: number, preferred unit: N/m

• optional

  • additional parameters can be included

  • they should have a prefix specifying the origin (e.g. mfp-[...] for mfp measurements)

Segment parameters

• required:

  • duration: number, preferred unit: s

  • velocity: number, preferred unit m/s

  • direction: one of z-retract-force, constant-height-pause and z-extend-force

• optional

  • x, y, position_index: numbers, position in a force map measurement grid

Segment datasets

• required:

  • height: 1D array, preferred unit: m

  • measuredHeight: 1D array, preferred unit: m

  • vDeflection: 1D array, preferred unit: N or m

• optional:

  • additional datasets can be included

• automatically generated:

  • if vDeflection in m is given, or can be obtained from vDeflection in N plus spring_constant in N/m, the measuredTipSample separation in m (measuredHeight+vDeflection) is automatically generated

  • in that case, the tipSample separation in m (height+vDeflection) is also automatically generated

  • if the duration in s is given, the velocity in m/s (measuredHeight/duration) is automatically generated

Additional elements

Any additional parameters and datasets are allowed. Some modifications might lead to errors when trying to open the resulting ForceSDF file using the Python ForceSDF API. In such cases, please contact the developers. Access via the more general Workspace API is always possible, since ForceSDF is just a subset of the Workspace specification.

Export to MATLAB .mat files

ForceSDF objects can be exported to MATLAB .mat files. The result is the equivalent of a Python dict of the following structure:

{
    # global parameters
    "spring_constant": ...,
    "sensitivity": ...,
    ...,
    # segments
    "segment 0": {
        # segment parameters
        "duration": ...,
        ...,
        # segment data channels
        "height_unit": "m",
        "height": np.ndarray([...])
        ...,
    }
    "segment 1": {
        ...
    }
}

Exceptions, fallbacks

Missing conversions

Sometimes, the unit of a data array cannot be read, since the conversions are not included in the original files.

JPK

If the original conversions from integers to distance and force are not included in the original .jpk-force file, the spring_constant and sensitivity are NaN and the arrays vDeflection, hDeflection do not have a unit, since the relevant metadata is missing.

MFP

If the SpringConstant in the original .ibw file is exactly 1 and the InvOLS (equivalent to sensitivity) is exactly 1e-07, it is assumed that these are fallback values and the real conversion was done externally and is unknown to the converter. In such cases, the vDeflection data channel and the global parameters spring_constant and sensitivity have no unit.