Merge pull request #41 from elmbeech/master

pcdl release v4.1.0

Author: elmbeech

.github/workflows/apple.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         #python-version: ["3.14"]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     env:
       MPLBACKEND: Agg  # https://github.com/orgs/community/discussions/26434

.github/workflows/linux.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         #python-version: ["3.14"]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     env:
       MPLBACKEND: Agg  # https://github.com/orgs/community/discussions/26434

.github/workflows/windows.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         #python-version: ["3.14"]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     env:
       MPLBACKEND: Agg  # https://github.com/orgs/community/discussions/26434

README.md

@@ -2,9 +2,12 @@
 
 ## Abstract:
 
-physicelldataloader (pcdl) provides a platform independent, python3 based, [pip](https://en.wikipedia.org/wiki/Pip_(package_manager)) installable interface
+physicelldataloader (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)).
+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.
+
+![pcdl concept](man/img/physicelldataloader_concept_v4.0.0.png)
 
 pcdl was forked from the original [PhysiCell-Tools](https://github.com/PhysiCell-Tools) [python-loader](https://github.com/PhysiCell-Tools/python-loader) implementation.
 
@@ -19,8 +22,8 @@ The pcdl python3 library maintains four branches:
 
 ## Header:
 
-+ Language: python [>= 3.10](https://devguide.python.org/versions/)
-+ Library dependencies: anndata, bioio, matplotlib, numpy, pandas, (requests), scipy, vtk
++ 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
 + 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
@@ -92,7 +95,7 @@ Within the pcdl library, we tried to stick to the documentation policy laid out
 + original PhysiCell-Tools python-loader implementation: Patrick Wall, Randy Heiland, Paul Macklin
 + fork pcdl implementation: Elmar Bucher
 + fork pcdl co-programmer: Furkan Kurtoglu, Heber Rocha, Jennifer Eng
-+ fork pcdl continuous testing and feedbacks: Aneequa Sundus, John Metzcar
++ fork pcdl continuous testing and feedbacks: Aneequa Sundus (python), John Metzcar (python), Raquel Arroya (matlab)
 + student prj on pcdl:
   Benjamin Jacobs (make\_graph\_gml),
   Jason Lu (render\_neuroglancer),
@@ -110,7 +113,7 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
 
 ```bibtex
 @Misc{bucher2023,
-  author    = {Bucher, Elmar and Wall, Patrick and Rocha, Heber and Kurtoglu, Furkan and Eng, Jennifer and Sundus, Aneequa, and Metzcar, John and Heiland, Randy and Macklin, Paul},
+  author    = {Bucher, Elmar and Wall, Patrick and Rocha, Heber and Kurtoglu, Furkan and Eng, Jennifer and Sundus, Aneequa, and Metzcar, John and Arroya, Raquel and Heiland, Randy and Macklin, Paul},
   title     = {elmbeech/physicelldataloader: pcdl platform-independent, pip-installable interface to load PhysiCell agent-based modeling framework output into python3.},
   year      = {2023},
   copyright = {Open Access},
@@ -124,7 +127,11 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
 
 + evt generate lineage tree graph output files.
 
+
 ## Release Notes:
++ version 4.1.0 (2025-12-31): elmbeech/physicelldataloader
+    + new TimeStep class and TimeSeris class function **get_spatialdata** and command line command **pcdl_get_spatialdata**.
+
 + 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.
@@ -135,7 +142,7 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
     + command line commands now return **error code 0** if the command runs successfully.
 
 + version 4.0.3 (2025-07-20): elmbeech/physicelldataloader
-    + timestep and timeseries **plot_contour**, **plot_scatter**, and **plot_timeseries** handle now **kwargs** arguments.
+    + TimeStep and TimeSeris **plot_contour**, **plot_scatter**, and **plot_timeseries** handle now **kwargs** arguments.
     + minor bugfixes.
 
 + version 4.0.2 (2025-06-29): elmbeech/physicelldataloader

man/TUTORIAL_commandline.md

@@ -13,7 +13,6 @@ Please spend some time to learn about each of the about 20 commands, by studying
 This will truly make you a power user!
 
 
-
 ## Preparation
 
 To runs this tutorial,
@@ -31,10 +30,8 @@ python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathli
 ```
 
 
-
 ## Metadata related commands
 
-
 ### ✨ pcdl\_get\_version
 
 Outputs PhysiCell, MCDS, and pcdl version on screen.
@@ -49,7 +46,6 @@ pcdl_get_version output/output00000000.xml
 pcdl_get_version -h
 ```
 
-
 ### ✨ pcdl\_get\_unit\_dict
 
 Generate a [csv](https://en.wikipedia.org/wiki/Comma-separated_values) file that maps attribute and units, as specified in the settings.xml.
@@ -65,10 +61,8 @@ pcdl_get_unit_dict -h
 ```
 
 
-
 ## Microenvironment related commands
 
-
 ### ✨ pcdl\_get\_substrate\_list
 
 Outputs all substrates modeled in the microenvironment on screen.
@@ -83,7 +77,6 @@ pcdl_get_substrate_list output/output00000000.xml
 pcdl_get_substrate_list -h
 ```
 
-
 ### ✨ pcdl\_get\_conc\_attribute
 
 Generate a [json](https://en.wikipedia.org/wiki/JSON) file, that lists all substrate attributes.
@@ -108,7 +101,6 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_get\_conc\_df
 
 Generate a dataframe [csv](https://en.wikipedia.org/wiki/Comma-separated_values) file that lists one voxel per row,
@@ -133,7 +125,6 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_plot\_contour
 
 For oxygen generate a [jpeg](https://en.wikipedia.org/wiki/JPEG) file
@@ -149,7 +140,6 @@ pcdl_plot_contour output/output00000000.xml oxygen
 pcdl_plot_contour -h
 ```
 
-
 ### ✨ pcdl\_make\_conc\_vtk
 
 Generate a rectilinear grid [vtk](https://en.wikipedia.org/wiki/VTK) file from a single time step,
@@ -179,7 +169,6 @@ Further readings:
 
 ## Cell agent related commands
 
-
 ### ✨ pcdl\_get\_celltype\_list
 
 Output all cell types modeled.
@@ -232,7 +221,6 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_get\_cell\_df
 
 Generate a dataframe [csv](https://en.wikipedia.org/wiki/Comma-separated_values) file that lists one cell per row,
@@ -244,7 +232,11 @@ In the example below, the generated csv contains:
 
 ```bash
 pcdl_get_cell_df output 2
+```
+```bash
 pcdl_get_cell_df output/output00000000.xml
+```
+```bash
 pcdl_get_cell_df -h
 ```
 
@@ -253,17 +245,15 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_get\_anndata
 
-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.
+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.
 Data stored in this format can be analyzed the same way as usually sc RNA seq data is analyzed.
 
 ```bash
 pcdl_get_anndata output/output00000000.xml
-pcdl_get_anndata -h
 ```
 ```bash
 pcdl_get_anndata output
@@ -277,7 +267,6 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_make\_graph\_gml
 
 Generate [gml](https://github.com/elmbeech/physicelldataloader/blob/master/man/publication/himsolt1996gml_a_portable_graph_file_format.pdf) files.
@@ -300,7 +289,6 @@ Further readings:
 + [TUTORIAL_r.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_r.md)
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
-
 ### ✨ pcdl\_plot\_scatter
 
 Generate a [jpeg](https://en.wikipedia.org/wiki/JPEG) file that displaying all cells.
@@ -319,7 +307,6 @@ pcdl_plot_scatter output
 pcdl_plot_scatter -h
 ```
 
-
 ### ✨ pcdl\_make\_cell\_vtk
 
 Generate a 3D glyph [vtk](https://en.wikipedia.org/wiki/VTK) file from a single time step,
@@ -348,9 +335,28 @@ Further readings:
 + [TUTORIAL_julia.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_julia.md)
 
 
-
 ## Microenvironment and cell agent related commands
 
+### ✨ 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.
+Data stored in this format can be analyzed the same way as spatial sc RNA seq data is analyzed.
+
+```bash
+pcdl_get_spatialdata output/output00000000.xml
+```
+```bash
+pcdl_get_spatialdata output
+```
+```bash
+pcdl_get_spatialdata -h
+```
+
+Further readings:
++ [TUTORIAL_python3_scverse.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_python3_scverse.md)
 
 ### ✨ pcdl\_plot\_timeseries
 
@@ -376,19 +382,16 @@ pcdl_plot_timeseries output none
 ```bash
 pcdl_plot_timeseries output cell_type
 ```
-
 ```bash
 pcdl_plot_timeseries output cell_type oxygen
 ```
-
 ```bash
 pcdl_plot_timeseries output cell_type oxygen max
 ```
 
 ```bash
 pcdl_plot_timeseries output none oxygen
 ```
-
 ```bash
 pcdl_plot_timeseries output none oxygen --frame conc
 ```
@@ -397,7 +400,6 @@ pcdl_plot_timeseries output none oxygen --frame conc
 pcdl_plot_timeseries -h
 ```
 
-
 ### ✨ pcdl\_make\_ome\_tiff
 
 Generate an [ome.tiff](https://ome-model.readthedocs.io/en/stable/index.html) file,
@@ -428,7 +430,6 @@ Further readings:
 + [TUTORIAL_neuroglancer.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_neuroglancer.md)
 + [TUTORIAL_blender.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_blender.md)
 
-
 ### ✨ pcdl\_render\_neuroglancer
 
 With this command, you can render a time step ome.tiff file or a time step from a whole time series ome.tiff file straight into [Neuroglancer](https://research.google/blog/an-interactive-automated-3d-reconstruction-of-a-fly-brain/), which is a [WebGL](https://en.wikipedia.org/wiki/WebGL)-based viewer that will render the ome.tiff straight in your browser.
@@ -477,6 +478,7 @@ pcdl_make_movie output/cell_cell_type_z0.0/
 pcdl_make_movie -h
 ```
 
+
 ## Data Clean Up
 
 After you are done checking out the 2D unit test dataset,

man/TUTORIAL_julia.md

@@ -3,6 +3,37 @@
 [Julia](https://julialang.org/) is a scientific computing language.
 
 
+## ✨ Run pcdl within Julia
+
+We are using the [PyCall.js](https://github.com/JuliaPy/PyCall.jl) library
+to run pcdl within Julia.
+
+Make sure that the python3 environment is activated, which has pcdl installed.
+
+Fire up a Juila shell.
+```bash
+julia
+```
+
+Pakage installation.
+
+```julia
+using Pkg
+Pkdg.add("PyCall")
+```
+
+Run pcdl.
+
+```julia
+using PyCall
+
+pcdl = pyimport("pcdl")  # import the pcdl module.
+mcdsts = pcdl.TimeSeries("path/to/PhysiCell/output/")  # load an mcds time series.
+
+?mcdsts.get_cell_df()  # retrieve a function's docstring.
+df = mcdsts.get_cell_df()  # retrieve the cell dataframe.
+```
+
 ## ✨ Handle csv files
 
 ### Save pcdl data structures as csv files from the command line
@@ -98,7 +129,7 @@ pcdl_make_graph_gml output/output00000024.xml neighbor --node_attribute cell_typ
 
 ### Load gml files into a julia data structures
 
-⚠ **bue 2024-09-04:** this is currently not working, since, for now, GraphIO cannot handle the graph, node, or edge metadata in the file.
+⚠ **bue 2024-09-04:** this is currently not working, since, for now, GraphIO cannot handle the graph, node, or edge metadata in the file ( https://github.com/JuliaGraphs/GraphIO.jl/issues/46 ).
 
 We will use the [GraphIO.js](https://github.com/JuliaGraphs/GraphIO.jl) library,
 to load gml files.
@@ -142,7 +173,7 @@ pcdl_get_anndata output/
 
 ### Load h5ad files into a julia data structures
 
-We will use scver's [Muon.jl](https://github.com/scverse/Muon.jl) library,
+We will use scverse's [Muon.jl](https://github.com/scverse/Muon.jl) library,
 to load h5ad files.
 
 Package installation.
@@ -203,7 +234,6 @@ Load image file.
 
 ```julia
 using FileIO
-using Images
 ```
 ```julia
 omeimg = load("output/timeseries_ID.ome.tiff")

man/TUTORIAL_python3_scverse.md

@@ -1,15 +1,14 @@
 # PhysiCell Data Loader Tutorial: pcdl and Python and the scVerse
 
-[AnnData](https://anndata.readthedocs.io/en/latest/) is the data standard from the python single cell community.
-This means, PhysiCell output transformed into an AnnData object can be analyzed the same way  sc RNA seq data is analyzed.
+[AnnData](https://anndata.readthedocs.io/en/latest/) and [SpatialData](https://spatialdata.scverse.org/en/stable/) are data standards from the python single cell community.
+This means, PhysiCell output transformed into an AnnData and SpatialData objects can be analyzed the same way  sc RNA seq data is analyzed.
 The whole [scverse](https://scverse.org/) (single cell univers)  becomes accessible.
 
 This includes:
 + [scanpy](https://scanpy.readthedocs.io/en/latest/): for classic single cell analysis.
 + [squidpy](https://squidpy.readthedocs.io/en/stable/): for spatial single cell analysis.
 + [scvi-tools](https://scvi-tools.org/): for single cell machine learning.
-+ [muon](https://muon.readthedocs.io/en/latest/): for multimodal omics analysis.
-And there is a whole [ecosystem](https://scverse.org/packages/#ecosystem) of libraries, compatible with the AnnData format.
+And there is a whole [ecosystem](https://scverse.org/packages/#ecosystem) of libraries, compatible with the AnnData (and SpatialData) format.
 
 Whatever you d'like to do with your physicell data, it most probably was already done with single cell wet lab data.
 That's being said: PhysiCell data is different scdata than scRNA seq data!