trackcell 0.1.1__tar.gz

trackcell-0.1.1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.3
+Name: trackcell
+Version: 0.1.1
+Summary: A Python package for processing single-cell and spatial transcriptomics data
+Author: Zan Yuan
+Author-email: yfinddream@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: geopandas (>=1.1.1,<2.0.0)
+Requires-Dist: imageio (>=2.31.0,<3.0.0)
+Requires-Dist: numpy (>=1.24.0,<2.0.0)
+Requires-Dist: pandas (>=2.1.0,<3.0.0)
+Requires-Dist: scanpy (>=1.9.0,<2.0.0)
+Requires-Dist: shapely (>=2.0.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# TrackCell
+
+A Python package for processing and vis single-cell and spatial transcriptomics data.
+
+## Installation
+
+```bash
+pip install trackcell
+```
+
+## Usage
+
+### Reading SpaceRanger Output
+
+```python
+import trackcell as tcl
+
+# Read SpaceRanger output
+adata = tcl.io.read_hd_cellseg(
+    datapath="SpaceRanger4.0/Cse1/outs/segmented_outputs",
+    sample="Cse1"
+)
+
+# The resulting AnnData object contains:
+# - Expression matrix in .X
+# - Cell metadata in .obs
+# - Gene metadata in .var
+# - Spatial coordinates in .obsm["spatial"]
+# - Tissue images in .uns["spatial"][sample]["images"]
+# - Scalefactors in .uns["spatial"][sample]["scalefactors"]
+```
+
+
+## Development
+
+
+## License
+
+

trackcell-0.1.1/README.md

@@ -0,0 +1,38 @@
+# TrackCell
+
+A Python package for processing and vis single-cell and spatial transcriptomics data.
+
+## Installation
+
+```bash
+pip install trackcell
+```
+
+## Usage
+
+### Reading SpaceRanger Output
+
+```python
+import trackcell as tcl
+
+# Read SpaceRanger output
+adata = tcl.io.read_hd_cellseg(
+    datapath="SpaceRanger4.0/Cse1/outs/segmented_outputs",
+    sample="Cse1"
+)
+
+# The resulting AnnData object contains:
+# - Expression matrix in .X
+# - Cell metadata in .obs
+# - Gene metadata in .var
+# - Spatial coordinates in .obsm["spatial"]
+# - Tissue images in .uns["spatial"][sample]["images"]
+# - Scalefactors in .uns["spatial"][sample]["scalefactors"]
+```
+
+
+## Development
+
+
+## License
+

trackcell-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[tool.poetry]
+name = "trackcell"
+version = "0.1.1"
+description = "A Python package for processing single-cell and spatial transcriptomics data"
+authors = ["Zan Yuan <yfinddream@gmail.com>"]
+readme = "README.md"
+packages = [{include = "trackcell"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+scanpy = "^1.9.0"
+geopandas = "^1.1.1"
+pandas = "^2.1.0"
+shapely = "^2.0.0"
+imageio = "^2.31.0"
+numpy = "^1.24.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0.0"
+black = "^23.0.0"
+flake8 = "^6.0.0"
+mypy = "^1.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true 

trackcell-0.1.1/trackcell/__init__.py

@@ -0,0 +1,18 @@
+"""
+TrackCell: A Python package for processing single-cell and spatial transcriptomics data.
+
+This package provides tools for:
+- IO: Data input/output operations
+- PL: Processing and analysis tools
+- TL: Utility and helper functions
+"""
+
+__version__ = "0.1.1"
+__author__ = "Zan Yuan"
+__email__ = "yfinddream@gmail.com"
+
+from . import io
+from . import pl
+from . import tl
+
+__all__ = ["io", "pl", "tl"] 

trackcell-0.1.1/trackcell/io/__init__.py

@@ -0,0 +1,9 @@
+"""
+IO module for TrackCell package.
+
+This module provides functions for reading and writing single-cell and spatial transcriptomics data.
+"""
+
+from .spatial import read_hd_cellseg
+
+__all__ = ["read_hd_cellseg"] 

trackcell-0.1.1/trackcell/io/spatial.py

@@ -0,0 +1,182 @@
+"""
+Spatial transcriptomics data input/output functions.
+
+This module provides functions for reading and writing spatial transcriptomics data,
+particularly from SpaceRanger output.
+"""
+
+import scanpy as sc
+import geopandas as gpd
+import pandas as pd
+from shapely import wkt, geometry
+import numpy as np
+import json
+import imageio.v3 as iio
+import os
+from typing import Optional
+import ast
+
+def read_hd_cellseg(
+    datapath: str,
+    sample: Optional[str] = None,
+    cell_segmentations_file: str = "graphclust_annotated_cell_segmentations.geojson",
+    matrix_file: str = "filtered_feature_cell_matrix.h5",
+    hires_image_file: str = "spatial/tissue_hires_image.png",
+    lowres_image_file: str = "spatial/tissue_lowres_image.png",
+    scalefactors_file: str = "spatial/scalefactors_json.json"
+) -> sc.AnnData:
+    """
+    Read 10X HD SpaceRanger cell segmentation output and create an AnnData object with spatial information.
+    
+    This function reads the output from SpaceRanger pipeline and creates an AnnData object
+    that includes spatial coordinates, cell segmentations, and tissue images.
+    
+    Parameters
+    ----------
+    datapath : str or Path
+        Path to the SpaceRanger output directory containing segmented outputs.
+    sample : str, optional
+        Sample name. If None, will be inferred from the path.
+    cell_segmentations_file : str, default "cell_segmentations.geojson"
+        Name of the cell segmentations file.
+    matrix_file : str, default "filtered_feature_cell_matrix.h5"
+        Name of the filtered feature-cell matrix file.
+    hires_image_file : str, default "spatial/tissue_hires_image.png"
+        Path to the high-resolution tissue image relative to datapath.
+    lowres_image_file : str, default "spatial/tissue_lowres_image.png"
+        Path to the low-resolution tissue image relative to datapath.
+    scalefactors_file : str, default "scalefactors_json.json"
+        Name of the scalefactors JSON file.
+    
+    Returns
+    -------
+    sc.AnnData
+        AnnData object containing:
+        - Expression matrix in .X
+        - Cell metadata in .obs
+        - Gene metadata in .var
+        - Spatial coordinates in .obsm["spatial"]
+        - Tissue images in .uns["spatial"][sample]["images"]
+        - Scalefactors in .uns["spatial"][sample]["scalefactors"]
+    
+    Examples
+    --------
+    >>> import trackcell.io as tcio
+    >>> adata = tcio.read_hd_cellseg("SpaceRanger4.0/Case1/outs/segmented_outputs", sample="Cas1")
+    >>> print(adata)
+    AnnData object with n_obs × n_vars = 1000 × 2000
+        obs: 'cellid'
+        obsm: 'spatial'
+        uns: 'spatial'
+    
+    Notes
+    -----
+    This function expects the SpaceRanger output to have the following structure:
+    - cell_segmentations.geojson: Cell segmentation polygons
+    - filtered_feature_cell_matrix.h5: Expression matrix
+    - spatial/tissue_hires_image.png: High-resolution tissue image
+    - spatial/tissue_lowres_image.png: Low-resolution tissue image
+    - scalefactors_json.json: Image scaling factors
+    """
+    
+    # Convert to Path object for easier handling
+    datapath = os.path.abspath(datapath)
+    
+    # If sample is not provided, try to infer from path
+    if sample is None:
+        sample = 'sample'
+    
+    # Read cell segmentations
+    gdf_seg = gpd.read_file(f'{datapath}/{cell_segmentations_file}')
+    df = pd.DataFrame(gdf_seg)
+    df['cellid'] = df['cell_id'].apply(lambda x: f"cellid_{str(x).zfill(9)}-1")
+    
+    # Read expression matrix
+    adata = sc.read_10x_h5(f'{datapath}/{matrix_file}')
+    
+    # Align cell segmentations with expression data
+    adata = adata[adata.obs_names.isin(df['cellid']),:]
+    
+    df = df.set_index("cellid").loc[adata.obs_names].reset_index()
+    
+    # Convert geometry strings to shapely objects if needed
+    if isinstance(df["geometry"].iloc[0], str):
+        df["geometry"] = df["geometry"].apply(wkt.loads)
+    
+    # Extract centroid coordinates
+    df["x"] = df["geometry"].apply(lambda poly: poly.centroid.x)
+    df["y"] = df["geometry"].apply(lambda poly: poly.centroid.y)
+    
+    # Store spatial coordinates
+    adata.obsm["spatial"] = np.array(df[["x", "y"]])
+    
+    if 'classification' in df.columns:
+        if isinstance(df['classification'].iloc[0], str):
+            classifications = df['classification'].apply(ast.literal_eval)
+        else:
+            classifications = df['classification']
+        adata.obs['classification'] = [i['name'] for i in classifications]
+        adata.uns['classification_colors'] = convert_classification_to_color_dict(df, 'classification')
+
+    # Read tissue images
+    try:
+        hires_img = iio.imread(f'{datapath}/{hires_image_file}')
+        lowres_img = iio.imread(f'{datapath}/{lowres_image_file}')
+    except FileNotFoundError as e:
+        print(f"Warning: Could not load tissue images: {e}")
+        hires_img = None
+        lowres_img = None
+    
+    # Initialize spatial metadata
+    adata.uns["spatial"] = {}
+    adata.uns["spatial"][sample] = {}
+    
+    # Load scalefactors
+    try:
+        with open(f'{datapath}/{scalefactors_file}', 'r', encoding='utf-8') as file:
+            scalefactor = json.load(file)
+    except FileNotFoundError as e:
+        print(f"Warning: Could not load scalefactors: {e}")
+        scalefactor = {}
+    
+    # Store images and scalefactors
+    if hires_img is not None and lowres_img is not None:
+        adata.uns["spatial"][sample]["images"] = {
+            "hires": hires_img,
+            "lowres": lowres_img
+        }
+    
+    adata.uns["spatial"][sample]["scalefactors"] = scalefactor
+    
+    return adata 
+
+
+
+def convert_classification_to_color_dict(df, classification_col='classification'):
+    """
+    将包含分类信息的DataFrame列转换为颜色字典
+    
+    参数:
+        df: pandas DataFrame
+        classification_col: 包含分类信息的列名 (默认'classification')
+    
+    返回:
+        dict: {分类名称: 十六进制颜色代码}
+    """
+    # 确保数据是字典格式（如果是字符串则转换为字典）
+    classifications = df[classification_col]
+    
+    # 获取唯一的分类
+    unique_classes = classifications.explode().unique()
+    
+    # 创建颜色字典
+    color_dict = {}
+    for cls in unique_classes:
+        if isinstance(cls, dict):  # 确保是字典格式
+            name = cls['name']
+            rgb = cls['color']
+            # 将RGB列表转换为十六进制颜色代码
+            hex_color = '#{:02x}{:02x}{:02x}'.format(*rgb)
+            color_dict[name] = hex_color
+    
+    return color_dict

trackcell-0.1.1/trackcell/pl/__init__.py

@@ -0,0 +1,8 @@
+"""
+PL (Processing) module for TrackCell package.
+
+This module provides functions for processing and analyzing single-cell and spatial transcriptomics data.
+"""
+
+# Add processing functions here as they are implemented
+__all__ = [] 

trackcell-0.1.1/trackcell/tl/__init__.py

@@ -0,0 +1,8 @@
+"""
+TL (Tools) module for TrackCell package.
+
+This module provides utility and helper functions for single-cell and spatial transcriptomics data analysis.
+"""
+
+# Add utility functions here as they are implemented
+__all__ = []