Biomechanical filtering supports efficient tactile encoding in the human hand

Biomechanical filtering supports efficient tactile encoding in the human hand Zenodo Repository Documentation Version 1.1.0 Neeli Tummala ([email protected]) December 27, 2025 1 Introduction This repository contains the data and code used to produce the results in the publication "Biomechanical filtering supports efficient tactile encoding in the human hand." If you use these data or code, please cite our publication and the publication presenting Touchsim: N. Tummala, G. Reardon, B. Dandu, Y. Shao, H. P. Saal, and Y. Visell, Biomechanical filtering supports efficient tactile encoding in the human hand. bioRxiv, 2024. doi: 10.1101/2023.11.10.565040 H. P. Saal, B. P. Delhaye, B. C. Rayhaun, and S. J. Bensmaia. (2017). Simulating tactile signals from the whole hand with millisecond precision. Proceedings of the National Academy of Sciences, 114(28), E5693–E5702, 2017. doi: 10.1073/pnas.1704856114 The original Python implementation of Touchsim, of which a modified version is included in this repository, is located here: https://github.com/hsaal/touchsim. 2 Setup 2.1 Python environment This repository has been tested on Python 3.9. To set up the correct Python environment, use the env.yml file, which contains most of the required packages. The only packages not included there is the touchsim package and the matlab.engine package. 2.1.1 touchsim package The touchsim package can be downloaded from here. The version of touchsim that the code was tested on is already included in this repository in the touchsim folder, but if a more up-to-date version is released, it needs to be re-downloaded. However, I have made some modifications to the touchsim code, such as removing amplitude decay of oscillations with skin depth. If the repository is re-downloaded, the modifications should be replicated. The surfaces folder and setup.py file are also requirements of the touchsim package. 1 2.1.2 MATLAB package Some of the Python code requires calls to MATLAB functions using the matlab.engine package. This package requires additional setup, which is summarized here. 2.2 MATLAB environment This repository has been tested on MATLAB R2024b. Before running any MATLAB code, run PathSetup.m from the main folder to set up the correct paths. All of the MATLAB code should be run from the main folder. 3 MATLAB Dataset 3.1 impulseResponseData.mat This is a struct that contains the main impulse response data used to generate the majority of the results in the paper. The first layer of fields in the struct correspond to one participant and stimulus location. They are named by “<participant identifier>_<stimulus location>" (e.g., “P1_DPII” or “P5_PPII”). The second layer of fields are as follows: •adjMatrix_px : 2D array recording distances from the points on the boundary of the 2D hand surface to the measurement locations. Size is <no. of boundary points> x <no. of measurement locations> and units are in pixels. Element ij is the distance in pixel space between boundary point i and measurement location j . An element is NaN if the distance between the boundary point and measurement location is more than 200 pixels. This adjacency matrix is used when extrapolating data outside the convex hull bounded by the measurement locations. •botLoc_mm and topLoc_mm : X and Y coordinates of the bottom and top points, respectively, of a line segment going from the tip of the stimulated digit to the bottom of the hand in units of millimeters. Helpful for plotting. •digitBoundary_px : 2D array containing coordinates of the stimulated digit boundary in 2D pixel space. Units are in pixels. •digitAxisBoundary_px : 2D array containing coordinates of the boudary encompassing the axis of the stimulated digit from the fingertip to the bottom of the hand in 2D pixel space. Units are in pixels. Helpful for plotting. 2 •fingertipsBoundary_px : Cell array containing 5 elements, each corresponding to one fingertip. Each element is a 2D array containing coordinates of the boundary of a fingertip in 2D pixel space. Units are in pixels. •fs_Hz: Sampling frequency of impulseResponses_vel in units of Hz. •glabrous_bool : 2D boolean matrix. Each element represents a pixel in 2D pixel space. The element is 1 if the pixel is within the 2D surface that encompasses the glabrous skin. •glabrousBoundary_px : 2D array containing coordinates of the glabrous skin boundary in 2D pixel space. Corresponds to glabrous_bool . Units are in pixels. •impulseResponses_vel: 2D array of processed impulse responses in units of m/s. Each row corresponds to a measurement location. Size: <no. of measurement locations> x <no. of timesteps>. •loc : Stimulus location (“DPII” - tip of distal phalanx of digit II; “DPIII” - tip of distal phalanx of digit III; “IPII” - side of intermediate phalanx of digit II; or “PPII” - side of proximal phalanx of digit II). •measCoords_mm : 2D coordinates of measurement locations on 2D hand surface. In units of millimeters. •mmPerPixel : Scaling factor to convert from image (pixel) space to actual measurements in millimeters. •palmBoundary_px : 2D array containing coordinates of the boundary of the palm in 2D pixel space. Units are in pixels. •participant: Participant identifier (“P1” - “P7”). •pcCoords_mm : 2D array of 2D coordinates for each PC in the population. Size is <no. of PCs> x 2. Units are in millimeters. In the Python code, the random seed used to generate the PC locations is 0. •pcDists_mm : Array of distances between each PC in the population and the stimulus location. Units are in millimeters. •pcImpulseResponses_vel : 2D array of processed impulse responses interpolated to all PC locations ( pcCoords_mm ) in units of m/s. Each row corresponds to a PC location. Size: <no. of PCs> x <no. of timesteps>. 3 •pcModels : Array of PC model numbers corresponding to each PC in the population. The model numbers are from 0-3 and they correspond to the PC model number in the touchsim package. The models were assigned randomly to each PC with a random seed of 1. •stimLoc_mm : X and Y coordinates of the stimulus location on the 2D hand surface in units of millimeters. •surface_bool : 2D boolean matrix. Each element represents a pixel in 2D pixel space. The element is 1 if the pixel is within the 2D hand surface that encompasses all of the measurement locations. •surfaceBoundary_px : 2D array containing coordinates of the boundary of the hand surface that encompasses all of the measurement locations in 2D pixel space. Corresponds to surface_bool. Units are in pixels. 3.2 sinusoidData.mat This is a struct that contains the windowed sinusoid data used to generate Supplementary Figures 2 and 3 in the paper. The first layer of fields in the struct correspond to one participant and stimulus location. They are named by "<participant identifier>_<stimulus location>" (e.g., “P1_DPIIsine” or “P5_DPIIsine”). The second layer of fields are as follows: •adjMatrix_px : 2D array recording distances from the points on the boundary of the 2D hand surface to the measurement locations. Size is <no. of boundary points> x <no. of measurement locations> and units are in pixels. Element ij is the distance in pixel space between boundary point i and measurement location j . An element is NaN if the distance between the boundary point and measurement location is more than 200 pixels. This adjacency matrix is used when extrapolating data outside the convex hull bounded by the measurement locations. Units are in pixels. •freqs_Hz : Array of stimulus frequencies corresponding to the elements in ldvData_vel . The frequencies are 20, 40, 80, 120, 160, 200, 240, 280, 320, 360, 400, 440, 480, 520, 560, 600, and 640 Hz. •fs_Hz: Sampling frequency of ldvData_vel in units of Hz. •glabrous_bool : 2D boolean matrix. Each element represents a pixel in 2D pixel space. The element is 1 if the pixel is within the 2D surface that encompasses the glabrous skin. 4 •glabrousBoundary_px : 2D array containing coordinates of the glabrous skin boundary in 2D pixel space. Corresponds to glabrous_bool . Units are in pixels. •ldvData_vel : Cell array containing processed LDV data measured during the application of windowed sinusoid stimuli. Each element of the cell array corresponds to one stimulus frequency. The stimulus frequencies correspond to those in freqs_Hz . Each element of the cell array is of size <no. of measurement locations> x <no. of time steps>. The units are in m/s. •loc : Stimulus location (“DPIIsine” - tip of distal phalanx of digit II, sinusoid stimulus.). •measCoords_mm : 2D coordinates of measurement locations on 2D hand surface. In units of millimeters. •mmPerPixel : Scaling factor to convert from image (pixel) space to actual measurements in millimeters. •participant: Participant identifier (“P1” - “P7”). •ref_V : Cell array containing input voltage signal corresponding to measured data in ldvData_vel . Each element of the cell array corresponds to one stimulus frequency. The stimulus frequencies correspond to those in freqs_Hz . The units are in V. •surface_bool : 2D boolean matrix. Each element represents a pixel in 2D pixel space. The element is 1 if the pixel is within the 2D hand surface that encompasses all of the measurement locations. •surfaceBoundary_px : 2D array containing coordinates in of the boundary of the hand surface that encompasses all of the measurement locations in 2D pixel space. Corresponds to surface_bool. Units are in pixels. 3.3 impulseResponseCaptures.mat This is a struct that contains the individual impulse response captures used to generate Supplementary Figure 14 in the paper. The first layer of fields in the struct correspond to one participant and stimulus location. They are named by “<participant identifier>_<stimulus location>" (e.g., “P1_DPII” or “P5_PPII”). The second layer of fields are as follows: 5 •fs_Hz : Sampling frequency of impulseResponseCaptures_vel in units of Hz. •impulseResponseCaptures_vel : 3D array of impulse response captures in units of m/s. Each capture has been bandpass filtered (20-1000 Hz). Size: <no. of measurement locations> x <no. of timesteps> x <no. of captures>. •loc : Stimulus location (“DPII” - tip of distal phalanx of digit II; “DPIII” - tip of distal phalanx of digit III; “IPII” - side of intermediate phalanx of digit II; or “PPII” - side of proximal phalanx of digit II). •participant: Participant identifier (“P1” - “P7”). 4 CSV Dataset The above data are also provided in CSV format in the data/csv folder. Data from impulseResponseData.mat are located in data/csv/impulseResponseData, data from sinusoidData.mat in data/csv/sinusoidData, and data from impulseResponseCaptures.mat in data/csv/impulseResponseCaptures. Within each of these folders, data for each combination of participant and stimulus location are stored in a separate subfolder, named by “<participant identifier>_<stimulus location>" (e.g., “P1_DPII” or “P5_PPII”). Within each subfolder, each field of the original MATLAB struct is saved as its own CSV file. For cell arrays (e.g., fingertipsBoundary_px ), each element of the cell array is saved in a separate CSV file, with the element index included in the filename. For 3D arrays (e.g., impulseResponseCaptures_vel ), each capture (containing all measurement locations and time samples) is saved in its own CSV file, with the capture number included in the filename. Each subfolder also contains a README file that specifies the size of the data in each CSV file. 5 Code The figs folder contains the code necessary to recreate all figures in the paper. The folders are organized by figure, with supplemental figures in the suppfigs folder. The scripts in each folder are named by the subfigure that they generate data or plots for. In all cases, the Python scripts must be run before the MATLAB script since they generate the data required for plotting. Each figure folder also contains a text document with parameters used, such as the participant identifier and stimulus location. The text document also contains the names of the scripts 6 needed to generate the data and plots for each subfigure as well as the order in which they need to be run. 7