pcDataLoader

Abstract:

pcDataLoader provides a platform independent, python3 based, pip installable interface to load output, generated with the PhysiCell agent based modeling framework, into python3.

pcDataLoader is forked from the original PhysiCell-Tools python-loader implementation.

The pcDataLoader python3 library will maintain two main branches:

• Branch version 2 will be strictly compatible with the original PhysiCell-Tools/python-loader code, although pip installable.
• Branch version 3 might break with old habits, although tries to be as downwards compatible as possible. The aim of the v3 branch is to get a very lean and agile physicell output interface for the ones coming from the python3 world to physicell.

Note: there can only be one version of pcDataLoader installed in each python3 environment.

Header:

• Language: python >= 3.6
• Library dependencies: matplotlib, numpy, pandas
• Programmer: Patrick Wall, Elmar Bucher, Randy Heiland, Paul Macklin
• Date of origin original PhysiCell-Tools python-loader: 2019-09-02
• Date of origin pcDataLoader fork: 2022-08-30
• License: BSD-3-Clause
• User manual: this README.md file
• Source code: https://github.com/elmbeech/pcDataLoader

HowTo Guide - branch v2 specific:

How to install the latest pcDataLoader from the v2 branch?

pip3 install "pcDataLoader<3"

How to update to the latest pcDataLoader from the v2 branch?
This works, even when you have a v3 branch installation.

pip3 install -U "pcDataLoader<3"

HowTo Guide - branch v3 specific:

How to install the latest pcDataLoader from the v3 branch?

pip3 install pcDataLoader

How to update to the latest pcDataLoader from the v3 branch?
This works, even when you have a v2 branch installation.

pip3 install -U pcDataLoader

HowTo Guide - branch generic:

How to uninstall pcDataLoader from your python3 environment?

pip3 uninstall pcDataLoader

How to check for the current installed pcDataLoader version?

import pcDataLoader
pcDataLoader.__version__

How to load the pcDataLoader library?

from pcDataLoader import pyMCDS
from pcDataLoader import pyMCDS_timeseries
from pcDataLoader import read_MultiCellDS_xml

How to use the addition plotting scripts for plotting PhysiCell output?
This plotting scripts can be found in the pcDataLoader/plotting directory.
You can copy these python3 scripts into your PhysiCell output directory and run them there.
anim_svg_substrate.py additionally requires the scipy library and cells3D_fury.py additionally requires the fury libraries to be installed. Both of them can be installed with pip.

Howto run the unit test code?
You can always run the unit test suit, to check if you have an integer pcDataLoader installation. The test code can be found in the test directory.

python3 test_snapshot.py

python3 test_timeseries.py

Reference:

This is the technical descriptions of the machinery and how to operate it. References are maintained in each module`s docstring.

For each pcDataLoader module, get on the fly reference information with the help command.

from pcDataLoader import pyMCDS, pyMCDS_timeseries, read_MultiCellDS_xml

help(pyMCDS)
help(pyMCDS_timeseries)
help(read_MultiCellDS_xml)

Tutorial:

• http://www.mathcancer.org/blog/python-loader/

Discussion:

To be developed.

About Documentation:

Within the pcDataLoader library, I try to stick to the documentation policy lined out by Daniele Procida in his talk "what nobody tells you about documentation" at PyCon 2017 in Portland, Oregon.

Contributions:

• original PhysiCell-Tools python-loader implementation: Patrick Wall, Randy Heiland, Paul Macklin
• fork pcDataLoader implementation: Elmar Bucher

Release Notes:

• version 2.0.3 (2023-06-16): elmbeech/physicelldataloader pypa odyssey is comming to an end.
• version 2.0.2 (2023-01-06): elmbeech/pcDataLoader reset patch voxel spacing bugfix, so that branch2 is full compatible with branch1 again. use branch3 for a bugfixed version!
• version 2.0.1 (2022-11-08): elmbeech/pcDataLoader beta release patch voxel spacing bugfix.
• version 2.0.0 (2022-08-30): elmbeech/pcDataLoader pip installable release, derived from and compatible with PhysiCell-Tools/python-loader release 1.1.0 (2022-07-20).
• version 1.1.0 (2022-05-09): Physicell-Tools/python-loader release compatible with pre-v1.10.x of PhysiCell
• version 1.0.1 (2020-01-25): Physicell-Tools/python-loader time-series related bug fix
• version 1.0.0 (2019-09-28): Physicell-Tools/python-loader first public release!