# PySSPFM
<p align="center" width="100%">
<img align="center" width="70%" src=https://cea-metrocarac.github.io/pysspfm/circular_diagram.png>
<br>
</p>
<p align="justify" width="100%">
<strong>PySSFPM</strong> is a specific tool developed in
<strong>Py</strong>thon dedicated to perform data analysis on <strong>SSPFM</strong> (Switching Spectroscopy Piezoresponse Force Microscopy) measurements with a GUI that aims to be as simple to use as possible and complete to accommodate the user's measurement requirements and conditions. The source code was developed to be easily customizable in order to meet the user's specific needs. Measurements can be processed in both standard SSPFM including fixed-frequency measurements on or off resonance, or with frequency sweeping to reconstruct the resonance peak, as well as SSPFM-DFRT (Dual Frequency Resonance Tracking) mode.
</p>
## Important
<p align="justify" width="100%">
This library is provided in its current state and remains under active development. The motivation behind the creation of the new PySSPFM application for SSPFM measurement processing stemmed from several factors :
</p>
<p align="justify" width="100%">
• There was a desire to offer the scientific community in the PFM domain an open-source solution that is easily comprehensible, adaptable, and customizable according to individual requirements. All developments adhere to the PEP-8 development standard and are accompanied by comprehensive, internal script documentation.
</p>
<p align="justify" width="100%">
• PySSPFM has been developed with the aim of achieving the most quantitative and advanced measurement processing compared to other existing solutions.
</p>
<p align="justify" width="100%">
However, while it has shown reliable performance with the data used by the library's developer, it's crucial to emphasize that there are no assurances that this library will seamlessly process your unique data. Moreover, it should be noted that in order to extract data from a Bruker SPM file, DLL (Dynamic Link Library) files must be installed alongside the Nanoscope Analysis software (Bruker).
</p>
<p align="justify" width="100%">
If you encounter any bugs or issues, you can kindly bring them to the developer's attention by visiting: <a href="https://github.com/CEA-MetroCarac/PySSPFM/issues">PySSPFM issues</a>.
</p>
## Overview
<p align="center" width="100%">
<img align="center" width=80%" src=https://cea-metrocarac.github.io/pysspfm/scheme_workflow_pysspfm.PNG> <br>
<em>PySSPFM workflow</em>
</p>
### 0) Measures
<p align="justify" width="100%">
PySSPFM facilitates the processing of a set of SSPFM measurement data points by simply populating a measurement form (template for: <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/resources/measurement%20sheet%20model%20SSPFM.csv">measurement sheet model SSPFM</a>). The range of measurement files to be processed may have the extensions: <br>
• <code>.spm</code> (Bruker) <br>
• <code>.txt</code> <br>
• <code>.csv</code> <br>
• <code>.xlsx</code> <br>
</p>
### 1) First step of data analysis
<p align="justify" width="100%">
For each of the SSPFM measurement files, amplitude and phase are extracted for each segment using a user-selected method: <br>
• <code>max</code>: extract maximum or resonance peak (for frequency sweep mode) <br>
• <code>fit</code>: perform a fit of the resonance peak based on SHO (Simple Harmonic Oscillator) model (for frequency sweep mode) <br>
• <code>single_freq</code>: mean of the segment (for single frequency mode, in or out of resonance, and for DFRT mode without sidebands processing) <br>
• <code>dfrt</code>: mean of the segment (for DFRT mode with sidebands processing: if errors occur, use the <code>single_freq</code> mode) <br>
</p>
### 2) Second step of data analysis
<p align="justify" width="100%">
The measurements are then automatically calibrated, and the piezoresponse hysteresis is created. It is subsequently fitted using an algorithm based on the <a href="https://pypi.org/project/lmfit/">lmfit</a> library, and the piezoelectric and ferroelectric properties are extracted. Five different artifact decorrelation protocols (quadratic components: electrostatic, electrostrictive, and joules effects) allow for obtaining quantitative piezoelectric and ferroelectric measurements and for acquiring a more comprehensive understanding of material properties, such as the contact surface potential.
</p>
### 3) Mapping
<p align="justify" width="100%">
Once the processing is complete for all the files, maps are generated. 2D interpolation tools and masks to mitigate the influence of problematic pixels are also available.
</p>
### 4) Toolbox
<p align="justify" width="100%">
Finally, a toolbox is provided for the analysis of processing results: it
includes algorithms of:
</p>
<p align="justify" width="100%">
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/curve_clustering.py">Machine learning (K-Means, GMM, PCA)</a> <br>
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/mean_hyst.py">Phase separation</a> <br>
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/map_correlation.py">Mapping cross-correlation</a> <br>
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/spm_converter.py">SPM file converter</a> <br>
• ...
</p>
<p align="justify" width="100%">
See the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/doc">documentation</a> for more details on PySSPFM workflow.
</p>
## Usage
<p align="center" width="100%">
<img align="center" width="15%" src=https://cea-metrocarac.github.io/pysspfm/gui_main.PNG> <br>
<em>PySSPFM GUI main window</em>
</p>
<p align="justify" width="100%">
All code executed and parameter adjustments made through the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/gui">GUI</a> can be replicated in executable scripts: <br>
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/data_processing">Data Processing</a> <br>
• <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/toolbox">Toolbox</a> <br>
Then, the user can adjust parameters directly either in a pre-filled JSON file, in a TOML file, or in the executable Python code. The JSON and TOML files, which manage the global settings of PySSPFM as well as the parameters specific to each executable script, are stored in a <code>.pysspfm</code> folder located in the user's C drive (e.g., <code>C:\Users\HV265662.pysspfm</code>). This folder is created during the PySSPFM installation process, detailed in the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main?tab=readme-ov-file#installation">PySSPFM Overview</a> file. It is possible to run the <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/post_install.py">post_install.py</a> script (via a terminal, console, etc.) to regenerate it. These files are also available in the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources">resources</a> folder, distributed across the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources/data_processing">resources/data_processing</a> and <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources/toolbox">resources/toolbox</a> directories.
</p>
<p align="justify" width="100%">
You can check the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/examples">examples</a> (based on both real and simulated SSPFM measurements) to grasp the utilization of the scripts, and the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/tests">tests</a> to ensure the proper functioning of the scripts. The examples and tests follow the same directory structure as the main PySSPFM scripts.
</p>
<p align="justify" width="100%">
See the <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/doc">documentation</a> for more details on PySSPFM usage.
</p>
## Installation
### From PyPI
```bash
pip install PySSPFM
```
### From GitHub
#### With poetry
```bash
poetry add git+https://github.com/CEA-MetroCarac/PySSPFM.git
```
#### With pip
```bash
pip install git+https://github.com/CEA-MetroCarac/PySSPFM.git
```
### Create the Settings and Parameters Folder
<p align="justify" width="100%">
The settings and parameters folder (containing files with .json and .toml extensions) is automatically created during installation. To regenerate it, run the <a href="https://github.com/CEA-MetroCarac/PySSPFM/blob/main/post_install.py">post_install.py</a> script (via a terminal, console, etc.) after installation.
</p>
### Optional dependencies
<p align="justify" width="100%">
• <a href="https://pypi.org/project/pytest/">pytest</a> to run <a href="https://github.com/CEA-MetroCarac/PySSPFM/tree/main/tests">tests</a> python files. <br>
• <a href="https://pypi.org/project/toml/">toml</a> to load user parameters directly from toml file, for excecutable python script. <br>
• Nanoscope Analysis software (Bruker) installed on computer to extract data from SSPFM Bruker measurement files (spm extension).
</p>
## Citing
<p align="justify" width="100%">
In the case you use this library for your work, please think about citing it: <br>
• H. Valloire, P. Quéméré, N. Vaxelaire, H. Kuentz, G. Le Rhun, Ł. Borowik, "Enhancing ferroelectric characterization at nanoscale: A comprehensive approach for data processing in spectroscopic piezoresponse force microscopy", J. Appl. Phys, 21 May 2024, 135 (19): 194101, DOI: <a href="https://doi.org/10.1063/5.0197226">https://doi.org/10.1063/5.0197226</a> <br>
• Hugo Valloire, Patrick Quéméré, 2024, November 22, PySSPFM (Version 2024.11).
</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/CEA-MetroCarac/PySSPFM",
"name": "PySSPFM",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "PySSPFM, SS-PFM, C-KPFM, switching-spectroscopy, PFM, AFM, piezoelectric, ferroelectric, image, hysteresis, nano-loop, piezoresponse, bruker, datacube, spm, python, python-library, data-processing, machine-learning, k-means, cross-correlation",
"author": "Hugo Valloire, Patrick Quemere",
"author_email": "\"Hugo Valloire, Patrick Quemere\" <hugovalloire@gmail.com>",
"download_url": null,
"platform": null,
"description": "# PySSPFM\n\n<p align=\"center\" width=\"100%\">\n <img align=\"center\" width=\"70%\" src=https://cea-metrocarac.github.io/pysspfm/circular_diagram.png>\n <br>\n</p>\n\n<p align=\"justify\" width=\"100%\"> \n<strong>PySSFPM</strong> is a specific tool developed in \n<strong>Py</strong>thon dedicated to perform data analysis on <strong>SSPFM</strong> (Switching Spectroscopy Piezoresponse Force Microscopy) measurements with a GUI that aims to be as simple to use as possible and complete to accommodate the user's measurement requirements and conditions. The source code was developed to be easily customizable in order to meet the user's specific needs. Measurements can be processed in both standard SSPFM including fixed-frequency measurements on or off resonance, or with frequency sweeping to reconstruct the resonance peak, as well as SSPFM-DFRT (Dual Frequency Resonance Tracking) mode.\n</p>\n\n## Important\n\n<p align=\"justify\" width=\"100%\">\nThis library is provided in its current state and remains under active development. The motivation behind the creation of the new PySSPFM application for SSPFM measurement processing stemmed from several factors : \n</p>\n\n<p align=\"justify\" width=\"100%\">\n• There was a desire to offer the scientific community in the PFM domain an open-source solution that is easily comprehensible, adaptable, and customizable according to individual requirements. All developments adhere to the PEP-8 development standard and are accompanied by comprehensive, internal script documentation.\n</p>\n\n<p align=\"justify\" width=\"100%\">\n• PySSPFM has been developed with the aim of achieving the most quantitative and advanced measurement processing compared to other existing solutions.\n</p>\n\n<p align=\"justify\" width=\"100%\">\nHowever, while it has shown reliable performance with the data used by the library's developer, it's crucial to emphasize that there are no assurances that this library will seamlessly process your unique data. Moreover, it should be noted that in order to extract data from a Bruker SPM file, DLL (Dynamic Link Library) files must be installed alongside the Nanoscope Analysis software (Bruker).\n</p>\n\n<p align=\"justify\" width=\"100%\">\nIf you encounter any bugs or issues, you can kindly bring them to the developer's attention by visiting: <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/issues\">PySSPFM issues</a>.\n</p>\n\n## Overview\n\n<p align=\"center\" width=\"100%\">\n <img align=\"center\" width=80%\" src=https://cea-metrocarac.github.io/pysspfm/scheme_workflow_pysspfm.PNG> <br>\n <em>PySSPFM workflow</em>\n</p>\n\n### 0) Measures\n<p align=\"justify\" width=\"100%\">\nPySSPFM facilitates the processing of a set of SSPFM measurement data points by simply populating a measurement form (template for: <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/resources/measurement%20sheet%20model%20SSPFM.csv\">measurement sheet model SSPFM</a>). The range of measurement files to be processed may have the extensions: <br>\n• <code>.spm</code> (Bruker) <br>\n• <code>.txt</code> <br>\n• <code>.csv</code> <br>\n• <code>.xlsx</code> <br>\n</p>\n\n### 1) First step of data analysis\n<p align=\"justify\" width=\"100%\">\nFor each of the SSPFM measurement files, amplitude and phase are extracted for each segment using a user-selected method: <br>\n• <code>max</code>: extract maximum or resonance peak (for frequency sweep mode) <br>\n• <code>fit</code>: perform a fit of the resonance peak based on SHO (Simple Harmonic Oscillator) model (for frequency sweep mode) <br>\n• <code>single_freq</code>: mean of the segment (for single frequency mode, in or out of resonance, and for DFRT mode without sidebands processing) <br>\n• <code>dfrt</code>: mean of the segment (for DFRT mode with sidebands processing: if errors occur, use the <code>single_freq</code> mode) <br>\n</p>\n\n### 2) Second step of data analysis\n<p align=\"justify\" width=\"100%\">\nThe measurements are then automatically calibrated, and the piezoresponse hysteresis is created. It is subsequently fitted using an algorithm based on the <a href=\"https://pypi.org/project/lmfit/\">lmfit</a> library, and the piezoelectric and ferroelectric properties are extracted. Five different artifact decorrelation protocols (quadratic components: electrostatic, electrostrictive, and joules effects) allow for obtaining quantitative piezoelectric and ferroelectric measurements and for acquiring a more comprehensive understanding of material properties, such as the contact surface potential.\n</p>\n\n### 3) Mapping\n<p align=\"justify\" width=\"100%\">\nOnce the processing is complete for all the files, maps are generated. 2D interpolation tools and masks to mitigate the influence of problematic pixels are also available.\n</p>\n\n### 4) Toolbox\n<p align=\"justify\" width=\"100%\">\nFinally, a toolbox is provided for the analysis of processing results: it \nincludes algorithms of:\n</p>\n\n<p align=\"justify\" width=\"100%\">\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/curve_clustering.py\">Machine learning (K-Means, GMM, PCA)</a> <br>\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/mean_hyst.py\">Phase separation</a> <br>\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/map_correlation.py\">Mapping cross-correlation</a> <br>\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/PySSPFM/toolbox/spm_converter.py\">SPM file converter</a> <br>\n• ...\n</p>\n\n<p align=\"justify\" width=\"100%\">\nSee the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/doc\">documentation</a> for more details on PySSPFM workflow.\n</p>\n\n## Usage\n\n<p align=\"center\" width=\"100%\">\n <img align=\"center\" width=\"15%\" src=https://cea-metrocarac.github.io/pysspfm/gui_main.PNG> <br>\n <em>PySSPFM GUI main window</em>\n</p>\n\n<p align=\"justify\" width=\"100%\">\nAll code executed and parameter adjustments made through the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/gui\">GUI</a> can be replicated in executable scripts: <br>\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/data_processing\">Data Processing</a> <br>\n• <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/PySSPFM/toolbox\">Toolbox</a> <br>\nThen, the user can adjust parameters directly either in a pre-filled JSON file, in a TOML file, or in the executable Python code. The JSON and TOML files, which manage the global settings of PySSPFM as well as the parameters specific to each executable script, are stored in a <code>.pysspfm</code> folder located in the user's C drive (e.g., <code>C:\\Users\\HV265662.pysspfm</code>). This folder is created during the PySSPFM installation process, detailed in the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main?tab=readme-ov-file#installation\">PySSPFM Overview</a> file. It is possible to run the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/post_install.py\">post_install.py</a> script (via a terminal, console, etc.) to regenerate it. These files are also available in the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources\">resources</a> folder, distributed across the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources/data_processing\">resources/data_processing</a> and <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/resources/toolbox\">resources/toolbox</a> directories.\n</p>\n\n<p align=\"justify\" width=\"100%\">\nYou can check the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/examples\">examples</a> (based on both real and simulated SSPFM measurements) to grasp the utilization of the scripts, and the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/tests\">tests</a> to ensure the proper functioning of the scripts. The examples and tests follow the same directory structure as the main PySSPFM scripts.\n</p>\n\n<p align=\"justify\" width=\"100%\">\nSee the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/doc\">documentation</a> for more details on PySSPFM usage.\n</p>\n\n## Installation\n\n### From PyPI\n\n```bash\npip install PySSPFM\n```\n\n### From GitHub\n\n#### With poetry\n\n```bash\npoetry add git+https://github.com/CEA-MetroCarac/PySSPFM.git\n```\n\n#### With pip\n\n```bash\npip install git+https://github.com/CEA-MetroCarac/PySSPFM.git\n```\n\n### Create the Settings and Parameters Folder\n\n<p align=\"justify\" width=\"100%\">\nThe settings and parameters folder (containing files with .json and .toml extensions) is automatically created during installation. To regenerate it, run the <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/blob/main/post_install.py\">post_install.py</a> script (via a terminal, console, etc.) after installation.\n</p>\n\n### Optional dependencies\n\n<p align=\"justify\" width=\"100%\">\n• <a href=\"https://pypi.org/project/pytest/\">pytest</a> to run <a href=\"https://github.com/CEA-MetroCarac/PySSPFM/tree/main/tests\">tests</a> python files. <br>\n• <a href=\"https://pypi.org/project/toml/\">toml</a> to load user parameters directly from toml file, for excecutable python script. <br>\n• Nanoscope Analysis software (Bruker) installed on computer to extract data from SSPFM Bruker measurement files (spm extension).\n</p>\n\n## Citing\n\n<p align=\"justify\" width=\"100%\">\nIn the case you use this library for your work, please think about citing it: <br>\n• H. Valloire, P. Qu\u00e9m\u00e9r\u00e9, N. Vaxelaire, H. Kuentz, G. Le Rhun, \u0141. Borowik, \"Enhancing ferroelectric characterization at nanoscale: A comprehensive approach for data processing in spectroscopic piezoresponse force microscopy\", J. Appl. Phys, 21 May 2024, 135 (19): 194101, DOI: <a href=\"https://doi.org/10.1063/5.0197226\">https://doi.org/10.1063/5.0197226</a> <br>\n• Hugo Valloire, Patrick Qu\u00e9m\u00e9r\u00e9, 2024, November 22, PySSPFM (Version 2024.11).\n</p>\n\n",
"bugtrack_url": null,
"license": "GPL v3",
"summary": "PySSPFM: A specialized tool for Switching Spectroscopy Piezoresponse Force Microscopy (SSPFM) data processing",
"version": "2024.11",
"project_urls": {
"Documentation": "https://github.com/CEA-MetroCarac/PySSPFM/tree/main/doc",
"Homepage": "https://github.com/CEA-MetroCarac/PySSPFM"
},
"split_keywords": [
"pysspfm",
" ss-pfm",
" c-kpfm",
" switching-spectroscopy",
" pfm",
" afm",
" piezoelectric",
" ferroelectric",
" image",
" hysteresis",
" nano-loop",
" piezoresponse",
" bruker",
" datacube",
" spm",
" python",
" python-library",
" data-processing",
" machine-learning",
" k-means",
" cross-correlation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "67c72bee7f2e67f262a57ee25ce0f7a5fd5b5ad69e3060a4b337411411f9ddf9",
"md5": "88d572774afc79daab6170f065836dd4",
"sha256": "c99b9c71ba93df196c28ec9245bc247714796f3761f49f11be6c68cddc63ed95"
},
"downloads": -1,
"filename": "PySSPFM-2024.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88d572774afc79daab6170f065836dd4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 344952,
"upload_time": "2024-11-27T16:01:24",
"upload_time_iso_8601": "2024-11-27T16:01:24.275607Z",
"url": "https://files.pythonhosted.org/packages/67/c7/2bee7f2e67f262a57ee25ce0f7a5fd5b5ad69e3060a4b337411411f9ddf9/PySSPFM-2024.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-27 16:01:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CEA-MetroCarac",
"github_project": "PySSPFM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysspfm"
}
JSON
