pyIMD tutorial with user interface¶
Before starting, make sure pyIMD is installed
This tutorial provides a simple example with a test dataset, teaching step by step how to:
- create a pyIMD project
- calculate the mass form the measured data
The layout of the following windows and the paths are set for windows and might differ for Mac or Unix. First, lets have a look at the input data. The typical data set consists of 3 files: 1) a sweep file of the cantilever WITHOUT cell (text file with multi-line header) 2) a sweep file of the cantilever WITH cell (text file with multi-line header) and 3) the actual (long-term) measurement file, which is either a text file or TDMS file (lab-view specific file type). A typical time resolution is 10 ms for the data acquisition so these files can be quite large. Fig. 1 visualizes the data input which can be found as example data set for download and testing.
The example pyIMD script section demonstrates how a pyIMD project is created on the console:
from pyIMD.imd import InertialMassDetermination
# Create the inertial mass determination object
imd = InertialMassDetermination()
# Create a config file for the project / experiment to analyze using default values. Note non default parameters can be
# added as optional arguments for e.g. cell_position = 9.5.
file_path1 = "/pyIMD/examples/data/show_case/0190110_ShowCase_PLL_B.txt"
file_path2 = "/pyIMD/examples/data/show_case/20190110_ShowCase_PLL_A.txt"
file_path3 = "/pyIMD/examples/data/show_case/20190110_ShowCase_PLL_LongTerm.txt"
imd.create_pyimd_project(file_path1, file_path2, file_path3, '\t', 23, 'PLL', figure_width=16.5, figure_height=20,
initial_parameter_guess=[60.0, 2.0, 0.0, 0.0], cell_position=9.5, figure_format='pdf')
When using pyIMD through its user interface (UI) in the stand alone mode, the pyIMD project is created in exact the same way in the background. Yet, the user does not need to take care to type the paths or arguments correctly as all the input entered trough the UI will be validated automatically. Fig. 2 shows the main window and the settings window of the pyIMD application. A new pyIMD project is created by selecting the three data files required for the calculation from a directory (3). Next, it needs to be declared which measurement each file contains and what the measurement mode is (5). Using the menu (1), opens the settings dialog and lets you determine all project related parameters such as the names of the output figures. After all settings are set, the mass calculation is started with (6).
The tools menu in Fig. 2 (7) allows for data concatenation from multiple files into a single one, in case the data was acquired with the Nanonis data logger. The resulting file can then be loaded as mentioned above along with the before and after cell attachment file.
# Run the inertial mass determination
imd.run_inertial_mass_determination()
The console (8) logs all actions performed with the UI and indicates when all calculations are done. The results can be viewed in the results tab (2), where as all the output figures are listed as well as the data can be inspected.
The first output created by pyIMD are control figures visualizing the fit of the cantilevers phase response is shown for the case with and without cell (Fig. 3). The shift towards lower frequencies can be clearly seen, when the cell is attached. Moreover, the Q-factor changes and therefore the slope of the response curve. If the fits are not fitting the raw data the parameter ‘initial_parameter_guess’, ‘lower_parameter_bounds’, ‘upper_parameter_bounds’ need to be adjusted in the settings dialog.
The analysis output by the software is shown in Fig. 4, the exemplary data for a mammalian cell is provided for download. The evolution of mass vs time is shown for a time span of 20 min. The mass data was acquired every 10 ms (data shown in black), overlaid in red is the rolling mean with a window of 1000 (adjustable parameter ‘rolling_window_size’). Images taken every 3 min over the observed time span, we see on average a steady increase of the cell mass, the spring constant is 8 N/m (adjustable parameter ‘sprint_constant’). The position of the cell projected along the long axis of the cantilever was 9.5 um (adjustable parameter, ‘cell_position’) and did not change, which is of importance for the current use of the software.
The project can either be re-run with different parameters, to i.e. improve the function fits or be saved using the menu (Fig. 2, (1)).
# save a pyIMD project
imd.save_pyimd_project("/pyIMD/examples/data/show_case/pyIMDShowCaseProject.xml")
A previously saved project can be loaded again at a later time from the menu (Fig. 2, (1))or also from the command line without the user interface:
# load a pyIMD project
imd.load_pyimd_project("/pyIMD/examples/data/show_case/pyIMDShowCaseProject.xml")