Merge pull request #16 from elmbeech/master

release v3.2.12

Author: elmbeech

.github/workflows/python-package.yml

@@ -0,0 +1,115 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: pytest pcdl
+run-name: ${{ github.actor }} is pytesting the pcdl library on all supported python versions and operating systems.
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        #python-version: ["3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+
+    env:
+      PYTHONPATH: /home/runner/work/physicelldataloader/physicelldataloader
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        sudo apt install ffmpeg imagemagick
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest matplotlib numpy pandas scipy requests anndata
+        #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest
+
+
+  build-macosx:
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        #python-version: ["3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+
+    env:
+      PYTHONPATH: /Users/runner/work/physicelldataloader/physicelldataloader
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      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 matplotlib numpy pandas scipy requests anndata
+        #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest
+
+
+  build-windows:
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        #python-version: ["3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+
+    env:
+      PYTHONPATH: D:\a\physicelldataloader\physicelldataloader
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      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 matplotlib numpy pandas scipy requests anndata
+        #echo 'set PYTHONPATH=D:\a\physicelldataloader\physicelldataloader' >> $GITHUB_ENV
+        #if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest
+

.gitignore

@@ -16,3 +16,5 @@ build/
 dist/
 pcdl.egg-info/
 
+# jupyter
+**/.ipynb_checkpoints/

README.md

@@ -16,7 +16,7 @@ The pcdl python3 library maintains three branches branches:
 
 
 ## Header:
-+ Language: python >= 3.6
++ Language: python [>= 3.8](https://devguide.python.org/versions/)
 + Library dependencies: anndata, matplotlib, numpy, pandas, scipy
 + Date of origin original PhysiCell-Tools python-loader: 2019-09-02
 + Date of origin pcdl fork: 2022-08-30
@@ -32,7 +32,7 @@ The pcdl python3 library maintains three branches branches:
 
 ## Tutorial:
 + Check out: [man/TUTORIAL.md](https://github.com/elmbeech/physicelldataloader/tree/master/man/TUTORIAL.md)!
-
++ Check out: [man/jupyter/pcdl\_repl\_programming.ipynb](https://github.com/elmbeech/physicelldataloader/tree/master/man/jupyter/pcdl_repl_programming.ipynb)
 
 ## Reference Manual:
 + Check out: [man/REFERENCE.md](https://github.com/elmbeech/physicelldataloader/tree/master/man/REFERENCE.md)!
@@ -67,10 +67,24 @@ Within the pcdl library, we tried to stick to the documentation policy lined out
 
 ## Road Map:
 + [vtk file format](https://docs.vtk.org/en/latest/design_documents/VTKFileFormats.html) output, maybe [stl](https://en.wikipedia.org/wiki/STL_(file_format)) and [wavefront obj](https://en.wikipedia.org/wiki/Wavefront_.obj_file) output.
-+ [GML](https://en.wikipedia.org/wiki/Graph_Modelling_Language) ([networkx](https://networkx.org/) compatible) graph output.
++ [GML](https://en.wikipedia.org/wiki/Graph_Modelling_Language) ([networkx](https://networkx.org/) and [igraph](https://igraph.org/) compatible) output.
 
 
 ## Release Notes:
++ version 3.2.12 (2023-08-12): elmbeech/physicelldatalodader
+    + add **pcdl_repl_programming.ipynb** : Jupyter notebook to give an idea about how to work with pcdl in a Python3 REPL.
+    + add github **continuous integration**, all supported python versions, all supported operating systems.
+
++ version 3.2.11 (2023-08-08): elmbeech/physicelldatalodader
+    + **pip install pcdl**: will only install the bare minimum library dependencies.
+    + **pip install pcdl[data]**: will install the minimum dependencies plus the dependencies to download the test dataset.
+    + **pip install pcdl[scverse]**: will install the minimum dependencies plus the dependencies needed to generate anndata object.
+    + **pip install pcdl[all]**: will always install all dependencies.
+    + new TimeSeries **get_annmcds_list** function, which, points to the self.l\_annmcds object.
+    + new pyMCDS **get_scatter** function split off from pyMCDSts make\_imgcell.
+    + pyMCDSts **make_imgcell** and **make_imgsubs** bug fixes.
+    + TimeStep and TimeSeries **get_anndata** evolution.
+
 + version 3.2.10 (2023-07-24): elmbeech/physicelldataloader
     + rename pyMCDSts get\_cell\_df\_columns\_states to **get_cell_df_states** for conciseness.
     + rename pyMCDSts get\_conc\_df\_columns\_states to **get_conc_df_states** for conciseness.

man/HOWTO.md

@@ -2,15 +2,23 @@
 
 ## How to install the latest physicelldataloader?
 
+Full-fledged installation, with all library dependencies installed.
 ```bash
-pip3 install pcdl
+pip3 install pcdl[all]
 ```
 
+If necessary, you can tweak your installation to make it more lightweight.
+```bash
+pip3 install pcdl  # The bare minimum. Installs only the pcdl core library dependencies.
+pip3 install pcdl[data]  # Installs pcdl core and test data library dependencies.
+pip3 install pcdl[scverse]  # Installs pcdl core and anndata library dependencies.
+pip3 install pcdl[all]  # Installs pcdl core, test data, and anndata library dependencies.
+```
 
 ## How to update to the latest physicelldataloader?
 
 ```bash
-pip3 install -U pcdl
+pip3 install -U pcdl[all]
 ```
 
 
@@ -19,6 +27,7 @@ pip3 install -U pcdl
 Note: For the pcdl library this is a two-step procedure.
 First, possibly installed test data and tutorial output will be removed.
 Then, the software will be uninstalled.
+Keep in mind that pcdl library dependencies (like anndata, matplotlib, numpy, pandas, scipy) will never be uninstalled automatically.
 
 ```bash
 python3 -c "import pcdl; pcdl.uninstall_data()"
@@ -54,7 +63,7 @@ The pcDataLoader library will thereafter act as a simple gateway to the latest i
 In future, you can just update the pcdl package to go with the latest version.
 
 ```
-pip install -U pcDataLoader pcdl
+pip install -U pcDataLoader pcdl[all]
 ```
 
 

man/REFERENCE.md

@@ -13,7 +13,7 @@ The **workhorse functions** are the ones most important for data analysis.
 Familiarize yourself with all of their parameters!
 
 
-# TimeStep
+# TimeStep Class
 ```python3
 help(pcdl.TimeStep)  # ! make class instance
 help(pcdl.TimeStep.__init__)
@@ -55,6 +55,7 @@ help(pcdl.TimeStep.get_celltype_dict)
 help(pcdl.TimeStep.get_cell_variables)
 help(pcdl.TimeStep.get_cell_df)  # ! workhorse function
 help(pcdl.TimeStep.get_cell_df_at)
+help(pcdl.TimeStep.get_scatter)  # ! workhorse function
 
 # TimeStep graphs
 help(pcdl.TimeStep.get_attached_graph_dict)  # !
@@ -74,7 +75,7 @@ help(pcdl.TimeStep.scaler)
 ```
 
 
-# TimeStep time series
+# TimeSeries Class
 ```python3
 help(pcdl.TimeSeries)  # ! make class instance
 help(pcdl.TimeSeries.__init__)
@@ -83,6 +84,7 @@ help(pcdl.TimeSeries.__init__)
 help(pcdl.TimeSeries.get_xmlfile_list)
 help(pcdl.TimeSeries.read_mcds)
 help(pcdl.TimeSeries.get_mcds_list)  # ! workhorse function
+help(pcdl.TimeSeries.get_annmcds_list)  # ! workhorse function
 
 # TimeSeries triage data
 help(pcdl.TimeSeries.get_cell_df_states)  # ! workhorse function

man/TUTORIAL.md

@@ -349,6 +349,17 @@ df.shape  # (3, 94)
 df = mcds.get_cell_df_at(x=111,y=22,z=-5.1)  # None and Warning @ pyMCDS.is_in_mesh : z = -5.1 out of bounds: z-range is (-5.0, 5.0)
 ```
 
+Additionally, there is a scatter plot function available, shaped for df\_cell dataframe content.
+```
+# scatter plot
+fig = mcds.get_scatter()  # default focus is cell_type and z_slice=0
+fig.show()
+
+fig = mcds.get_scatter('oxygen', z_slice=3.333)
+fig.show()
+```
+
+
 Since lately, PhysiCell tracks for each cell, if this cell touches other cells.\
 This data is stored in two dictionaries of sets of integers which link the corresponding cell IDs.\
 We have here a closer look at the neighbor graph because the attached graph is in this particular study not really interesting.
@@ -719,21 +730,25 @@ mcdsts = pcdl.TimeSeries(s_path)
 A mcds time series can be translated into one single anndata (default).
 ```python
 ann = mcdsts.get_anndata(states=2, scale='maxabs', collapse=True)
-print(ann)  # AnnData object with n_obs × n_vars = 24758 × 27
-            #     obs: 'ID', 'current_phase', 'cycle_model'
+print(ann)  # AnnData object with n_obs × n_vars = 889 × 26
+            #     obs: 'z_layer', 'time', 'current_phase', 'cycle_model'
             #     obsm: 'spatial'
 ```
 The output tells us that we have loaded a time series with 24758 cell (agent) snapshots and 27 features.
 And that we have spatial coordinate annotation (position\_x, position\_y, position\_z, time) of the loaded data.
 
-
-A mcds time series can be translated into a dictionary of anndata objects, where each entry is a single time step.
+A mcds time series can be translated into a chronological list of anndata objects, where each entry is a single time step.
+After running get\_anndata, you can access the objects by the get\_annmcds\_list function.
 ```python
-d_ann = mcdsts.get_anndata(states=2, scale='maxabs', collapse=False)
-d_ann.keys()  # dict_keys([0, 60, ..., 1440])
-d_ann[1440]  # AnnData object with n_obs × n_vars = 1099 × 27
-             #     obs: 'ID', 'current_phase', 'cycle_model'
-             #     obsm: 'spatial'
+l_ann = mcdsts.get_anndata(states=2, scale='maxabs', collapse=False)
+len(l_ann)  # 25
+l_ann[24]  # AnnData object with n_obs × n_vars = 1099 × 79
+           #     obs: 'z_layer', 'time', 'cell_type', 'current_death_model', 'current_phase', 'cycle_model'
+           #     obsm: 'spatial'
+
+# load all snapshots
+mcdsts.get_annmcds_list()  # YMMV! [AnnData object with n_obs × n_vars ..., ..., ... obsm: 'spatial']
+len(mcdsts.get_annmcds_list())  # 25
 ```