PhysiCell-Tools · elmbeech · Jan 10, 2025 · Sep 26, 2024 · Sep 26, 2024 · Oct 8, 2024
diff --git a/README.md b/README.md
@@ -56,9 +56,7 @@ Extras tutorials python3 language:
 Extras tutorials for other languages than python3:
 
 + [pcdl and julia](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_julia.md)
-<!--
-+ [pcdl and matlab or octave](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_matlab_octave.md)
--->
++ [pcdl and matlab](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_matlab_octave.md)
 + [pcdl and R](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL_r.md)
 
 Extras tutorials for GUI software:
@@ -104,6 +102,8 @@ Within the pcdl library, we tried to stick to the documentation policy laid out
   Nick Oldfather (unit test model),
   Thierry-Pascal Fleurant (plot\_timeseries)
 
+Developers, please make pull requests to the https://github.com/elmbeech/physicelldataloader/tree/development branch. Thanks!
+
 
 ## Cite:
 
@@ -121,12 +121,21 @@ Within the pcdl library, we tried to stick to the documentation policy laid out
 
 ## Road Map:
 
-+ add make\_conc\_vtk visualization parameter.
-+ new next generation unit test dataset.
-+ rewrite make\_ome\_tiff to use less RAM.
++ evt generate lineage tree graph output files.
 + evt add neuroglancer ome.tiff support.
++ switch from aicsimageio to bioio library, when the library is ripe (napari has switched to bioio).
+
 
 ## Release Notes:
++ version 3.3.3 (2025-01-10): elmbeech/physicelldataloader
+    + bug fix **plot_contour** plot orientation. special thanks to Marco Ruscone!
+    + add test data for new improved **unittest physicell model**. special thanks to Nick Oldfather!
+    + add pyMCDS **make_conc_vtk** on the fly visualization. special thanks to Randy Heiland and Nick Oldfather!
+    + pyMCDS and pyMCDSts **make_graph_gml** and pyAnnData **get_anndata** handles now spring\_attached\_cells graph too.
+
++ version 3.3.2 (2024-11-24): elmbeech/physicelldataloader
+    + **Warnings** will no longer be piped to standard output if verbose is set to False.
+    + pyMCDS **make_ome_tiff** function rewriten to be less RAM hungry and more versatile.
 
 + version 3.3.1 (2024-09-22): elmbeech/physicelldataloader
     + bugfix pyMCDS custom vectors loading.
@@ -170,11 +179,11 @@ Within the pcdl library, we tried to stick to the documentation policy laid out
     + new pyMCDS **set_verbosity_false** function, to complete pcdl.TimeStep(verbosity=True/False) experience.
     + new pyMCDSts **get_cell_df** function, to extract one big dataframe or a list of dataframes from the whole time series.
     + new pyMCDSts **get_conc_df** function, to extract one big dataframe or a list of dataframes from the whole time series.
-    + new pyMCDSts **make_cell_vtk** function, to save substrate data as rectilinear grid vtk files.
-    + new pyMCDSts **make_conc_vtk** function, to save cell data as glyph vtk files.
-    + new pyMCDSts **make_graph_gml** function, to save graphs in a networkx and igraph compatible files format.
+    + new pyMCDSts **make_cell_vtk** function, to save substrate data as rectilinear grid vtk files. special thanks to Furkan Kurtoglu!
+    + new pyMCDSts **make_conc_vtk** function, to save cell data as glyph vtk files. special thanks to Furkan Kurtoglu!
+    + new pyMCDSts **make_graph_gml** function, to save graphs in a networkx and igraph compatible files format. special thanks to Benjamin Jacobs!
     + new pyMCDSts **make_ome_tiff** function, to save the output data in ome tiff file format.
-    + new pyMCDSts **plot_timeseries** function, to plot time series.
+    + new pyMCDSts **plot_timeseries** function, to plot time series. special thanks to Thierry-Pascal Fleurant!
     + new pyMCDSts **set_verbosity_true** function, to complete the pcdl.TimeSeries(verbosity=True/False) experience.
     + new pyMCDSts **set_verbosity_false** function to complete the pcdl.TimeSeries(verbosity=True/False) experience.
 
@@ -247,7 +256,7 @@ Within the pcdl library, we tried to stick to the documentation policy laid out
       given the computer is connected to the internet, test data can easily be installed and removed with the **pcdl.install_data()** and **pcdl.uninstall_data()** functions now.
 
 + version 3.0.7 (2023-06-08): elmbeech/physicelldataloader
-    + pyMCDSts: replaces the svg dependent **mcdsts.make_jpeg**, **mcdsts.make_png**, and **mcdsts.make_tiff** with **mcdsts.make_imgcell** and **mcdsts.make_imgsubs** which generate images straight out of the loaded data. the **mcdsts.make_gif** and **mcdsts.make_movie** functions were adjusted accordingly.
+    + pyMCDSts: replaces the svg dependent **mcdsts.make_jpeg**, **mcdsts.make_png**, and **mcdsts.make_tiff** with **mcdsts.make_imgcell** and **mcdsts.make_imgsubs** which generate images straight out of the loaded data. the **mcdsts.make_gif** and **mcdsts.make_movie** functions were adjusted accordingly. special thanks to Marshal Gress!
     + pyMCDSts: **mcdsts.read_mcds** loads now automatically all mcds snapshots if no xmlfile\_list is provided (default).
 
 + version 3.0.6 (2023-04-29): elmbeech/physicelldataloader

diff --git a/data_timeseries_2d.tar.gz b/data_timeseries_2d.tar.gz
diff --git a/data_timeseries_3d.tar.gz b/data_timeseries_3d.tar.gz
diff --git a/man/TUTORIAL_commandline.md b/man/TUTORIAL_commandline.md
@@ -29,7 +29,7 @@ cd path/to/PhysiCell
 ```
 ```bash
 make data-cleanup
-python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'data_timeseries_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
+python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'output_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
 ```
 
 

diff --git a/man/TUTORIAL_julia.md b/man/TUTORIAL_julia.md
@@ -26,7 +26,7 @@ Package installation.
 
 ```julia
 using Pkg
-Pkg.add("CSV")
+Pkdg.add("CSV")
 Pkdg.add("DataFrames")
 ```
 

diff --git a/man/TUTORIAL_matlab_octave.md b/man/TUTORIAL_matlab_octave.md
@@ -1,11 +1,11 @@
-# PhysiCell Data Loader Tutorial: pcdl and the Matlab and Octave programming language
+# PhysiCell Data Loader Tutorial: pcdl and the Matlab programming language  <!-- and Octave-->
 
-[Matlab](https://www.mathworks.com/products/matlab.html) / GNU [Octave](https://octave.org/)
+<!-- bue 20240903: could someone test and update who actuallty knows matlab or octave? -->
+
+[Matlab](https://www.mathworks.com/products/matlab.html)  <!-- / GNU [Octave](https://octave.org/) -->
 is a scientific programming language used by some engineers.
 The earliest predecessor of pcdl was actually a Matlab implementation.
-Coming full circle, this is how you can load some pcdl data constructs into Matlab and GNU Octave.
-
-<!-- bue 20240903: could someone test and update who actuallty knows matlab or octave? -->
+Coming full circle, this is how you can load some pcdl data constructs into Matlab.  <!-- and GNU Octave -->
 
 
 ## &#x2728; Handle csv files
@@ -22,7 +22,7 @@ pcdl_get_conc_df output
 pcdl_get_cell_df output
 ```
 
-### Load a csv file into Matlab or Octave as a tabel
+### Load a csv file into Matlab as a tabel  <!-- or Octave -->
 
 &#x26A0; **bue 2024-09-22:** the readtable function is not yet implemented in Octave.
 
@@ -51,7 +51,7 @@ pcdl_get_conc_attribute output 2
 pcdl_get_cell_attribute output 2
 ```
 
-### Load json files into Matlab or Octave
+### Load json files into Matlab  <!-- or Octave -->
 
 ```matlab
 struct_conc = jsondecode(fileread("output/timeseries_conc_attribute_minmax.json"))
@@ -72,10 +72,10 @@ cd path/to/PhysiCell
 pcdl_make_graph_gml output/output00000024.xml neighbor --node_attribute cell_type dead oxygen pressure
 ```
 
-### Load gml files into a Matlab or Octave data construct
+### Load gml files into a Matlab data construct  <!-- or Octave -->
 
-We will use the [matlab-igraph](https://www.mathworks.com/matlabcentral/fileexchange/159001-matlab-igraph) toolbox to load gml files into Matlab or Octave.
-+ https://github.com/DavidRConnell/matlab-igraph/releases/tag/v0.2.0
+We will use the [matlab-igraph](https://www.mathworks.com/matlabcentral/fileexchange/159001-matlab-igraph) toolbox to load gml files into Matlab.  <!-- or Octave -->
++ https://github.com/DavidRConnell/matlab-igraph
 + https://igraph.org/
 
 Install matlab-igaph toolbox.
@@ -101,14 +101,14 @@ pcdl_make_conc_vtk output/output00000024.xml
 pcdl_make_cell_vtk output/output00000024.xml
 ```
 
-### Load a vtr and vtp file into Matlab or Octave data construct
+### Load a vtr and vtp file into Matlab data construct  <!-- or Octave -->
 
 + https://www.mathworks.com/matlabcentral/fileexchange/94993-vtktoolbox
 + https://github.com/KIT-IBT/vtkToolbox
 
-Install matlab-igaph toolbox.
+Install vtk toolbox.
 
-Load vtkfile into Matlab or Octave.
+Load vtkfile into Matlab.  <!-- or Octave -->
 
 ```matlab
 output/output00000024_conc.vtr

diff --git a/man/TUTORIAL_paraview.md b/man/TUTORIAL_paraview.md
@@ -1,5 +1,11 @@
 # PhysiCell Data Loader Tutorial: pcdl and Paraview
 
+<!--
+bue 2024-09-02: vtk and paraview can handle up to 32 bit ometiff images.
+fluorescent microscopy ome tiff standard is 16 bit.
++ https://discourse.vtk.org/t/failed-to-read-tiff-64-bit-samples/12118
+-->
+
 [Paraview](https://www.paraview.org/) is a free and open source scientific visualization software,
 that lets us load and analyze vtk rectilinear grid data and vtk polynomial data<!--, and even ome.tiff data files-->.
 

diff --git a/man/TUTORIAL_python3_graph.md b/man/TUTORIAL_python3_graph.md
@@ -3,7 +3,7 @@
 [Gml](https://github.com/elmbeech/physicelldataloader/blob/master/man/publication/himsolt1996gml_a_portable_graph_file_format.pdf) (graph modeling language) is a portable plain text file format for graphs,
 that can be read by the popular graph libraries [networkx](https://networkx.org/) (python), [igraph](https://igraph.org/) (C, C++, mathematica, python, R) <!--, [JuliaGraphs](ttps://github.com/JuliaGraphs/GraphIO.jl)-->, and possible other graph analysis software too.
 
-Pcdl can export neighborhood <!- and lineage tree --> graphs in gml format for downstream analysis.
+Pcdl can export neighborhood <!-- and lineage tree --> graphs in gml format for downstream analysis.
 
 If you are new to graph theory, then I recommend reading [A Simple Introduction to Graph Theory](https://www.brianheinold.net/graph_theory/A_Simple_Introduction_to_Graph_Theory_Heinold.pdf)
 from Prof. Brian Heinold from Mount Saint Mary's University in Emmitsburg, Maryland, USA.
@@ -48,7 +48,7 @@ print(sorted(g.edges.keys())[0:4])
 g.nodes['node_0']   # {'cell_type': 'cancer_cell', 'dead': 0, 'oxygen': 25.304510426523084, 'pressure': 10.519314516003435}
 ```
 ```python
-g.edgea[('node_0', 'node_1')]   # {'label': 'edge_0_1', 'distance_microns': 15}
+g.edges[('node_0', 'node_1')]   # {'label': 'edge_0_1', 'distance_microns': 15}
 ```
 
 
@@ -60,7 +60,7 @@ import igraph as ig
 g = ig.Graph.Read_GML('output/output00000024_neighbor.gml')
 print(g)
 ```
-``python
+```python
 ig.summary(g)
 ```
 

diff --git a/man/TUTORIAL_python3_json.md b/man/TUTORIAL_python3_json.md
@@ -9,7 +9,7 @@ The [json library](https://docs.python.org/3/library/json.html) is a part of cor
 Json is the ideal data format for unstructured data constructs that not can be stored in csv file format, like a dictionary of lists.
 Please note, python objecta are not per se json comaptible.
 For example:
-Complex numbers are a standard data type in python, but complex numbers can not be stored in json.
+Complex numbers are a standard data type in python, but complex numbers cannot be stored in json.
 Python dictionary keys can be of almost any data type, but json object keys have to be strings.
 
 

diff --git a/man/TUTORIAL_python3_napari.md b/man/TUTORIAL_python3_napari.md
@@ -1,14 +1,14 @@
 # PhysiCell Data Loader Tutorial: pcdl and Python and Napari
 
-[Napari](https://napari.org/stable/) is both, a python library and a GUI software.
+[Napari](https://napari.org/stable/) is both a python library and a GUI software.
 Napari is used by wetlab scientists and bioinformatician to analyze fluorescent microscopy data.
 Napari can read [ome.tiff](https://www.openmicroscopy.org/ome-files/) files.
 https://github.com/AllenCellModeling/napari-aicsimageio
 
 
 ## Install napari
 
-And install the [aicsimageio](https://allencellmodeling.github.io/aicsimageio/) library,
+And install the [aicsimageio](https://github.com/AllenCellModeling/aicsimageio) library,
 which installs the "ome-types" napari plugin,
 that napari can read ome.tiff images inclusive ome metadata.
 

diff --git a/man/TUTORIAL_python3_ometiff.md b/man/TUTORIAL_python3_ometiff.md
@@ -14,7 +14,7 @@ and [TUTORIAL_fiji_imagej.md](https://github.com/elmbeech/physicelldataloader/bl
 
 Additionally ome.tiff, tiff, png, and jpeg files can as well be loaded back in to python as [numpy](https://numpy.org/) array, for example with the [sci-kit image](https://scikit-image.org/) library (image data only).
 
-Besides that, ome.tiff files can be loaded with Allen Institute for Cell Science's [aicsiamgeio](https://github.com/AllenCellModeling/aicsimageio) library (image and metadata).
+Besides that, ome.tiff files can be loaded with Allen Institute for Cell Science's [aicsimageio](https://github.com/AllenCellModeling/aicsimageio) library and possibly with its successor library [bioio](https://github.com/bioio-devs/bioio) (image and metadata).
 
 
 ### Save pcdl data constructs from the command line into tiff and ome.tiff files
@@ -60,7 +60,7 @@ a_cell.shape  # (480, 640, 4)
 from skimage import io
 
 a_ome = io.imread('output/timeseries_ID.ome.tiff')
-a_ome.shape (25, 2, 200, 300)
+a_ome.shape  # (25, 2, 200, 300)
 ```
 
 

diff --git a/man/TUTORIAL_python3_scverse.md b/man/TUTORIAL_python3_scverse.md
@@ -28,7 +28,7 @@ Let's install the required analysis libraries
 pip3 install -U scanpy[leiden]  # single cell analysis inclusive leiden graph clustering algorithm.
 ```
 
-To runs thi tutorial,
+To runs this tutorial,
 you can install the 3D unit test dataset into your PhysiCell output folder,
 by executing the following command sequence.
 
@@ -39,7 +39,7 @@ cd path/to/PhysiCell
 ```
 ```bash
 make data-cleanup
-python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'data_timeseries_3d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
+python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'output_3d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
 ```
 
 

diff --git a/man/TUTORIAL_python3_timeseries.md b/man/TUTORIAL_python3_timeseries.md
@@ -65,7 +65,7 @@ cd path/to/PhysiCell
 ```
 ```bash
 make data-cleanup
-python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'data_timeseries_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
+python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'output_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
 ```
 
 

diff --git a/man/TUTORIAL_python3_timestep.md b/man/TUTORIAL_python3_timestep.md
@@ -1,6 +1,6 @@
 # PhysiCell Data Loader Tutorial: pcdl and python and MCDS TimeSteps
 
-In this chapter, we will load the pcdl library and use its TimeStep class to load the data snapshot 00000012, from [data\_timeseries\_ 2d](https://github.com/elmbeech/physicelldataloader/tree/master/pcdl/data_timeseries_2d) from the 2D time series test dataset.
+In this chapter, we will load the pcdl library and use its TimeStep class to load the data snapshot 00000012, from [data\_timeseries\_ 2d](https://github.com/elmbeech/physicelldataloader/tree/master/pcdl/output_2d) from the 2D time series test dataset.
 
 First, please install the latest version of physicelldataloader (pcdl),
 as described in the [HowTo](https://github.com/elmbeech/physicelldataloader/blob/master/man/HOWTO.md) chapter.
@@ -23,7 +23,7 @@ cd path/to/PhysiCell
 ```
 ```bash
 make data-cleanup
-python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'data_timeseries_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
+python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'output_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
 ```
 
 
@@ -292,7 +292,7 @@ with the agent's position (xyz), the related mesh center coordinate (mnp), the r
 
 ```python
 df_cell = mcds.get_cell_df()
-df_cel.info()
+df_cell.info()
 ```
 ```
 df_cell.shape  # (992, 95)  this means: 992 agents, 96 tracked variables
@@ -343,7 +343,7 @@ print(ann)  # AnnData object with n_obs × n_vars = 992 × 26
 variables:
 
 ```python
-ann.var_name  # numerical cell attributes:  Index(['cell_BM_repulsion_strength', ... , 'total_volume'], dtype='object')
+ann.var_names  # numerical cell attributes:  Index(['cell_BM_repulsion_strength', ... , 'total_volume'], dtype='object')
 ```
 
 observation:
@@ -375,7 +375,7 @@ ann.uns['neighbor']  # metadata about the neighborhood graph.
 
 The output tells us that we have loaded a time step  with 992 cell agents and 26 numerical attributes (vars).
 Further, we have 4 categorical cell agent attributes (obs).
-We have each cell agnet's xy spatial coordinate information (obsm).
+We have each cell agent's xy spatial coordinate information (obsm).
 And we have cell neighbor graph infromation (obsp, uns).
 
 Please have a look at [TUTORIAL_python3_scverse.md](https://github.com/elmbeech/physicelldataloader/blob/master/man/TUTORIAL_python3_scverse.md) to learn more.

diff --git a/man/TUTORIAL_python3_vtk.md b/man/TUTORIAL_python3_vtk.md
@@ -65,7 +65,7 @@ pip3 install fury
 ```
 
 <!-- i have ask Elef if this is true -->
-Unfortunately, rectiliniar grid files are not supported, conc.vtr files can't be loaded.
+Unfortunately, rectiliniar grid files are not supported, conc.vtr files cannot be loaded.
 
 Load and display cell.vtp ploydata files.
 

diff --git a/man/docstring/mcds.make_ome_tiff.md b/man/docstring/mcds.make_ome_tiff.md
@@ -3,13 +3,26 @@
 
 ## input:
 ```
-            cell_attribute: strings; default is 'ID', which will result in a segmentation mask.
-                column name within cell dataframe.
-                the column data type has to be numeric (bool, int, float) and can't be string.
+            cell_attribute: strings; default is 'ID', which will result in a
+                cell segmentation mask.
+                column name within the cell dataframe.
+                the column data type has to be numeric (bool, int, float)
+                and cannot be string.
+                the result will be stored as 32 bit float.
+
+            conc_cutoff: dictionary string to real; default is an empty dictionary.
+                if a contour from a substrate not should be cut by greater
+                than zero (shifted to integer 1), another cutoff value can be
+                specified here.
+
+            focus: set of strings; default is a None
+                set of substrate and cell_type names to specify what will be
+                translated into ome tiff format.
+                if None, all substrates and cell types will be processed.
 
             file: boolean; default True
-                if True, an ome tiff file is output.
-                if False, a numpy array with shape czyx is output.
+                if True, an ome tiff file is the output.
+                if False, a numpy array with shape czyx is the output.
 
 ```
 

diff --git a/man/docstring/mcdsts.make_ome_tiff.md b/man/docstring/mcdsts.make_ome_tiff.md
@@ -3,13 +3,25 @@
 
 ## input:
 ```
-            cell_attribute: strings; default is 'ID', with will result in a segmentation mask.
-                column name within cell dataframe.
-                the column data type has to be numeric (bool, int, float) and can't be string.
+            cell_attribute: strings; default is 'ID', which will result in a
+                cell segmentation mask.
+                column name within the cell dataframe.
+                the column data type has to be numeric (bool, int, float)
+                and cannot be string.
+                the result will be stored as 32 bit float.
+
+            conc_cutoff: dictionary string to real; default is an empty dictionary.
+                if a contour from a substrate not should be cut by greater
+                than zero (shifted to integer 1), another cutoff value can be specified here.
+
+            focus: set of strings; default is a None
+                set of substrate and cell_type names to specify what will be
+                translated into ome tiff format.
+                if None, all substrates and cell types will be processed.
 
             file: boolean; default True
-                if True, an ome tiff file is output.
-                if False, a numpy array with shape tczyx is output.
+                if True, an ome tiff file is the output.
+                if False, a numpy array with shape tczyx is the output.
 
             collapse: boole; default True
                 should all mcds time steps from the time series be collapsed
@@ -22,6 +34,7 @@
 ```
             a_tczyx_img: numpy array or ome tiff file.
 
+
 ```
 
 ## description:
-Original file line number
+Diff line change
@@ Expand Up / @@ -29,7 +29,7 @@ cd path/to/PhysiCell @@
     ```
     ```bash
     make data-cleanup
-    python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'data_timeseries_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
+    python3 -c"import pathlib, pcdl, shutil; pcdl.install_data(); s_ipath=str(pathlib.Path(pcdl.__file__).parent.resolve()/'output_2d'); shutil.copytree(s_ipath, 'output', dirs_exist_ok=True)"
     ```
@@ Expand Down @@