Merge pull request #45 from elmbeech/master

pcdl release v4.1.6

Author: elmbeech

README.md

@@ -130,15 +130,19 @@ Developers, please make pull requests to the https://github.com/elmbeech/physice
 
 
 ## Release Notes:
-+ version 4.1.5 (2026-04-05)
+
++ version 4.1.6 (2026-08-20): elmbeech/physicelldataloader
+    + pcdl installs now by default lightweight with only the core dependencies; users are prompted to install optional libraries if necessary. special thanks to Heber Rocha!
+
++ version 4.1.5 (2026-04-05): elmbeech/physicelldataloader
     + bugfix library dependencies and library versions.
 
-+ version 4.1.4 (2026-04-04)
++ version 4.1.4 (2026-04-04): elmbeech/physicelldataloader
     + 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):
++ version 4.1.3 (2026-03-21): elmbeech/physicelldataloader
     + new **pcdl.pccmap** color map. this is an adaptation of the physicell pathology paint by number color map.
     + new TimeStep **get_pcdl_version** function.
 

man/HOWTO.md

@@ -8,6 +8,14 @@ Below you will find information about how to install, load, update, uninstall, a
 ```bash
 pip3 install pcdl
 ```
+This installs pcdl light weight: only the libraries needed to load PhysiCell output into pandas dataframes and to render basic contour and scatter plots (matplotlib, numpy, pandas, scipy).
+A handful of pcdl functions (e.g. get\_anndata) rely on other libraryes (anndata).
+If you call such a function and a necessary library is missing, the function will prompt you to install it.
+
+To install pcdl with all optional dependencies at once, run:
+```bash
+pip3 install pcdl[full]
+```
 
 
 ## How to load the pcdl library?

man/TUTORIAL_blender.md

@@ -19,7 +19,7 @@ This is why the ext parameter explicitly has to be set.
 pcdl_make_conc_vtk output
 ```
 ```bash
-pcdl_make_cell_vtk output --ext .vtp  # blender bvtk nodes compatible filename and extension.
+pcdl_make_cell_vtk output --ext .vtp  # generate blender bvtk nodes compatible filename and extension!
 ```
 
 ### Generate vtk files from within python
@@ -29,7 +29,7 @@ import pcdl
 
 mcdsts = pcdl.TimeSeries('output/')
 mcdsts.make_conc_vtk()
-mcdsts.make_cell_vtk(ext='.vtp')  # blender bvtk nodes compatible filename and extension.
+mcdsts.make_cell_vtk(ext='.vtp')  # generate blender bvtk nodes compatible filename and extension!
 ```
 
 ### Blender vtk nodes plugin installation
@@ -49,6 +49,21 @@ including workspace setup.
 5. tkXMLPolyDataReader FileName: path/to/output00000000.vtp
 6. VTKtoBlenderMesh: click Update Node
 
+### Load vtk polynomial data vtk files as a time course
+
+Special thank to Danyon Gedris from the Stein-O'Brien Lab, who figuring all of this out!
+
+1. In the BVTK Node Tree Workspace from the previous section, right click Add / Custom / TimeSelector.
+2. Connect vtkXMLPolyDataReader output with input TimeSelector.
+3. Connect TimeSelector output with input VTKtoBlenderMesh.
+4. In the BVTK Node Editor, press N to open the sidebar.
+5. Select the Inspect tab and change: Update Mode → Update All Automatically.
+6. Click update node on each element in the BVTK Node Editor and force update upstream on VTKtoBlenderMesh.
+7. Set your scene frame range to:
++ Start = 1 (this selects output00000000.vtp).
++ End = # of .vtp files in the sequence (the last output file number plus 1).
+8. Press play on the animation.
+
 ### Load rectilinear grid vtk files
 
 I was not able to bridge that data yet.

man/TUTORIAL_matlab_octave.md

@@ -33,7 +33,7 @@ pcdl_get_cell_df output
 df_conc = readtable("output/timeseries_conc.csv")
 ```
 ```matlab
-df_cell = readtable("output/timeseries_conc.csv")
+df_cell = readtable("output/timeseries_cell.csv")
 ```
 
 

pcdl/VERSION.py

@@ -1 +1 @@
-__version__ = '4.1.5'
+__version__ = '4.1.6'

pcdl/dependency.py

@@ -0,0 +1,59 @@
+######
+# title: dependency.py
+#
+# language: python3
+# date: 2026-08-14
+# license: BSD-3-Clause
+# author: Elmar Bucher, Heber Rocha, Claude Anthropic
+#
+# description:
+#   pcdl, by default, only installs and imports lightweight core dependencies.
+#   the code below deals with installation and import of the more specialized
+#   heavyweight libraries.
+######
+
+
+# library
+import importlib
+
+
+# function
+def optional_import(s_module, s_attr=None, s_pip=None, s_caller=None):
+    """
+    input:
+        s_module: string
+            dotted module path to import, e.g. 'anndata' or 'bioio.writers'.
+
+        s_attr: string; default None
+            if given, equivalent to from s_module import s_attr.
+
+        s_pip: string; default None
+            pip install name for the module, if this differs from s_module
+            (e.g. s_module='skimage' but s_pip='scikit-image').
+            if None, the first dot-separated part of s_module is used.
+
+        s_caller: string; default None
+            name of the calling pcdl function, to mention in the error message.
+
+    output:
+        the imported module, or, if s_attr is given, the requested attribute
+        of the imported module.
+
+    description:
+        function lazily load an optional pcdl dependency.
+        if the library is not installed, an error message is raised,
+        pointing the user to install the missing library.
+    """
+    s_pip = s_module.split('.')[0] if (s_pip is None) else s_pip
+    try:
+        o_module = importlib.import_module(s_module)
+    except ImportError as e:
+        s_fct = s_caller if not (s_caller is None) else ' '
+        raise ModuleNotFoundError(
+            f"Error{s_fct}: this functionality requires the optional dependency '{s_pip}', which is not installed.\n" +
+            f"pcdl was installed light weight (default), without this and other heavyweight, specialized libraries.\n" +
+            f"to fix this, either:\n" +
+            f"+ install the missing library manually: pip install {s_pip}\n" +
+            f"+ or install pcdl with all optional dependencies: pip install pcdl[full]\n"
+        ) from e
+    return o_module if (s_attr is None) else getattr(o_module, s_attr)

pcdl/neuromancer.py

@@ -39,14 +39,18 @@
 
 # library
 import argparse
-from bioio import BioImage
 import matplotlib as mpl
-import neuroglancer
-import neuroglancer.cli
 import numpy as np
-from skimage import exposure, util
 import sys
 
+# lazy loading heavyweight: bioio, neuroglancer, and scikit-image
+from pcdl.dependency import optional_import
+BioImage = optional_import('bioio', s_attr='BioImage', s_pip='bioio', s_caller='pcdl.render_neuroglancer')
+neuroglancer = optional_import('neuroglancer', s_caller='pcdl.render_neuroglancer')
+optional_import('neuroglancer.cli', s_caller='pcdl.render_neuroglancer')  # binds neuroglancer.cli as attribute
+exposure = optional_import('skimage.exposure', s_pip='scikit-image', s_caller='pcdl.render_neuroglancer')
+util = optional_import('skimage.util', s_pip='scikit-image', s_caller='pcdl.render_neuroglancer')
+
 
 # functions
 def ometiff2neuro(

pcdl/output_data.py

@@ -23,7 +23,7 @@
 import os
 import pathlib
 import pcdl
-import requests
+from pcdl.dependency import optional_import
 import shutil
 import tarfile
 
@@ -40,6 +40,9 @@ class install_data:
         function to install a 2D and 3D PhysiCell output test dataset.
     """
     def __init__(self):
+        # load optional dependency
+        requests = optional_import('requests', s_caller='pcdl.install_data')
+
         # get pcdl library installation path
         s_path = str(pathlib.Path(pcdl.__file__).parent).replace('\\','/') + '/'
 

pcdl/timeseries.py

@@ -16,15 +16,13 @@
 
 
 # load libraries
-import anndata as ad
-import bioio_base
-from bioio.writers import OmeTiffWriter
 import glob
 import matplotlib.pyplot as plt
 import numpy as np
 import os
 import pandas as pd
 from pcdl import render_neuroglancer
+from pcdl.dependency import optional_import
 from pcdl.timestep import TimeStep, es_coor_cell, es_coor_conc, _anndextract
 from pcdl.VERSION import __version__
 import platform
@@ -1176,6 +1174,11 @@ def make_ome_tiff(self, cell_attribute='ID', conc_cutoff={}, focus=None, file=Tr
 
         # output 11 ometiff file
         elif (file and collapse):  # 11
+            # load optional dependency
+            OmeTiffWriter = optional_import('bioio.writers', s_attr='OmeTiffWriter', s_pip='bioio', s_caller='TimeSeries.make_ome_tiff')
+            bioio_base = optional_import('bioio_base', s_pip='bioio', s_caller='TimeSeries.make_ome_tiff')
+
+            # numpy array
             a_tczyx_img = np.array(l_tczyx_img)
             if self.verbose:
                 print('a_tczyx_img shape:', a_tczyx_img.shape)
@@ -1661,6 +1664,9 @@ def get_anndata(self, values=1, drop=set(), keep=set(), scale='maxabs', collapse
             function to transform mcds time steps into one or many
             anndata objects for downstream analysis.
         """
+        # load optional dependency
+        ad = optional_import('anndata', s_caller='TimeSeries.get_anndata')
+
         # initialize vaiable
         l_annmcds = []
         df_anncount = None

pcdl/timestep.py

@@ -15,31 +15,22 @@
 
 
 # load library
-import anndata as ad
-import bioio_base
-from bioio.writers import OmeTiffWriter
-import geopandas as gpd
 import matplotlib.pyplot as plt
 from matplotlib import cm
 from matplotlib import colors
 try:
     import muspan as ms
 except ModuleNotFoundError:
     ms = None
-import networkx as nx
-import neuroglancer
 import numpy as np
 import os
 import pandas as pd
 from pcdl import imagine
 from pcdl import pdplt
-from pcdl import neuromancer
+from pcdl.dependency import optional_import
 from scipy import io
 from scipy import sparse
-import shapely
-import spatialdata as sd
 import sys
-import vtk
 import warnings
 import xml.etree.ElementTree as etree
 from pcdl.VERSION import __version__
@@ -223,6 +214,10 @@ def render_neuroglancer(tiffpathfile, timestep=0, intensity_cmap='gray'):
         function to load a time step from an ome tiff files, generated
         with make_ome_tiff, into neuroglancer.
     """
+    # load optional dependencies (neuromancer itself lazy loads bioio and scikit-image)
+    neuroglancer = optional_import('neuroglancer', s_caller='pcdl.render_neuroglancer')
+    from pcdl import neuromancer
+
     # start neuroglancer
     viewer = neuroglancer.Viewer()
     with viewer.txn() as state:
@@ -1404,6 +1399,9 @@ def make_conc_vtk(self, ext='_conc.vtr'):
 
             https://www.paraview.org/
         """
+        # load optional dependency
+        vtk = optional_import('vtk', s_caller='TimeStep.make_conc_vtk')
+
         # off we go.
         s_vtkfile = self.xmlfile.replace('.xml', ext)
         if self.verbose:
@@ -1896,6 +1894,9 @@ def make_cell_vtk(self, attribute=['cell_type'], ext='_cell.vtp'):
 
             https://www.paraview.org/
         """
+        # load optional dependency
+        vtk = optional_import('vtk', s_caller='TimeStep.make_cell_vtk')
+
         # off we go.
         s_vtkfile = self.xmlfile.replace('.xml', ext)
         if self.verbose:
@@ -2031,6 +2032,11 @@ def make_ome_tiff(self, cell_attribute='ID', conc_cutoff={}, focus=None, file=Tr
             https://napari.org/stable/
             https://fiji.sc/
         """
+        # load optional dependencies
+        if file:
+            OmeTiffWriter = optional_import('bioio.writers', s_attr='OmeTiffWriter', s_pip='bioio', s_caller='TimeStep.make_ome_tiff')
+            bioio_base = optional_import('bioio_base', s_pip='bioio', s_caller='TimeStep.make_ome_tiff')
+
         # handle channels
         ls_substrate = self.get_substrate_list()
         ls_celltype = self.get_celltype_list()
@@ -2404,6 +2410,9 @@ def get_anndata(self, values=1, drop=set(), keep=set(), scale='maxabs'):
             function to transform a mcds time step into an anndata object
             for downstream analysis.
         """
+        # load optional dependency
+        ad = optional_import('anndata', s_caller='TimeStep.get_anndata')
+
         # processing
         if self.verbose:
             print(f'processing: 1/1 {round(self.get_time(),9)}[min] mcds into anndata obj.')
@@ -2479,6 +2488,12 @@ def get_spatialdata(self, images={'subs'}, labels={}, points={'subs'}, shapes={'
             function to transform a mcds time step into
             a spatialdata object for downstream analysis.
         """
+        # load optional dependencies
+        ad = optional_import('anndata', s_caller='TimeStep.get_spatialdata')
+        sd = optional_import('spatialdata', s_caller='TimeStep.get_spatialdata')
+        shapely = optional_import('shapely', s_caller='TimeStep.get_spatialdata')
+        gpd = optional_import('geopandas', s_caller='TimeStep.get_spatialdata')
+
         # set table spatial element links
         s_region_subs = None
         s_region_cell = None
@@ -2720,9 +2735,12 @@ def get_muspan(self, z_slice=None, values=1, drop=set(), keep=set()):
             + https://docs.muspan.co.uk/latest/Documentation.html
         """
         # check if muspan library is installed
-        if ms is None:
+        if (ms is None) or (ms.__file__ is None):
             sys.exit(f'Error @ TimeStep.get_muspa : the muspan Multi Spatial Analysis python3 library is not installed!\nfor instructions check out : https://www.muspan.co.uk/')
 
+        # load optional dependency
+        nx = optional_import('networkx', s_caller='TimeStep.get_muspan')
+
         # get conc and cell dataframe
         df_conc = self.get_conc_df(values=values, drop=drop, keep=keep)
         df_cell = self.get_cell_df(values=values, drop=drop, keep=keep)