Merge pull request #44 from elmbeech/master

pcdl version 4.1.5

Author: elmbeech

.github/workflows/apple.yml

@@ -25,16 +25,16 @@ jobs:
       PYTHONPATH: /Users/runner/work/physicelldataloader/physicelldataloader
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@main
     - name: set up python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@main
       with:
         python-version: ${{ matrix.python-version }}
     - name: install dependencies
       run: |
         brew install ffmpeg imagemagick
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib neuroglancer numpy pandas requests scikit-image scipy vtk
+        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib networkx neuroglancer numpy pandas requests scikit-image scipy vtk "ome-zarr<0.14.0"
         python -m pip install /Users/runner/work/physicelldataloader/physicelldataloader -v
         #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: lint with flake8

.github/workflows/linux.yml

@@ -25,16 +25,17 @@ jobs:
       PYTHONPATH: /home/runner/work/physicelldataloader/physicelldataloader
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@main
     - name: set up python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@main
       with:
         python-version: ${{ matrix.python-version }}
     - name: install dependencies
       run: |
+        sudo apt update
         sudo apt install ffmpeg imagemagick
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib neuroglancer numpy pandas requests scikit-image scipy vtk
+        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib networkx neuroglancer numpy pandas requests scikit-image scipy vtk "ome-zarr<0.14.0"
         python -m pip install /home/runner/work/physicelldataloader/physicelldataloader -v
         #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: lint with flake8

.github/workflows/windows.yml

@@ -25,16 +25,16 @@ jobs:
       PYTHONPATH: D:\a\physicelldataloader\physicelldataloader
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@main
     - name: set up python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@main
       with:
         python-version: ${{ matrix.python-version }}
     - name: install dependencies
       run: |
         choco install ffmpeg imagemagick
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib neuroglancer numpy pandas requests scikit-image scipy vtk
+        python -m pip install flake8 pytest anndata bioio bioio-ome-tiff matplotlib networkx neuroglancer numpy pandas requests scikit-image scipy vtk "ome-zarr<0.14.0"
         python -m pip install D:\a\physicelldataloader\physicelldataloader -v
         #echo 'set PYTHONPATH=D:\a\physicelldataloader\physicelldataloader' >> $GITHUB_ENV
         #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

README.md

@@ -2,7 +2,7 @@
 
 ## Abstract:
 
-physicelldataloader (pcdl) provides a platform-independent (Windows, MacOSX, Linux), python3 based, [pip](https://en.wikipedia.org/wiki/Pip_(package_manager))-installable set of commands
+physicell data loader (pcdl) provides a platform-independent (Windows, MacOSX, Linux), python3 based, [pip](https://en.wikipedia.org/wiki/Pip_(package_manager))-installable set of commands
 to load output, generated with the [PhysiCell](https://github.com/MathCancer/PhysiCell) agent-based modeling and diffusion solver framework,
 into [python3](https://en.wikipedia.org/wiki/Python_(programming_language)) or transform PhysiCell output into more widely used data formats.
 pcdl can be loaded as a python3 module or run straight from the command line.
@@ -23,7 +23,7 @@ The pcdl python3 library maintains four branches:
 ## Header:
 
 + Language: python [>= 3.11](https://devguide.python.org/versions/)
-+ Library dependencies: anndata, bioio, geopandas, matplotlib, neuroglancer, numpy, pandas, (requests), scikit-image, scipy, shapely, spatialdata, vtk
++ Library dependencies: anndata, bioio, geopandas, matplotlib, networkx, neuroglancer, numpy, pandas, (requests), scikit-image, scipy, shapely, spatialdata, vtk
 + Date of origin original PhysiCell-Tools python-loader: 2019-09-02
 + Date of origin pcdl fork: 2022-08-30
 + Doi: https://doi.org/10.5281/ZENODO.8176399
@@ -49,7 +49,8 @@ Basics Tutorials:
 Extras tutorials python3 language:
 + [pcdl and python3 and json](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_python3_json.md)
 + [pcdl and python3 and pandas](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_pandas.md)
-+ [pcdl and python3 and scipy and scanpy](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_scverse.md)
++ [pcdl and python3 and scanpy and squidpy](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_scverse.md)
++ [pcdl and python3 and muspan](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_muspan.md)
 + [pcdl and python3 and graphs](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_graph.md)
 + [pcdl and python3 and matplotlib](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_matplotlib.md)
 + [pcdl and python3 and vtk](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_python3_vtk.md)
@@ -129,6 +130,18 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
 
 
 ## Release Notes:
++ version 4.1.5 (2026-04-05)
+    + bugfix library dependencies and library versions.
+
++ version 4.1.4 (2026-04-04)
+    + pyMCDSts **mcdsts.make_contour** extrema parameter is replaced by vmin and vmax to be compatible with mcds.make\_contour and plt.contour.
+    + **make_cell_vtk** and **make_conc_vtk** now offer an ext parameter, allowing to manually specify the exact file extension. special thanks to Danyon Gedris!
+    + new **make_muspan** TimeStep class and TimeSeris class function and **pcdl_get_muspan** command line command. special thanks to Joshua Moore and Joshua Bull!
+
++ version 4.1.3 (2026-03-21):
+    + new **pcdl.pccmap** color map. this is an adaptation of the physicell pathology paint by number color map.
+    + new TimeStep **get_pcdl_version** function.
+
 + version 4.1.2 (2026-03-06): elmbeech/physicelldataloader
     + new  **custom_data_astype** TimeStep class and TimeSeries class function to set the dtype of custom\_data variables even after the timestep or timeseries is loaded.
     + TimeSeries \_\_init\_\_ function can now handle a list of TimeStep objects as input instead of a path.
@@ -137,13 +150,14 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
     + reduced memory footprint.
 
 + version 4.1.0 (2025-12-31): elmbeech/physicelldataloader
-    + new **get_spatialdata** TimeStep class and TimeSeris class function and **pcdl_get_spatialdata** command line command.
+    + new **get_spatialdata** TimeStep class and TimeSeris class function and **pcdl_get_spatialdata** command line command. special thanks to Luca Marconato!
+    + with this release, pcdl officially became an [scverse ecosystem](https://scverse.org/packages/#ecosystem) package.
 
 + version 4.0.5 (2025-10-22): elmbeech/physicelldataloader
     + **settingxml** default is now set to False, because the cell\_type id label mapping can, in recent PhysiCell output, be retrieved from output\*.xml too.
     + **plot_scatter** and **plot_timeseries** now additionally have a cat\_drop and cat\_keep argument to filter categorical data.
     + **plot_timeseries(frame=conc)** now plots by default all substrate concentrations over time.
-    + **plot_timeseries(ext=)** parameter offers to return a dataframe object, dafaframe csv file, image file, or a matplotlib fig object. special thanks to John Nardini and Edward Young.
+    + **plot_timeseries(ext=)** parameter offers to return a dataframe object, dafaframe csv file, image file, or a matplotlib fig object. special thanks to John Nardini and Edward Young!
 
 + version 4.0.4 (2025-07-23): elmbeech/physicelldataloader
     + command line commands now return **error code 0** if the command runs successfully.

man/REFERENCE.md

@@ -46,6 +46,7 @@ Basically, there are four types of functions:
 ### TimeStep medata
 *version*
 + [help(mcds.get_multicellds_version)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.get_multicellds_version.md)  #! workhorse function
++ [help(mcds.get_pcdl_version)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.get_pcdl_version.md)  #! workhorse function
 + [help(mcds.get_physicell_version)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.get_physicell_version.md)  #! workhorse function
 
 *time*
@@ -99,6 +100,8 @@ Basically, there are four types of functions:
 + [help(mcds.make_graph_gml)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.make_graph_gml.md)  #! workhose function
 
 ### TimeStep microenvironment and cells
++ [help(mcds.get_muspan)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.get_muspan.md)  #! workhose function
++ [help(mcds.get_spatialdata)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.get_spatialdata.md)  #! workhose function
 + [help(mcds.make_ome_tiff)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.make_ome_tiff.md)  #! workhose function
 + [help(mcds.make_neuroglancer)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcds.make_neuroglancer.md)  #! workhose function
 
@@ -146,6 +149,8 @@ Basically, there are four types of functions:
 + [help(mcdsts.get_graph_gml)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcdsts.make_graph_gml.md)  #! workhose function
 
 ### TimeSteries microenvironment and cells
++ [help(mcdsts.get_muspan)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcdsts.get_muspan.md)  #! workhose function
++ [help(mcdsts.get_spatialdata)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcdsts.get_spatialdata.md)  #! workhose function
 + [help(mcdsts.make_ome_tiff)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcdsts.make_ome_tiff.md)  #! workhose function
 + [help(mcdsts.make_neuroglancer)](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/mcdsts.make_neuroglancer.md)  #! workhose function
 
@@ -196,6 +201,8 @@ The command line interface functions mimic the name and parameter arguments as c
 + [pcdl_make_graph_gml --help](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/pcdl_make_graph_gml.md)  #! workhorse function
 
 ### Command line cells and microenvironment
++ [pcdl_get_muspan --help](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/pcdl_get_muspan.md)  #! workhorse function
++ [pcdl_get_spatialdata --help](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/pcdl_get_spatialdata.md)  #! workhorse function
 + [pcdl_make_ome_tiff --help](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/pcdl_make_ome_tiff.md)  #! workhorse function
 + [pcdl_make_neuroglancer --help](https://github.com/elmbeech/physicelldataloader/tree/master/man/docstring/pcdl_make_neuroglancer.md)  #! workhorse function
 

man/TUTORIAL_blender.md

@@ -10,13 +10,16 @@ And there exists a bioxel nodes plugin, that lets us load ome tiff files.
 
 The blender bvtk nodes plugin allows us to load vtk files into blender.
 
+Note, to be able to load whole time series, the blender bvtk nodes plugin needs a simplified output00000000.vtp file name and extension (which is different from the pcdl default output00000000\_cell.vtp).
+This is why the ext parameter explicitly has to be set.
+
 ### Generate vtk files from the command line
 
 ```bash
 pcdl_make_conc_vtk output
 ```
 ```bash
-pcdl_make_cell_vtk output
+pcdl_make_cell_vtk output --ext .vtp  # blender bvtk nodes compatible filename and extension.
 ```
 
 ### Generate vtk files from within python
@@ -26,7 +29,7 @@ import pcdl
 
 mcdsts = pcdl.TimeSeries('output/')
 mcdsts.make_conc_vtk()
-mcdsts.make_cell_vtk()
+mcdsts.make_cell_vtk(ext='.vtp')  # blender bvtk nodes compatible filename and extension.
 ```
 
 ### Blender vtk nodes plugin installation

man/TUTORIAL_commandline.md

@@ -249,7 +249,7 @@ Further readings:
 
 From the whole time series or from a single time step, generate h5ad [anndata](https://anndata.readthedocs.io/en/latest/) [hd5](https://en.wikipedia.org/wiki/Hierarchical_Data_Format) files.
 
-Anndata is the standard data format in the python single cell community.
+Anndata is the standard data format in the python3 single cell community.
 Data stored in this format can be analyzed the same way as usually sc RNA seq data is analyzed.
 
 ```bash
@@ -337,12 +337,33 @@ Further readings:
 
 ## Microenvironment and cell agent related commands
 
+### ✨ pcdl\_get\_muspan
+
+From time series and single time steps, generate [muspan](https://www.muspan.co.uk/) domain files.
+One file per time step and z-layer.
+
+Muspan is a sphisticated python3 libaray for multiscale spatial data analysis, develop by researchers at the University of Oxford.
+
+```bash
+pcdl_get_muspan output/output00000000.xml
+```
+```bash
+pcdl_get_muspan output
+```
+```bash
+pcdl_get_muspand -h
+```
+
+Further readings:
++ [TUTORIAL_python3_muspan.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_python3_muspan.md)
+
+
 ### ✨ pcdl\_get\_spatialdata
 
 From a single time step, generate [spatialdata](https://spatialdata.scverse.org/en/stable/) [zarr](https://zarr.dev/) files.
 The spatialdata format should, in the long run, become comaptibel with the [OME-NGFF](https://ngff.openmicroscopy.org/latest/index.html) data format.
 
-Spatialdata is the standard data format in the python spatial single cell community.
+Spatialdata is the standard data format in the python3 spatial single cell community.
 Data stored in this format can be analyzed the same way as spatial sc RNA seq data is analyzed.
 
 ```bash

man/TUTORIAL_introduction.md

@@ -1,6 +1,6 @@
 # PhysiCell Data Loader Tutorial: pcdl Introduction
 
-If you have not already done so, please install the latest version of physicelldataloader (pcdl),
+If you have not already done so, please install the latest version of physicell data loader (pcdl),
 as described in the [HowTo](https://github.com/elmbeech/physicelldataloader/blob/master/man/HOWTO.md) section.\
 The current development happens in branch v4.
 Branch v3 and v4 are maintained and [pip](https://pypi.org/project/pcdl/) installable.
@@ -23,10 +23,10 @@ In 2019, a similar loader script was written for python3.
 The name of this script filed was pyMCDS.py and basically defined one class named pyMCDS.
 
 In autumn 2022, an endeavor was undertaken to pack the original pyMCDS.py script into a pip installable python3 library and develop it further, but always in such a way that, if necessary, the code could still be run like in the early days.\
-The result is the pcdl physicelldataloader library branch v2, v3.
+The result is the pcdl physicell data loader library branch v2, v3.
 In spring 2025, the code was stripped of some relics (mainly in the back end) from the early days to make the code more python3 than C++ like, which resulted in branch v4.
 
-The result from all of this is the pcdl physicelldataloader library here.\
+The result from all of this is the pcdl physicell data loader library here.\
 In the big picture, the pyMCDS class evolved into the TimeStep class, which is slightly heavier but much more powerful for downstream data analysis than the original pyMCDS class.
 Additionally, a TimeSeries class was added.
 

man/TUTORIAL_python3_muspan.md

@@ -0,0 +1,30 @@
+# PhysiCell Data Loader Tutorial: pcdl and Python and MuSpAn
+
+[MuSpAn](https://www.muspan.co.uk/) is a multiscale spatial analysis toolbox for analyzing spatial transcriptomics data, multiplex immunohistochemistry data, imaging mass cytometry data, and more.
+It uses cutting-edge mathematical and statistical approaches to data analysis to provide the most comprehensive spatial analysis available and is being continually expanded, with a team of quantitative researchers constantly developing new methodology to tackle multiscale spatial analysis problems.
+
+Pcdl offers a time step and time series get\_muspan function to translate cell and substrate data into a dictionary of muspan domain objects, one domain per time step z-layer.
+
+Additionally, pcdl provides a pcdl\_get\_muspan command line command to translate PhysiCell output into muspan domain files.
+
+For installation and learning how to use muspan, please follow the official documentation.
+
++ https://www.muspan.co.uk/
++ https://docs.muspan.co.uk/latest/Documentation.html
++ https://github.com/joshwillmoore1/MuSpAn-Public
+
+## Translate mcds time step and time series into muspan domains.
+
+```python
+import pcdl
+import muspan as ms
+
+mcdsts = pcdl.TimeSeries('output/')
+do_domain = mcdsts.get_muspan()  # translate the mcds time seris into a dictionary of muspan domain objects.
+ls_domain =  sorted(do_domain.keys())  # generate an orderes list of domain names
+
+print(ls_domain)   # print a list of domain names
+print(do_domain[ls_domain[0]])  # take a look at the first domain in the ls_domain list.
+```
+
+That's it. The rest is analysis!

man/TUTORIAL_python3_timeseries.md

@@ -1,6 +1,6 @@
 # PhysiCell Data Loader Tutorial: pcdl and Python and MCDS TimeSeries
 
-If not already done so, please install the latest version of physicelldataloader (pcdl), as described in the [HowTo](https://github.com/elmbeech/physicelldataloader/blob/master/man/HOWTO.md) section.
+If not already done so, please install the latest version of physicell data loader (pcdl), as described in the [HowTo](https://github.com/elmbeech/physicelldataloader/blob/master/man/HOWTO.md) section.
 And maybe read about the pcdl [background](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_introduction.md) information.
 And perhaps, work thorough the [TUTORIAL_python3_timestep.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_python3_timestep.md)