PhysiCell-Tools · elmbeech · Oct 23, 2025 · Aug 4, 2025 · Aug 4, 2025 · Aug 15, 2025
diff --git a/README.md b/README.md
@@ -125,6 +125,12 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
 + evt generate lineage tree graph output files.
 
 ## Release Notes:
++ 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.
+
 + version 4.0.4 (2025-07-23): elmbeech/physicelldataloader
     + command line commands now return **error code 0** if the command runs successfully.
 

diff --git a/man/TUTORIAL_python3_graph.md b/man/TUTORIAL_python3_graph.md
@@ -45,7 +45,7 @@ print(sorted(g.nodes.keys())[0:4])
 print(sorted(g.edges.keys())[0:4])
 ```
 ```python
-g.nodes['node_0']   # {'cell_type': 'cancer_cell', 'dead': 0, 'oxygen': 25.304510426523084, 'pressure': 10.519314516003435}
+g.nodes['node_0']   # {'cell_type': 'default', 'dead': 0, 'oxygen': 25.304510426523084, 'pressure': 10.519314516003435}
 ```
 ```python
 g.edges[('node_0', 'node_1')]   # {'label': 'edge_0_1', 'distance_microns': 15}

diff --git a/man/TUTORIAL_python3_ometiff.md b/man/TUTORIAL_python3_ometiff.md
@@ -77,7 +77,7 @@ img.shape  # (25, 2, 1, 200, 300)
 img.dims  # <Dimensions [T: 25, C: 2, Z: 1, Y: 200, X: 300]>
 ```
 ```python
-img.channel_names  # [np.str_('oxygen'), np.str_('cancer_cell')]
+img.channel_names  # [np.str_('oxygen'), np.str_('default')]
 ```
 
 That's it. The rest is analysis!
diff --git a/man/TUTORIAL_python3_timestep.md b/man/TUTORIAL_python3_timestep.md
@@ -241,13 +241,13 @@ We can retrieve a list of all cell types processed in the simulation,
 ordered by cell type ID.
 
 ```python
-mcds.get_celltype_list()  # ['cancer_cell']
+mcds.get_celltype_list()  # ['default']
 ```
 
 We can retrieve a dictionary that maps cell type IDs to labels.
 
 ```python
-mcds.get_celltype_dict()  # {'0': 'cancer_cell'}
+mcds.get_celltype_dict()  # {'0': 'default'}
 ```
 
 And we can retrieve an alphabetically ordered list with all cell agent attributes outputted by PhysiCell, loadable with mcds.get\_cell\_df().

diff --git a/man/docstring/mcds.__init__.md b/man/docstring/mcds.__init__.md
@@ -29,7 +29,7 @@
                 should physiboss state data be loaded, if found?
                 setting physiboss to False will use less memory and speed up processing.
 
-            settingxml: string; default PhysiCell_settings.xml
+            settingxml: string; default False
                 the settings.xml that is loaded, from which the cell type ID
                 label mapping, is extracted, if this information is not found
                 in the output xml file.

diff --git a/man/docstring/mcds.plot_scatter.md b/man/docstring/mcds.plot_scatter.md
@@ -6,6 +6,16 @@
             focus: string; default is 'cell_type'
                 column name within cell dataframe.
 
+            cat_drop: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be dropped for the dataframe.
+                Attention: when the cat_keep parameter is given, then
+                the cat_drop parameter has to be an empty set!
+
+            cat_keep: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be kept in the dataframe.
+
             z_slice: floating point number; default is 0.0
                 z-axis position to slice a 2D xy-plain out of the
                 3D substrate concentration mesh. if z_slice position

diff --git a/man/docstring/mcdsts.__init__.md b/man/docstring/mcdsts.__init__.md
@@ -29,7 +29,7 @@
                 should physiboss state data be loaded, if found?
                 setting physiboss to False will use less memory and speed up processing.
 
-            settingxml: string; default PhysiCell_settings.xml
+            settingxml: string; default False
                 the settings.xml that is loaded, from which the cell type ID
                 label mapping, is extracted, if this information is not found
                 in the output xml file.

diff --git a/man/docstring/mcdsts.plot_scatter.md b/man/docstring/mcdsts.plot_scatter.md
@@ -8,6 +8,16 @@
             focus: string; default is 'cell_type'
                 column name within cell dataframe.
 
+            cat_drop: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be dropped for the dataframe.
+                Attention: when the cat_keep parameter is given, then
+                the cat_drop parameter has to be an empty set!
+
+            cat_keep: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be kept in the dataframe.
+
             z_slice: floating point number; default is 0.0
                 z-axis position to slice a 2D xy-plain out of the 3D mesh.
                 if z_slice position is not an exact mesh center coordinate,

diff --git a/man/docstring/mcdsts.plot_timeseries.md b/man/docstring/mcdsts.plot_timeseries.md
@@ -21,6 +21,16 @@
                 cell: dataframe will be retrieved through the mcds.get_cell_df function.
                 conc: dataframe will be retrieved through the mcds.get_conc_df function.
 
+            cat_drop: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be dropped for the dataframe.
+                Attention: when the cat_keep parameter is given, then
+                the cat_drop parameter has to be an empty set!
+
+            cat_keep: set of strings; default is an empty set
+                if focus is a categorical attribute,
+                set of category labels to be kept in the dataframe.
+
             z_slice: floating point number; default is None
                 z-axis position to slice a 2D xy-plain out of the 3D mesh.
                 if z_slice position numeric but not an exact mesh center coordinate,
@@ -92,14 +102,16 @@
                 to be able to generate movies from the images.
 
             ext: string; default is None
-                output image format. possible formats are None, jpeg, png, and tiff.
-                if None then the matplotlib figure is returned by the function
-                and not written to file.
+                output format.
+                possible image formats are jpeg, jpg, png, tif, and tiff.
+                for retrieving a datafarme file use csv.
+                any other string or a number returns a pandas dataframe object.
+                None returnes a matplotlib figure object.
 
             figbgcolor: string; default is None which is transparent (png)
                 or white (jpeg, tiff).
                 figure background color.
-                only relevant if ext not is None.
+                only relevant if ext specifies an image file.
 
             **kwargs: possible additional keyword arguments input,
                 handled by the pandas series plot function.

diff --git a/man/docstring/pcdl_get_anndata.md b/man/docstring/pcdl_get_anndata.md
@@ -41,7 +41,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_get_cell_attribute.md b/man/docstring/pcdl_get_cell_attribute.md
@@ -43,7 +43,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_get_cell_attribute_list.md b/man/docstring/pcdl_get_cell_attribute_list.md
@@ -24,7 +24,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to True for more text output, while
                         processing. default is False.

diff --git a/man/docstring/pcdl_get_cell_df.md b/man/docstring/pcdl_get_cell_df.md
@@ -29,7 +29,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_get_celltype_list.md b/man/docstring/pcdl_get_celltype_list.md
@@ -16,7 +16,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to True for more text output, while
                         processing. default is False.

diff --git a/man/docstring/pcdl_get_unit_dict.md b/man/docstring/pcdl_get_unit_dict.md
@@ -19,7 +19,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_make_cell_vtk.md b/man/docstring/pcdl_make_cell_vtk.md
@@ -35,7 +35,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_make_graph_gml.md b/man/docstring/pcdl_make_graph_gml.md
@@ -43,7 +43,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_make_ome_tiff.md b/man/docstring/pcdl_make_ome_tiff.md
@@ -32,7 +32,7 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.

diff --git a/man/docstring/pcdl_plot_scatter.md b/man/docstring/pcdl_plot_scatter.md
@@ -2,11 +2,12 @@
 usage: pcdl_plot_scatter [-h] [--custom_data_type [CUSTOM_DATA_TYPE ...]]
                          [--microenv MICROENV] [--physiboss PHYSIBOSS]
                          [--settingxml SETTINGXML] [-v VERBOSE]
-                         [--z_slice Z_SLICE] [--z_axis Z_AXIS [Z_AXIS ...]]
-                         [--alpha ALPHA] [--cmap CMAP] [--title TITLE]
-                         [--grid GRID] [--legend_loc LEGEND_LOC]
-                         [--xlim XLIM [XLIM ...]] [--ylim YLIM [YLIM ...]]
-                         [--xyequal XYEQUAL] [--s S]
+                         [--cat_drop [CAT_DROP ...]]
+                         [--cat_keep [CAT_KEEP ...]] [--z_slice Z_SLICE]
+                         [--z_axis Z_AXIS [Z_AXIS ...]] [--alpha ALPHA]
+                         [--cmap CMAP] [--title TITLE] [--grid GRID]
+                         [--legend_loc LEGEND_LOC] [--xlim XLIM [XLIM ...]]
+                         [--ylim YLIM [YLIM ...]] [--xyequal XYEQUAL] [--s S]
                          [--figsizepx FIGSIZEPX [FIGSIZEPX ...]] [--ext EXT]
                          [--figbgcolor FIGBGCOLOR]
                          [path] [focus]
@@ -39,10 +40,20 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.
+  --cat_drop [CAT_DROP ...]
+                        if focus is a categorical attribute, set of category
+                        labels, strings separated by space, to be dropped for
+                        the dataframe. Attention: when the cat_keep parameter
+                        is given, then the cat_drop parameter has to be an
+                        empty string! default is an empty string.
+  --cat_keep [CAT_KEEP ...]
+                        if focus is a categorical attribute, set of category
+                        labels, strings separated by space, to be kept in the
+                        dataframe. default is an empty string.
   --z_slice Z_SLICE     z-axis position to slice a 2D xy-plain out of the 3D
                         mesh. if z_slice position numeric but not an exact
                         mesh center coordinate, then z_slice will be adjusted

diff --git a/man/docstring/pcdl_plot_timeseries.md b/man/docstring/pcdl_plot_timeseries.md
@@ -2,8 +2,9 @@
 usage: pcdl_plot_timeseries [-h] [--custom_data_type [CUSTOM_DATA_TYPE ...]]
                             [--microenv MICROENV] [--physiboss PHYSIBOSS]
                             [--settingxml SETTINGXML] [-v VERBOSE]
-                            [--frame FRAME] [--z_slice Z_SLICE] [--logy LOGY]
-                            [--ylim YLIM [YLIM ...]]
+                            [--frame FRAME] [--cat_drop [CAT_DROP ...]]
+                            [--cat_keep [CAT_KEEP ...]] [--z_slice Z_SLICE]
+                            [--logy LOGY] [--ylim YLIM [YLIM ...]]
                             [--secondary_y SECONDARY_Y [SECONDARY_Y ...]]
                             [--subplots SUBPLOTS] [--sharex SHAREX]
                             [--sharey SHAREY] [--linestyle LINESTYLE]
@@ -49,14 +50,24 @@ options:
                         type ID label mapping, is extracted, if this
                         information is not found in the output xml file. set
                         to None or False if the xml file is missing! default
-                        is PhysiCell_settings.xml.
+                        is False.
   -v VERBOSE, --verbose VERBOSE
                         setting verbose to False for less text output, while
                         processing. default is True.
   --frame FRAME         to specifies the data dataframe. cell: dataframe will
                         be retrieved through the mcds.get_cell_df function.
                         conc: dataframe will be retrieved through the
                         mcds.get_conc_df function. default is cell.
+  --cat_drop [CAT_DROP ...]
+                        if focus is a categorical attribute, set of category
+                        labels to be dropped for the dataframe. Attention:
+                        when the cat_keep parameter is given, then the
+                        cat_drop parameter has to be an empty string! default
+                        is an empty string.
+  --cat_keep [CAT_KEEP ...]
+                        if focus is a categorical attribute, set of category
+                        labels to be kept in the dataframe. default is an
+                        empty string.
   --z_slice Z_SLICE     z-axis position to slice a 2D xy-plain out of the 3D
                         mesh. if z_slice position numeric but not an exact
                         mesh center coordinate, then z_slice will be adjusted
@@ -84,7 +95,7 @@ options:
                         matplotlib line style {-, --, .-, :} string. default
                         is - .
   --linewidth LINEWIDTH
-                        line width in points, integer. default is None.
+                        line width in points, float. default is None.
   --cmap CMAP           matplotlib colormap string from https://matplotlib.org
                         /stable/tutorials/colors/colormaps.html . default is
                         None.
@@ -103,8 +114,9 @@ options:
                         x and y will be rounded to the nearest even number, to
                         be able to generate movies from the images. default is
                         640 480.
-  --ext EXT             output image format. possible formats are jpeg, png,
-                        and tiff. default is jpeg.
+  --ext EXT             output format. possible image formats are jpeg, jpg,
+                        png, tif, and tiff. for retrieving a datafarme file
+                        use csv. default is jpeg.
   --figbgcolor FIGBGCOLOR
                         figure background color. None is transparent (png) or
                         white (jpeg, tiff). default is None.

diff --git a/pcdl/VERSION.py b/pcdl/VERSION.py
@@ -1 +1 @@
-__version__ = '4.0.4'
+__version__ = '4.0.5'