pyvcell 0.0.1__py3-none-any.whl

pyvcell/foo.py

@@ -0,0 +1,17 @@
+def foo(bar: str) -> str:
+    """Summary line.
+
+    Extended description of function.
+
+    Args:
+        bar: Description of input argument.
+
+    Returns:
+        Description of return value
+    """
+
+    return bar
+
+
+if __name__ == "__main__":  # pragma: no cover
+    pass

pyvcell/simdata/main.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+import typer
+
+from pyvcell.simdata.mesh import CartesianMesh
+from pyvcell.simdata.simdata_models import DataFunctions, PdeDataSet
+from pyvcell.simdata.zarr_writer import write_zarr
+
+app = typer.Typer()
+
+
+@app.command(name="vc_to_zarr", help="Convert a VCell FiniteVolume simulation dataset to Zarr")
+def n5_to_zarr(
+    sim_data_dir: Path = typer.Argument(..., help="path to vcell dataset directory"),
+    sim_id: int = typer.Argument(..., help="simulation id (e.g. 946368938)"),
+    job_id: int = typer.Argument(..., help="job id (e.g. 0"),
+    zarr_path: Path = typer.Argument(..., help="path to zarr dataset to write to"),
+) -> None:
+    pde_dataset = PdeDataSet(base_dir=sim_data_dir, log_filename=f"SimID_{sim_id}_{job_id}_.log")
+    pde_dataset.read()
+    data_functions = DataFunctions(function_file=sim_data_dir / f"SimID_{sim_id}_{job_id}_.functions")
+    data_functions.read()
+    mesh = CartesianMesh(mesh_file=sim_data_dir / f"SimID_{sim_id}_{job_id}_.mesh")
+    mesh.read()
+
+    write_zarr(pde_dataset=pde_dataset, data_functions=data_functions, mesh=mesh, zarr_dir=zarr_path)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

pyvcell/simdata/mesh.py

@@ -0,0 +1,224 @@
+import zlib
+from pathlib import Path
+
+import numpy as np
+
+from pyvcell.simdata.vtk.vismesh import Box3D
+
+
+class CartesianMesh:
+    """
+    reads the .mesh file and extracts the mesh information
+
+    Example .mesh file:
+    Version 1.2
+    CartesianMesh {
+        //              X          Y          Z
+        Size           71         71         25
+        Extent 74.239999999999995 74.239999999999995         26
+        Origin          0          0          0
+
+        VolumeRegionsMapSubvolume {
+        6
+        //VolRegID   SubvolID     Volume
+                 0          0 124767.54117864356 //ec
+                 1          1 14855.904388351477 //cytosol
+                 2          1 1.2185460680272107 //cytosol
+                 3          1 1.2185460680272107 //cytosol
+                 4          1 1.2185460680272107 //cytosol
+                 5          2 3673.9163951019395 //Nucleus
+        }
+
+        MembraneRegionsMapVolumeRegion {
+        5
+        //MemRegID    VolReg1    VolReg2    Surface
+                 0          1          0 4512.8782874369472
+                 1          2          0 1.7113582585034091
+                 2          3          0 1.7113582585033937
+                 3          4          0 1.711358258503394
+                 4          5          1 1306.5985272332098
+        }
+
+        VolumeElementsMapVolumeRegion {
+        126025 Compressed
+        789CEDDD8D72DBC81100612389DFFF9573572A5912B9BF2066A66176B32A57B12CE22B8022E5DD11
+        F5EB9799999999999999999999999999999999999999999999999999999999999999999999999999
+        ...
+        3333338B8F3625C09A5BE069281EE2BC0BC543D530FA907034666666666666666666666666666666
+        6666666666666666666666667F67FF07ABF56A9C
+        }
+
+        MembraneElements {
+        7817
+        //Indx Vol1 Vol2 Conn0 Conn1 Conn2 Conn3 MemRegID
+             0 6710 11751     5   507   493     1        0
+             1 6711 11752     6     0   494   510        0
+             2 6771 11812    10   524   503     3        0
+             3 6772 11813    11     2   505   527        0
+             4 6780 11821    16   533   508     5        0
+             ....
+            7808 109155 104114  7807  7805  7792  7806        4
+            7809 104179 104180  7810  7551  7798  7811        4
+            7810 104251 104180  7812  7551  7809    -1        4
+            7811 109221 104180    -1  7809  7799  7813        4
+            7812 104252 104181  7815  7553  7810    -1        4
+            7813 109222 104181    -1  7811  7800  7816        4
+            7814 104183 104182  7815  7556  7802  7816        4
+            7815 104253 104182  7814  7554  7812    -1        4
+            7816 109223 104182    -1  7813  7801  7814        4
+        }
+    }
+    """
+
+    mesh_file: Path
+    size: list[int]  # [x, y, z]
+    extent: list[float]  # [x, y, z]
+    origin: list[float]  # [x, y, z]
+    volume_regions: list[tuple[int, int, float, str]]  # list of tuples (vol_reg_id, subvol_id, volume, domain_name)
+    membrane_regions: list[tuple[int, int, int, float]]  # list of tuples (mem_reg_id, vol_reg1, vol_reg2, surface)
+
+    # membrane_element[m,:] = [idx, vol1, vol2, conn0, conn1, conn2, conn3, mem_reg_id]
+    membrane_elements: np.ndarray  # shape (num_membrane_elements, 8)
+
+    # volume_region_map[m] = vol_reg_id
+    volume_region_map: np.ndarray  # shape (size[0] * size[1] * size[2],)
+
+    def __init__(self, mesh_file: Path) -> None:
+        self.mesh_file = mesh_file
+        self.size = []
+        self.extent = []
+        self.origin = []
+        self.volume_regions = []
+        self.membrane_regions = []
+        # self.membrane_elements
+        self.volume_region_map = np.array([], dtype=np.uint8)
+
+    @property
+    def dimension(self) -> int:
+        if self.size[1] == 1 and self.size[2] == 1:
+            return 1
+        elif self.size[2] == 1:
+            return 2
+        else:
+            return 3
+
+    def read(self) -> None:
+        # read file as lines and parse
+        with self.mesh_file.open("r") as f:
+            # get line enumerator from f
+
+            iter_lines = iter(f.readlines())
+
+            if next(iter_lines) != "Version 1.2\n":
+                raise RuntimeError("Expected 'Version 1.2' at the beginning of the file")
+            if next(iter_lines) != "CartesianMesh {\n":
+                raise RuntimeError("Expected 'CartesianMesh {' after version")
+            if next(iter_lines) != "\t//              X          Y          Z\n":
+                raise RuntimeError("Expected coordinate comment line")
+
+            size_line = next(iter_lines).split()
+            if size_line[0] == "Size":
+                self.size = [int(size_line[1]), int(size_line[2]), int(size_line[3])]
+
+            extent_line = next(iter_lines).split()
+            if extent_line[0] == "Extent":
+                self.extent = [float(extent_line[1]), float(extent_line[2]), float(extent_line[3])]
+
+            origin_line = next(iter_lines).split()
+            if origin_line[0] == "Origin":
+                self.origin = [float(origin_line[1]), float(origin_line[2]), float(origin_line[3])]
+
+            while next(iter_lines) != "\tVolumeRegionsMapSubvolume {\n":
+                pass
+            num_volume_regions = int(next(iter_lines))
+            _header_line = next(iter_lines)
+            self.volume_regions = []
+            for _i in range(num_volume_regions):
+                parts = next(iter_lines).split()
+                self.volume_regions.append((int(parts[0]), int(parts[1]), float(parts[2]), parts[3].strip("/")))
+
+            while next(iter_lines) != "\tMembraneRegionsMapVolumeRegion {\n":
+                pass
+            num_membrane_regions = int(next(iter_lines))
+            _header_line = next(iter_lines)
+            self.membrane_regions = []
+            for _i in range(num_membrane_regions):
+                parts = next(iter_lines).split()
+                self.membrane_regions.append((int(parts[0]), int(parts[1]), int(parts[2]), float(parts[3])))
+
+            while next(iter_lines) != "\tVolumeElementsMapVolumeRegion {\n":
+                pass
+            compressed_line = next(iter_lines).split()
+            num_volume_elements = int(compressed_line[0])
+            if compressed_line[1] != "Compressed":
+                raise ValueError("Expected 'Compressed' in VolumeElementsMapVolumeRegion")
+            # read HEX lines until "}" line, and concatenate into one string, then convert to bytes and decompress
+            hex_lines = []
+            while True:
+                line = next(iter_lines)
+                if line.strip() == "}":
+                    break
+                hex_lines.append(line.strip())
+            hex_string: str = "".join(hex_lines).strip()
+            compressed_bytes = bytes.fromhex(hex_string)
+            uncompressed_bytes: bytes = zlib.decompress(compressed_bytes)
+            self.volume_region_map = np.frombuffer(uncompressed_bytes, dtype="<u2")  # unsigned 2-byte integers
+            if self.volume_region_map.shape[0] != self.size[0] * self.size[1] * self.size[2]:
+                raise ValueError("Expected number of volume elements to match the size of volume region map")
+            if num_volume_elements != self.volume_region_map.shape[0]:
+                raise ValueError("Expected number of volume elements to match the size of volume region map")
+            if set(np.unique(self.volume_region_map)) != {v[0] for v in self.volume_regions}:
+                raise ValueError("Expected volume region map to have the same unique values as volume regions")
+
+            while next(iter_lines).strip() != "MembraneElements {":
+                pass
+            num_membrane_elements = int(next(iter_lines))
+            self.membrane_elements = np.zeros((num_membrane_elements, 8), dtype=np.int32)
+            _header_line = next(iter_lines)
+            mem_index = 0
+            while True:
+                line = next(iter_lines)
+                if line.strip() == "}":
+                    break
+                parts = line.split()
+                idx = int(parts[0])
+                vol1 = int(parts[1])
+                vol2 = int(parts[2])
+                conn0 = int(parts[3])
+                conn1 = int(parts[4])
+                conn2 = int(parts[5])
+                conn3 = int(parts[6])
+                mem_reg_id = int(parts[7])
+                self.membrane_elements[mem_index, :] = [idx, vol1, vol2, conn0, conn1, conn2, conn3, mem_reg_id]
+                mem_index += 1
+            if self.membrane_elements.shape != (num_membrane_elements, 8):
+                raise RuntimeError("Expected membrane elements to have the correct shape")
+            if set(np.unique(self.membrane_elements[:, 7])) != {v[0] for v in self.membrane_regions}:
+                raise RuntimeError("Expected volume region ids in membrane elements to match volume regions")
+
+    def get_volume_element_box(self, i: int, j: int, k: int) -> Box3D:
+        x_lo = self.origin[0] + i * self.extent[0] / self.size[0]
+        y_lo = self.origin[1] + j * self.extent[1] / self.size[1]
+        z_lo = self.origin[2] + k * self.extent[2] / self.size[2]
+        x_hi = self.origin[0] + (i + 1) * self.extent[0] / self.size[0]
+        y_hi = self.origin[1] + (j + 1) * self.extent[1] / self.size[1]
+        z_hi = self.origin[2] + (k + 1) * self.extent[2] / self.size[2]
+        return Box3D(x_lo, y_lo, z_lo, x_hi, y_hi, z_hi)
+
+    def get_membrane_region_index(self, mem_element_index: int) -> int:
+        return int(self.membrane_elements[mem_element_index, 7])
+
+    def get_membrane_region_ids(self, volume_domain_name: str) -> set[int]:
+        return {
+            mem_reg_id
+            for mem_reg_id, vol_reg1, vol_reg2, surface in self.membrane_regions
+            if self.volume_regions[vol_reg1][3] == volume_domain_name
+            or self.volume_regions[vol_reg2][3] == volume_domain_name
+        }
+
+    def get_volume_region_ids(self, volume_domain_name: str) -> set[int]:
+        return {
+            vol_reg_id
+            for vol_reg_id, subvol_id, volume, domain_name in self.volume_regions
+            if domain_name == volume_domain_name
+        }

pyvcell/simdata/postprocessing.py

@@ -0,0 +1,191 @@
+from enum import IntEnum
+from pathlib import Path
+
+import numpy as np
+from h5py import Dataset, Group
+from h5py import File as H5File
+
+
+class StatisticType(IntEnum):
+    AVERAGE = 0
+    TOTAL = 1
+    MIN = 2
+    MAX = 3
+
+
+class ImageMetadata:
+    name: str
+    group_path: str
+    extents: np.ndarray
+    origin: np.ndarray
+    shape: tuple[int, ...]
+
+    def __init__(self, name: str, group_path: str):
+        self.name = name
+        self.group_path = group_path
+
+    def get_dataset(self, hdf5_file: H5File, time_index: int) -> Dataset:
+        group_path_object = hdf5_file[self.group_path]
+        if not isinstance(group_path_object, Group):
+            raise TypeError(f"Expected a group at {self.group_path} but found {type(group_path_object)}")
+        image_group: Group = group_path_object
+        dataset_path_object = image_group[f"time{time_index:06d}"]
+        if not isinstance(dataset_path_object, Dataset):
+            raise TypeError(
+                f"Expected a dataset at {self.group_path}/time{time_index:06d} but found {type(dataset_path_object)}"
+            )
+        image_ds: Dataset = dataset_path_object
+        return image_ds
+
+    def read(self, f: H5File) -> None:
+        group_path_object = f[self.group_path]
+        if not isinstance(group_path_object, Group):
+            raise TypeError(f"Expected a group at {self.group_path} but found {type(group_path_object)}")
+        image_group: Group = group_path_object
+
+        # get attributes from the group
+        extents_list = []
+        origin_list = []
+        if "ExtentX" in image_group.attrs:
+            extents_list.append(image_group.attrs["ExtentX"])
+        if "ExtentY" in image_group.attrs:
+            extents_list.append(image_group.attrs["ExtentY"])
+        if "ExtentZ" in image_group.attrs:
+            extents_list.append(image_group.attrs["ExtentZ"])
+        if "OriginX" in image_group.attrs:
+            origin_list.append(image_group.attrs["OriginX"])
+        if "OriginY" in image_group.attrs:
+            origin_list.append(image_group.attrs["OriginY"])
+        if "OriginZ" in image_group.attrs:
+            origin_list.append(image_group.attrs["OriginZ"])
+        self.extents = np.array(extents_list)
+        self.origin = np.array(origin_list)
+        self.shape = self.get_dataset(f, 0).shape
+
+
+class VariableInfo:
+    var_index: int
+    var_name: str  # e.g. "C_cyt"
+    stat_channel: int
+    statistic_type: StatisticType  # e.g. StatisticType.AVERAGE
+    stat_var_name: str  # e.g. "C_cyt_average"
+    stat_var_unit: str  # e.g. "uM"
+
+    def __init__(self, stat_var_name: str, stat_var_unit: str, stat_channel: int, var_index: int):
+        self.stat_var_name = stat_var_name
+        self.stat_var_unit = stat_var_unit
+        self.stat_channel = stat_channel
+        self.var_index = var_index
+        # stat_var_name is in the form of "C_cyt_average" so remove _average to get the variable name
+        stat_type_raw = stat_var_name.split("_")[-1]
+        self.statistic_type = StatisticType[stat_type_raw.upper()]
+        self.var_name = stat_var_name.replace("_" + stat_type_raw, "")
+
+
+class PostProcessing:
+    postprocessing_hdf5_path: Path
+    times: np.ndarray
+    variables: list[VariableInfo]
+    statistics: np.ndarray  # shape (times, vars, stats) where status is average=0, total=1, min=2, max=3
+    image_metadata: list[ImageMetadata]
+
+    def __init__(self, postprocessing_hdf5_path: Path):
+        self.postprocessing_hdf5_path = postprocessing_hdf5_path
+        self.variables = []
+        self.image_metadata = []
+
+    def read(self) -> None:
+        # read the file as hdf5
+        with H5File(name=self.postprocessing_hdf5_path, mode="r") as file:  # type: ignore[call-arg]
+            # read dataset with path /PostProcessing/Times
+            postprocessing_times_object = file["/PostProcessing/Times"]
+            if not isinstance(postprocessing_times_object, Dataset):
+                raise TypeError(
+                    f"Expected a dataset at /PostProcessing/Times but found {type(postprocessing_times_object)}"
+                )
+            times_ds: Dataset = postprocessing_times_object
+            # read array from times dataset into a ndarray
+            self.times = times_ds[()]
+
+            # read attributes from group /PostProcessing/VariableStatistics
+            # data is flat, so we can read the attributes directly, so name and units for each channel are separate
+            #
+            # key=comp_0_name, value=b'C_cyt_average'
+            # key=comp_0_unit, value=b'uM'
+            # key=comp_1_name, value=b'C_cyt_total'
+            # key=comp_1_unit, value=b'molecules'
+            # key=comp_2_name, value=b'C_cyt_min'
+            # key=comp_2_unit, value=b'uM'
+            # key=comp_3_name, value=b'C_cyt_max'
+            # key=comp_3_unit, value=b'uM'
+            #
+            var_stats_grp_object = file["/PostProcessing/VariableStatistics"]
+            if not isinstance(var_stats_grp_object, Group):
+                raise TypeError(
+                    f"Expected a group at /PostProcessing/VariableStatistics but found {type(var_stats_grp_object)}"
+                )
+            var_stats_grp: Group = var_stats_grp_object
+            # gather stat_var_name and stat_var_unit for each channel into dictionaries by channel
+            var_name_by_channel: dict[int, str] = {}
+            var_unit_by_channel: dict[int, str] = {}
+            for k, v in var_stats_grp.attrs.items():
+                parts = k.split("_")
+                channel = int(parts[1])
+                if not isinstance(v, bytes):
+                    raise TypeError(f"Expected a bytes object for attribute {k} but found {type(v)}")
+                value = v.decode("utf-8")
+                if parts[2] == "name":
+                    var_name_by_channel[channel] = value
+                elif parts[2] == "unit":
+                    var_unit_by_channel[channel] = value
+            # combine into a single list of VariableInfo objects, one for each channel
+            self.variables = [
+                VariableInfo(
+                    stat_var_name=var_name_by_channel[i],
+                    stat_var_unit=var_unit_by_channel[i],
+                    stat_channel=i,
+                    var_index=i // 4,
+                )
+                for i in range(len(var_name_by_channel))
+            ]
+
+            # within /PostProcessing/VariableStatistics, there are datasets for each time point
+            # PostProcessing/VariableStatistics
+            # PostProcessing/VariableStatistics/time000000
+            # PostProcessing/VariableStatistics/time000001
+            # PostProcessing/VariableStatistics/time000002
+            # PostProcessing/VariableStatistics/time000003
+            # PostProcessing/VariableStatistics/time000004
+
+            # we can read the data for each time point into a list of ndarrays
+            statistics_raw: np.ndarray = np.zeros((len(self.times), len(self.variables)))
+            for time_index in range(len(self.times)):
+                time_ds_object = var_stats_grp[f"time{time_index:06d}"]
+                if not isinstance(time_ds_object, Dataset):
+                    raise TypeError(
+                        f"Expected a dataset at /PostProcessing/VariableStatistics/time{time_index:06d} "
+                        f"but found {type(time_ds_object)}"
+                    )
+                time_ds: Dataset = time_ds_object
+                statistics_raw[time_index, :] = time_ds[()]
+
+            # reshape the statistics_raw into a 3D array (times, vars, stats)
+            self.statistics = statistics_raw.reshape((len(self.times), len(self.variables) // 4, 4))
+
+            # get list of child groups from /PostProcessing which are not Times or VariableStatistics
+            # e.g. /PostProcessing/fluor
+            postprocessing_dataset = file["/PostProcessing"]
+            if not isinstance(postprocessing_dataset, Group):
+                raise TypeError(f"Expected a group at /PostProcessing but found {type(postprocessing_dataset)}")
+            image_groups = [k for k in postprocessing_dataset if k not in ["Times", "VariableStatistics"]]
+
+            # for each image group, read the metadata to allow reading later
+            for image_group in image_groups:
+                metadata = ImageMetadata(group_path=f"/PostProcessing/{image_group}", name=image_group)
+                metadata.read(file)
+                self.image_metadata.append(metadata)
+
+    def read_image_data(self, image_metadata: ImageMetadata, time_index: int) -> np.ndarray:
+        with H5File(name=self.postprocessing_hdf5_path, mode="r") as file:  # type: ignore[call-arg]
+            image_ds = image_metadata.get_dataset(hdf5_file=file, time_index=time_index)
+            return np.array(image_ds[()])