Project Overview

This repository contains the data, code and 3D models related to the research titled "A Mathematical Model to Predict Network Growth in Physarum polycephalum as a Function of Extracellular Matrix Viscosity, Measured by a Novel Viscometer". The repository includes raw and processed data from viscosity measurements, fractal dimension analysis and growth data. It also includes 3D models, technical drawings and Python scripts required to operate and analyse the viscometer system.

DOI: https://doi.org/10.5061/dryad.0k6djhb9m

Data Directory Overview

The dataset is organised into several main directories containing different aspects of the experimental data and necessary files for processing and analysis. Below is a brief overview of each directory:

1. GrowthFractalDimension.zip: This directory contains data and results related to the growth and fractal dimension of the Physarum polycephalum networks. It includes measurements of network growth over time and fractal dimension calculations, providing insights into the complexity and adaptability of the organism's network formation.
2. DensityViscosity.zip: This folder contains two main subdirectories for density and viscosity measurements. It includes raw data, processed results, images used for area and height determination and results related to the viscometer measurements.
3. Model-Files.zip: This directory contains the 3D printing files for the viscometer components, available in both STL and G-code formats. These files allow users to print the parts needed to assemble the viscometer or modify them for alternative setups. The G-code files are pre-sliced for use with the Prusa MK3S+ 3D printer.
4. TechnicalDrawings.zip: This directory includes detailed technical drawings and schematics for each component of the viscometer, as well as an overview of the fully assembled device. These drawings help replicate or modify the viscometer's design.
5. ViscometerDataProcessing.zip: This folder contains Python scripts and associated files required to process and analyse the viscometer's data. The scripts are designed to process the raw sensor data, calculate key measurements like viscosity and generate output results for further analysis. This folder is hosted by Zenodo and available here.
6. Viscometer.zip: This folder contains the core files and hardware setup for operating the custom-built viscometer. It includes Python scripts for controlling the measurement process, handling sensor data and managing communication with external hardware such as the Arduino microcontroller. It also contains all sensor-specific files for calibrating and recording the data. This folder is hosted by Zenodo and available here.

General Information on Samples, Terminology and File Handling

Sample Classification

The samples are organised into folders based on different experimental conditions and sample numbers. Each folder follows a straightforward naming convention to reflect the condition, concentration and sample number:

1. Condition: The first part of the folder name represents the experimental condition.
   • 00 stands for the control group (no additives).
   • 01 represents the MgCl2·6H2O (magnesium chloride) condition.
2. Concentration: The second part of the folder name represents the concentration of the added substance. For example:
   • 010 stands for 10 mM magnesium chloride.
   • 025 stands for 25 mM.
   • 100 stands for 100 mM.
   • The control group has 000 since no additive is included.
3. Sample Number: The third part indicates the sample number. For example:
   • 01 refers to the first sample.
   • 02 refers to the second sample, and so on.

Example Folder Name: A sample folder might have the name 01-025-03:

• 01: Represents the magnesium chloride condition.
• 025: Represents 25 mM magnesium chloride concentration.
• 03: Represents the third sample of that condition.

Folder Structure for Density and Viscosity Data

The dataset contains samples involving the Physarum polycephalum organism and its extracellular slime matrix (ECM). The samples are classified into two main categories. Note that this folder structure is relevant only for the Density and Viscosity results and not for the Growth or Fractal Dimension analysis:

1. ECM-Organism-Sample: These samples include the ECM and the Physarum polycephalum organism. These samples represent the entire network environment in which the organism operates.
2. ECM-Sample: These samples comprise only the isolated ECM. These are used specifically for measurements related to the ECM's properties, such as viscosity and density, without the influence of the organism itself.

File Handling

This dataset contains various file types, each requiring different software or tools for optimal use. Below is a brief guide on how to handle these file types:

1. CSV Files: These files store tabular data, such as sensor readings or measurement results. They can be opened and processed using Python (e.g., with the pandas library) or spreadsheet software like Microsoft Excel or Google Sheets. The first row typically represents column headers (e.g., time, value). Please note that all CSV files use a semicolon (;) as the separator instead of the standard comma.
2. SVG Files: These vector graphic files can be opened using Microsoft Edge, Inkscape, or any program that supports SVG format. They are used for plotting data in vector format, such as temperature or humidity measurements over time.
3. JPG/PNG Image Files: These image files contain pictures used for sample analysis, such as sampleArea.jpg and sampleHeight.jpg. They can be opened with image viewers (e.g., Windows Photos, Preview on Mac) or image analysis software like ImageJ for quantitative measurements (e.g., area calculation).
4. PY Files (.py): The dataset includes several Python scripts that process and analyse the collected data. These files are compatible and tested with Python 3.10.11.
5. PKL Files (.pkl): Pickle files store serialised Python objects, such as interpolation functions or processed data. To load and use these files in Python, use the following code:
   • import joblib
   • loadCellInterpolationFunction = joblib.load('LoadCellInterpolationFunction.pkl')
   • distanceInterpolationFunction = joblib.load('DistanceInterpolationFunction.pkl')
6. G-code Files: These files contain instructions for 3D printers (specific for Prusa MK3S+ 3D printer) on how to print the components of the viscometer. They can be loaded directly into the Prusa 3D printer interface or viewed with Prusa G-Code Viewer.
7. STL-Files: These files represent the 3D models of the viscometer components in STL format. They can be opened and modified using CAD software (e.g., OnShape, Autodesk Fusion 360). These can also be used to prepare files for 3D printing with other printers.
8. PDF-Files: The technical drawings for the viscometer components are saved in PDF format. These can be opened and viewed using Acrobat Reader, Microsoft Edge, or any other PDF viewer.

Raw Data Structure

GrowthFractalDimension.zip

This folder contains all results related to growth analysis and network complexity (fractality, measured through the fractal dimension). Within this folder, there are two subfolders:

1. FractalDimension: Contains data related to the fractal dimension analysis of the slime mould network.
2. Growth: Contains data related to the growth of the slime mould network over time.

Each of these subfolders follows the regular sample naming convention described earlier. The corresponding result file is within each sample folder.

Fractal Dimension Folder

FractalDimension.csv: This file contains time-related results for the fractal dimension analysis. The data is organised in rows, each corresponding to a timestep (every 60 seconds). The columns in the file are as follows:

1. Time: Time in seconds
2. Fractal Dimension: calculated fractal dimension value
3. Slope: the slope of the regression line from the box-counting method
4. R² (Coefficient of Determination): indicates how well the data fits the linear regression model
5. Intercept: the intercept of the regression line
6. StdError: the standard error of the regression, indicating uncertainty in the estimation

In the box-counting method for fractal dimension analysis, the relationship between the number of occupied boxes and the box size follows a predictable scaling pattern. A straight-line relationship is obtained by plotting the logarithm of the number of occupied boxes against the logarithm of the inverse box size, allowing key parameters to be extracted through linear regression. The fractal dimension is determined from the slope of this line, representing the complexity and space-filling nature of the structure. The absolute value of the slope corresponds to the fractal dimension in this context, describing how the number of occupied boxes changes with scale. The R² value (coefficient of determination) is used to assess how well the data follows a linear trend, with values close to 1 indicating strong correlation and reliable estimation. The intercept is included as a constant in the regression equation, reflecting the structure's overall scaling but not directly affecting the fractal dimension. Lastly, the standard error (StdError) measures uncertainty in the fractal dimension calculation, with lower values indicating greater precision and consistency.

Growth Folder

growthResults.csv: This file contains data on the network's growth over time. The data is organised in rows, each corresponding to a specific time point. The columns are as follows:

1. Time: time in minutes
2. Network Area: the network area at the given time point, measured in mm².

DensityViscosity.zip

This folder contains all results related to measuring physical properties, including density and viscosity. It is divided into two subfolders:

1. Density: Contains data related to density analysis.
2. Viscosity: Contains data related to viscosity analysis.

As explained earlier, these subfolders contain two main directories: ECM-Samples and ECM-Organism-Samples. The ECM-Organism-Sample includes the samples containing extracellular slime matrix and the Physarum polycephalum organism, representing the entire network environment in which the organism operates. The ECM-Sample includes only the isolated extracellular slime matrix, used for measurements related to the ECM's properties (viscosity and density) without the organism's influence.

The content of each directory follows the regular naming convention for samples, as described in the General Information on Samples, Terminology, and File Handling section above. Within each ECM-Sample or ECM-Organism-Sample folder, there are additional subfolders named according to the sample convention (e.g., 01-025-03), where the first part indicates the condition, the second part indicates the concentration (e.g., 025 for 25 mM magnesium chloride) and the third part represents the sample number.

Density Results

Within each sample folder in the Density directory, there are three files:

1. Results.csv: Contains 6 rows:
   • PxPerMM: The reference value for the number of pixels representing 1 mm.
   • Mass in kg: The weight of the sample in kilograms.
   • Height in m: The sample height in meters (measured between glass plates).
   • Area in m²: The area of the sample in square meters (calculated from the image).
   • Volume in m³: The sample volume in cubic meters (calculated as area × height).
   • Density in kg/m³: The calculated sample density (weight/volume).
2. sampleArea.jpg: An image captured by the Samsung Galaxy S24 Ultra (50 MP, 2.1x magnification). This image determines the sample area, which is crucial for calculating the volume.
3. sampleHeight.jpg: An image captured using the Keyence VHX-7000 digital microscope. It shows the distance between the glass plates, representing the sample height.

Viscosity Results

Within each Viscosity sample folder, there is a subfolder called ViscometerAnalysis, which includes the following files:

SVG Files:

• Temperature.svg: A vector plot representing the temperature measurements during the viscosity measurement process.
• Humidity.svg: A vector plot showing the humidity during the viscosity measurement.
• loadCellRaw.svg: A vector plot displaying the raw data from the load cell sensor (in grams).
• Force.svg: A vector plot of the load cell data recalculated into Force (in Newtons), where Force = mass × gravity (gravity = 9.81 m/s²).
• Distance.svg: A vector plot of the raw distance data from the distance sensor (in mm).
• Force_Distance.svg: A combined plot showing aligned measurements from the distance and load cell sensors.
• ForceDistance.svg: A refined plot showing the data with outliers removed. It also includes spline interpolation functions for both distance and force data. It marks the points used for the final viscosity calculation, including the force point and the distance segment used for speed measurement. Both are necessary for calculating the kinematic viscosity.

Interpolation Files:

• LoadCellInterpolationFunction.pkl & DistanceInterpolationFunction.pkl: These files contain the load cell and distance data interpolation functions, respectively.

CSV Files:

In addition to the vector graphics, several CSV files contain the data measurements:

• Ambient.csv: Contains results from the temperature-humidity sensor. The first column represents the time (in seconds from the measurement start), the second column contains temperature data (in °C) and the third column contains relative humidity data (in %).
• Distance.csv: Contains timepoint data from the distance sensor. The first column represents the time (in seconds from the measurement start) and the second column contains distance data (in meters).
• Force.csv: Contains timepoint data from the load cell sensor. The first column represents the time (in seconds from the measurement start) and the second column contains force data (in Newtons).
• LoadCell.csv: Similar to Force.csv, the second column contains the raw load cell data in grams before being recalculated into force.
• report.csv: Contains metadata and an overview of the measurement process. It includes the following information:
  • StartTime: UNIX timestamp indicating the start of the measurement.
  • EndTime: UNIX timestamp indicating the end of the measurement.
  • LoadCell data points: The number of data points recorded by the load cell.
  • Resultpath (LoadCell): The file path to the raw load cell data.
  • Ambient data points: The number of data points recorded by the ambient sensor.
  • Resultpath (Ambient): The file path to the raw ambient sensor data.
  • Distance data points: The number of data points recorded by the distance sensor.
  • Resultpath (Distance): The file path to the raw distance sensor data.

The FinalResults.csv file contains a summary of all calculations:

1. Date: the date of the measurement
2. Kinematic Viscosity: the kinematic viscosity (in J/kg·sec)
3. Dynamic Viscosity: the dynamic viscosity (in Pa·sec)
4. Density: the sample density (in kg/m³)
5. Force: the force used for the final calculation (in N)
6. Speed: the speed used for the calculation (in m/sec)
7. Sample Volume: the volume of the sample (in m³)
8. Temperature: the average temperature during the measurement (in °C)
9. Humidity: the average humidity during the measurement (in %)
10. Sample Weight: the weight of the sample (in kg)
11. Sample Height: the height of the sample (in m)
12. Sample Area: the measured area of the sample (in m²)

Additional Raw Data:

Within the rawData directory, there are three subfolders:

1. AreaDetermination/: Contains an image captured by the Samsung Galaxy S24 Ultra and a CSV file (AreaResults.csv) with the pixel area value.
2. DensityResults/: Contains DensityResults.csv, which includes the sample weight in grams.
3. ViscometerResults/: Contains three files:
   • AmbientResults.csv: This file contains temperature and humidity data organised by time (seconds from the measurement start). The first column represents the time, the second the temperature (°C) and the third the humidity (%).
   • DistanceResults.csv: Contains distance data (in mm) measured over time. The first column represents the time (seconds from the measurement start) and the second column contains the measured distance.
   • LoadCellResults.csv: Contains load cell data, organised by time (seconds from the measurement start). The first column represents the time and the second contains the load cell measurement (in grams).

Model-Files.zip

This folder contains two subfolders: Gcode-Files and STL-Files.

• Gcode-Files: This folder contains prepared files for the Prusa MK3S+ 3D printer in G-code format. The files are named based on the component number, layer height, filament type, printer model and estimated printing time. For example:
  • Component2&5_0.1mm_PLA_MK3S_2h51m.gcode: This file prints Component 2 and Component 5 with a layer height of 0.1mm using PLA filament on the MK3S(+) printer, requiring 2 hours 51 minutes for printing.
• STL-Files: This folder contains STL files for all components of the viscometer, named by the component number (e.g., Component1.stl). These files represent the 3D models and can be opened in CAD software for modification or used in 3D printing slicing software to prepare files for printing.

TechnicalDrawings.zip

This folder contains 11 PDF files, each representing the technical drawings for a specific component of the viscometer:

• Component 1 to 10: Each file contains detailed schematics and technical drawings for a specific component of the viscometer.
• Overview.pdf: This file includes an overview of the entire system, with a table summarising the sensor information.

ViscometerDataProcessing.zip

This folder contains Python scripts for processing and analysing the viscometer's data. It includes two main files: ViscometerResultClass.py and ViscometerAnalysis.py.

ViscometerResultClass.py: This file contains several Python classes used to store, process and combine all the results necessary for determining viscosity. It functions as a library for the ViscometerAnalysis.py file and is not meant to be executed separately. The classes in this file are used to handle and process data from various sensors, such as the load cell, distance sensor and ambient sensor, as well as to calculate parameters like kinematic viscosity, dynamic viscosity and density.

Explanation of Key Classes in the Script:

• PlotStuff: A class used to store data related to the sensor results and the generated plots.
• LoadCellResults: Handles the results from the load cell sensor, storing the mass and force values.
• AmbientResults: Handles the results from the ambient sensor, including temperature and humidity measurements.
• DistanceResults: Handles the results from the distance sensor, including the measured distance values.
• DensityResults: Calculates sample density, area and volume based on provided sample weight and other measurements.
• SensorResults: A class that reads and processes all sensor data from the load cell, ambient and distance sensors.
• ViscometerResults: This class integrates all sensor data and calculates kinematic and dynamic viscosity. It also generates plots and exports the results into CSV files.

ViscometerAnalysis.py: This script contains several functions that calculate kinematic viscosity and export results, including plots and CSV files. The following code ensures easy handling of the file:

if '__main__' == __name__:

print('Select the folder containing all datasets to process!')

path = fd.askdirectory()

startViscosimeterAnalysis(path)

When executed, this script prompts the user to select the directory containing the measured datasets. The script automatically processes each dataset in the specified directory by calling the startViscometerAnalysis(path) function.

Step-by-Step Process:

• Folder Selection: The user selects the folder containing the datasets to process.
• Automatic Processing: The script processes each dataset in the folder by calling the startViscometerAnalysis(path) function.
• Data Calculations: Based on the sensor data, kinematic and dynamic viscosities are calculated.
• Exporting Results: The results (force, distance, ambient data and viscosity) are saved in CSV files and plots are generated and saved as SVG files.

Explanation of Key Functions in the Script:

• getStartAndStop(): A function that calculates the start and stop times for the analysis based on the available sensor data.
• plotResult(): A function that generates and saves plots for the data collected during the experiment.
• exportForce(), exportDistance(), exportAmbient(): Functions for exporting sensor data into CSV files and generating corresponding plots.
• exportResults(): The main function that calls all other export functions and saves the results in a FinalResults.csv file.
• startViscosimeterAnalysis(): The function that begins the analysis for all datasets in the specified folder. It processes each dataset and performs all necessary calculations.

Viscometer.zip

This folder contains all the Python scripts necessary to operate the Viscometer. A Raspberry Pi 4B controls the device and the following scripts are required to run the system. The publication and supplementary materials provide a detailed explanation of the circuit connections, including the GPIO pin assignments. If different GPIO pins are used, the Python scripts must be adapted accordingly. Within this folder, there are 3 Python files and one subfolder called SensorStuff.

Files in the Viscometer.zip Folder

ResultClass.py: This file supports the main script (Viscometer.py) by providing classes for storing, processing and combining the results necessary for determining viscosity. It functions as a library for Viscometer.py and is not meant to be executed separately. The classes in ResultClass.py handle and process data from various sensors (load cell, distance sensor, ambient sensor) and calculate essential parameters like kinematic viscosity, dynamic viscosity and density.

SensorClass.py: This file contains classes for initialising and managing the sensors used in the Viscometer, including the load cell, ambient sensor, stepper motor and distance sensor. It establishes connections between the sensors and their respective hardware components (GPIO pins) on the Raspberry Pi 4B. The sensors are initialised and configured based on the provided pin settings.

Viscometer.py: This is the main script for controlling the Viscometer. It initialises the sensors, manages data collection and performs the measurements. The script uses multiprocessing to simultaneously handle multiple sensor readings (e.g. ambient temperature, load cell force and distance measurements). In the main section of the script, users can modify GPIO pin settings if needed, allowing flexibility depending on the hardware setup.

SensorStuff Directory

Within this folder are 5 Python files and one subfolder called Libraries. These files handle the individual sensors connected to the Raspberry Pi 4B.

AmbientSensor.py

• This file contains the class AmbientSensor, which measures temperature and humidity using the Adafruit DHT22 sensor. The sensor reads environmental data and stores it in the TempHumMeasurement class. The data is then used in the viscosity calculations.
• Class AmbientSensor: Initialises the DHT22 sensor, performs tests, and continuously measures temperature and humidity. The data is returned as an instance of the TempHumMeasurement class.

ArduinoStuff.py

• This file contains the Arduino class, which handles communication with the Arduino microcontroller. The Arduino measures data from the distance sensor.
• Class Arduino: Establishes a serial connection to the Arduino, reads data from it and manages the communication settings (e.g., baud rate).

CaliperSensor.py

• This file contains the class CaliperSensor, which manages the distance sensor used to measure the sample's movement. The class DistanceResult stores the distance readings and timestamps. The CaliperSensor class also includes methods for zeroing the sensor and measuring the distance.
• Class CaliperSensor: Initialises the sensor, calibrates it and continuously measures the distance. The DistanceResult class stores the distance and the time of the measurement.

Loadcell.py

• This file contains the class LoadCell, which handles the load cell used to measure the weight. The HX711 library interfaces with the load cell.
• Class LoadCell: This class initialises the load cell, calibrates it and is continuously measuring. The LoadCellMeasurement class stores the weight and the timestamp.

MotorControl.py

• This file contains the class StepperMotor, which controls the stepper motor that moves the sample during measurement. It manages the direction and speed of the motor using the provided GPIO pins.
• Class StepperMotor initialises the motor and handles the sample's movement, including setting the direction and speed. It uses multiprocessing to control the motor's movement independently of the other sensors.

Libraries Directory

This folder contains one file: hx711.py. This file is necessary for the load cell's operation and was downloaded from the HX711 GitHub repository. It provides the interface for the Raspberry Pi 4B to communicate with the HX711 load cell amplifier. It contains the necessary code to interface with the HX711 chip and retrieve weight data from the load cell. This Github repository was created and maintained by gandalf15.

How the Scripts Work Together

All the components of the Viscometer are connected through several Python scripts that work in tandem. Here's a brief overview of what happens when the Viscometer.py script is executed:

1. Script Initialisation: When Viscometer.py is executed, the script starts by importing the necessary classes and setting up the Raspberry Pi's GPIO pins. The SensorClass is then initialised, which connects to and configures all the sensors: the load cell, ambient sensor, distance sensor and stepper motor.
2. Sensor Initialisation: The SensorClass initilises all the sensors using the provided GPIO pin settings. The LoadCell, AmbientSensor and CaliperSensor classes are instantiated and prepared for measuring. The StepperMotor class is also initialised to control the movement.
3. Measurement Process: Once all sensors are initialised, the script collects data. The ViscometerEventsProcesses class manages multiple processes running in parallel. This includes reading data from the ambient sensor, load cell and distance sensor. The multiprocessing library ensures that each sensor's data collection happens simultaneously without blocking the others.
4. Data Collection and Control: Viscometer.py's startProcedure() function coordinates the entire measurement procedure. It triggers the startMeasurementEvent, which signals the sensors to begin taking readings. The motor is activated to move and the sensors start recording data in real-time. The distance sensor measures the sample's movement, the load cell measures the weight and the ambient sensor records temperature and humidity.
5. Data Export and Plotting: After the measurements are taken, the exportResults() function saves the collected data into CSV files. It also generates and saves plots for visualising the measurements (e.g., force, distance, ambient data) as SVG files. The final results, including calculated viscosity values, are saved in the FinalResults.csv file.
6. Clean-Up: Once the measurement is complete, the motor is stopped, the GPIO pins are cleaned and all processes are terminated. The user is then prompted to review the results and decide whether to keep or delete the data, especially if it contains many artefacts.

Code and Software Requirements

To process the viscometer data, the following Python libraries are required:

• Python V: 3.10.11
• numpy V: 1.24.4
• matplotlib V: 3.5.1
• scipy V: 1.8.0
• joblib V: 1.3.2