Metadata-Version: 2.1
Name: magic-afm
Version: 1.0.0b0
Summary: Code to analyze and understand Magic Ratio AFM
Author-email: richardsheridan <richard.sheridan@gmail.com>
Project-URL: Homepage, https://github.com/richardsheridan/magic-afm
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: attrs >=23.2.0
Requires-Dist: numpy >=1.21
Requires-Dist: samplerate ==0.1.0
Provides-Extra: build
Requires-Dist: pyinstaller ; extra == 'build'
Requires-Dist: build ; extra == 'build'
Requires-Dist: twine ; extra == 'build'
Provides-Extra: gui
Requires-Dist: imageio ; extra == 'gui'
Requires-Dist: pillow >=9 ; extra == 'gui'
Requires-Dist: psutil ; extra == 'gui'
Requires-Dist: matplotlib >=3.8.0 ; extra == 'gui'
Requires-Dist: trio >=0.20.0 ; extra == 'gui'
Requires-Dist: trio-parallel >1.1.0 ; extra == 'gui'
Requires-Dist: tqdm >=4.56.0 ; extra == 'gui'
Provides-Extra: h5py
Requires-Dist: h5py >=3 ; extra == 'h5py'
Provides-Extra: notebook
Requires-Dist: notebook >=7 ; extra == 'notebook'
Requires-Dist: ipywidgets ; extra == 'notebook'
Requires-Dist: scipy ; extra == 'notebook'
Requires-Dist: tqdm >=4.56.0 ; extra == 'notebook'
Requires-Dist: matplotlib >=3.8.0 ; extra == 'notebook'
Provides-Extra: numba
Requires-Dist: numba >=0.54.0 ; extra == 'numba'

=====================================================
Magic AFM -- Force curve analysis for Magic Ratio AFM
=====================================================

Magic AFM is Free Software (see `LICENSE <LICENSE>`__) for the analysis of AFM
force curves (static force spectroscopy) on polymers and other soft materials.

Features:

- Robust force curve fitting. (Parabolic indenter with DMT/JKR/LJ adhesion via [SCHWARZ]_.)

- Responsive interface for direct visual inspection/exploration of curves and fits.

- Sensitivity analysis of modulus error, to help identify if imaging conditions
  are amplifying or suppressing systemic error.

Supported file formats:

- QNM and FFV data from Nanoscope V3 or higher (Bruker/Veeco .spm/.pfc)

- Asylum research ARDF/HDF5

- Additional format contributions welcome!

Motivation
----------
This package is companion software to our recent publication, "Vanishing
Cantilever Calibration Error with Magic Ratio Atomic Force Microscopy" [MRAFM]_,
where we show that the ratio of cantilever deflection to tip indentation is an
important dimensionless number controlling the amplification or suppression of
sources of error, and that under common thermal calibration methods the
sensitivity of modulus estimates to the spring constant error can be eliminated
through choice of system parameters.

We hoped to create a force curve analysis package that helps AFM users to
calculate indentation ratios and modulus sensitivities for their force curve
data in an intuitive and responsive package.  By facilitating these sorts of
calculations, we hope to improve the overall systematic error of reported
modulus maps in the greater AFM nanomechanics community.

.. [MRAFM] Sheridan, R. J., Collinson, D. W., & Brinson, L. C. (2020).
        "Vanishing Cantilever Calibration Error with Magic Ratio Atomic Force
        Microscopy." Advanced Theory and Simulations, 3(8), 2000090.
        `DOI:10.1002/adts.202000090 <https://doi.org/10.1002/adts.202000090>`__

.. [SCHWARZ] Schwarz, U. D. (2003). A generalized analytical model for the
        elastic deformation of an adhesive contact between a sphere and a flat
        surface. Journal of Colloid and Interface Science, 261(1), 99–106.
        `DOI:10.1016/S0021-9797(03)00049-3
        <https://doi.org/10.1016/S0021-9797(03)00049-3>`_

Installation
------------
Requires CPython 3.11 or higher. (As of v0.9.0, we can read ARDF files natively,
so :code:`ARDFtoHDF5.exe` is no longer required. We can still read the converted
HDF5 files, if necessary.)

From source
^^^^^^^^^^^
Clone the git repository to your local machine, and
install into a fresh environment::

    git clone https://github.com/richardsheridan/magic-afm.git

    python -m venv magic_afm
    magic_afm\Scripts\activate.bat (or) magic_afm\bin\activate
    pip install -e .[gui,numba]
    (or)
    conda create -n magic_afm python=3.11
    conda activate magic_afm
    pip install -e .[gui,numba]

This is also a `Pixi <https://pixi.sh/>`_ project, so if you install Pixi, the
Python install is automatic and fast.


From PyPI
^^^^^^^^^
Eventually we should supply a pypi distribution.

From GitHub Releases
^^^^^^^^^^^^^^^^^^^^
We use PyInstaller to build executable releases for Windows on Github.
Simply download the ZIP archive, extract it to your hard drive.

Usage
-----
All functionality available when the source is imported from the :code:`magic_afm`,
see API_. :code:`magic fitting workflow.ipynb` doubles as an explainer and alternative
interface. It also functions as the test suite for the calculation code, such as it is.
The notebook needs additional dependencies you can get with the :code:`notebook` extra.

Running the GUI
^^^^^^^^^^^^^^^

All platforms, when running from source or PyPI::

     python -m magic_afm.gui

or if you are a Pixi user, you can use this while in the source tree::

     pixi run gui

When running the GitHub release executable for Windows::

     magic_gui.exe

To load data, select "Open..." from the File menu, or press Ctrl+O. A dialog
will open that will allow you to navigate and select any supported filetype.
This will open a data window and populate a number of options in the main window.
Many files and windows can be open simultaneously; the main window options will
display/affect the attributes of the *last selected* data window.

Viewing Images
^^^^^^^^^^^^^^

By default a height map is shown, when it is available inside the data file.
Other precalculated images can be displayed using the "Image" drop-down box. The
"Colormap" menu allows you to select from pre-defined colormaps. The
"logarithmic scale" checkbox can provide contrast when image
data varies over many orders of magnitude. Images can be flattened, offset, or
smoothed in the "Manipulations" window. The manipulated images are added to the
image menu with "Calc<Ext/Ret/Both><Manip>" where <Manip> is the selected operation
and <Ext/Ret/Both> indicates whether the parameter was estimated from the extend,
retract, or both data. The available image manipulations are:

Flatten
   A linear fit to each row of the image is subtracted from that row

PlaneFit
   A 2D linear fit to the image is subtracted from that image

Offset
   The minimum value present in the image is subtracted from that image

Median3x1
   Each pixel is replaced by the median value of that pixel and its vertical
   neighbors. Good for removing scanline artifacts.

Median3x3
   Each pixel is replaced by the median value of that pixel and its eight
   neighbors. Good for removing extreme outlier pixels.

Gauss3x3
   Blurs the image with a small Gaussian kernel. Good for random (pixel-wise)
   noise reduction via spatial averaging.

FillNaNs
   If the fitter was unsuccessful at a certain point, it will write NaN values
   into those pixels so they appear bright red in the figure. This fills in
   those pixels selectively with the median of their non-NaN neighbors. Works
   best when bad fits are sparse!

All calculated images can be exported by clicking "Export calculated maps" to various
image and data formats. The current preprocessing and fit parameters will be written
as JSON in the same folder.

Viewing Force Curves
^^^^^^^^^^^^^^^^^^^^

Force curves are displayed by left-clicking the image in the data window.
Shift+click allows multiple curves to be plotted. Ctrl+drag plots
continuously as the mouse moves over the image. A cross
is displayed over the selected point/pixel and the plot is displayed in the
adjacent axes with the extend and retract curves in blue and orange,
respectively. The data are in absolute units, as recorded in the raw data,
without any offsets/shifts. This view provides a quick qualitative check on a
force curve.

The "Force curve display" can be toggled between spatial (d vs z) temporal (d vs t)
and natural (f vs δ) units. "Select data source" appears if we detect that the file
contains Trace and or Retrace data, so you can select which curves to display and fit.
The "Preprocessing" parameters are read from the data file metadata but can be
adjusted on the fly, updating the display immediately. "Deflection Sens." refers to
the calibration factor that multiplies the static vertical photodetector signal to
obtain the cantilever deflection in nm (sometimes called InvOLS.) "Spring Constant"
refers to the static cantilever spring constant measured at the position of the probe
tip. "Sync Distance" is only available when dealing with QNM data, and phase-corrects
the position of the peak force with respect to time and z position.

Fitting Data
^^^^^^^^^^^^

Fitting can be toggled between the default nothing (Skip), the approach curve (Extend) or
the retract curve (Retract), or simultaneously fit the extend and retract curves (Both).
The fit parameters are not read from the file and
only affect the display when either the extend or the retract portions of the
force curve are toggled to fit. "Tip Radius (nm)" refers to the nominal radius
of the parabolic probe assumed in the indentation model. "DMT-JKR (0-1)" refers
to the transition parameter between the long-range and short-range adhesion
force regimes. Formally, it is the ratio of the short-range work of adhesion to
the total work of adhesion (τ1*τ1 in [SCHWARZ]_).

The deflection and piezo displacement of all currently displayed force curves can
be exported by clicking "Export calculated force curves" to various text and binary formats.

If a fit has been performed, a table is displayed above the force curve indicating
the key inferred parameters:

M
    indentation modulus M=4/3*E/(1-ν*ν)

dM/dk x k/M
    relative sensitivity of M to the spring constant

F_adh
    force of adhesion

d
    cantilever deflection from the maximum to the snap-off minimum

δ
    probe indentation depth from the maximum to the snap-off minimum

d/δ
    indentation ratio

a_c
    contact radius at the maximum indentation depth

SSE
    sum of squared errors

Using this table you observe the best fit value and uncertainty for parameters
at any point in the map. Mainly, this helps diagnose issues and confirm robust
fits. If you select multiple points, the average of the values of those points
will be displayed. Note that the current calculation assumes you are using the GCI/GetReal/Qf1.3
calibration method, as is current best practice. If you are doing hard-contact +
thermal calibration, you must approximately double the relative sensitivity value.
For calibrations that do not involve the equipartition theorem, the sensitivity
value reported is not applicable.

Additionally, fitting plots a curve labeled "Model" for the best-fit estimate.
If viewing in d vs z mode, "Surface Z" indicates the apparent height of the
substrate after accounting for indentation effects. If viewing in f vs δ mode,
Max/Crit markers indicate the apparent point of the "Maximum" and "Critical"
(snap-off) force and indentation, respectively.

The "calculate properties" button rapidly fits all data in the file and
creates new images for each in the "Image" menu. All calculated property maps can
be exported like any other image by clicking "Export calculated maps". Again, The
current preprocessing and fit parameters will be written as JSON in the same folder.

.. TODO: establish if you are in the magic ratio regime

Future Plans:

- Test suite and CI

- Viscoelastic model

- CLI for batch fit

API
---
:code:`magic_afm` can be imported and used, especially the submodules :code:`data_readers` and
:code:`calculation`.

.. TODO: This section will list the function names, arguments, results, exceptions and
   side effects. Possibly generated from docstrings?

Contributing
------------
If you notice any bugs, need any help, or want to contribute any code,
GitHub issues and pull requests are very welcome!

If you are reporting a crash, please include the traceback dump that is written
in the source or PyInstaller folder.
