cap_anndata 0.5.1__tar.gz

cap_anndata-0.5.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, R. Mukhin, A. Isaev, Cell-Annotation Platform
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cap_anndata-0.5.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: cap_anndata
+Version: 0.5.1
+Summary: Partial read/write of AnnData (h5ad) files for low-memory operations with large datasets.
+Home-page: https://github.com/cellannotation/cap-anndata
+Author: R. Mukhin, A. Isaev
+Author-email: roman@ebookapplications.com
+Project-URL: Bug Tracker, https://github.com/cellannotation/cap-anndata/issues
+Project-URL: Changelog, https://github.com/cellannotation/cap-anndata/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/cellannotation/cap-anndata/blob/main/HOWTO.md
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: anndata>=0.10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: setuptools~=69.1.1; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# CAP-AnnData: Partial I/O for AnnData (.h5ad) Files
+
+[![PyPI version](https://img.shields.io/pypi/v/cap-anndata)](https://pypi.org/project/cap-anndata/) [![Build Status](https://github.com/cellannotation/cap-anndata/actions/workflows/python-app.yml/badge.svg)](https://github.com/cellannotation/cap-anndata/actions)
+
+## Overview
+CAP-AnnData offering functionalities for selective reading and writing of [AnnData](https://pypi.org/project/anndata/) 
+file fields without the need for loading entire dataset (or even entire field) into memory. 
+For example, it allows to read and modify the single `obs` column taking nothing into memory except the column itself.
+Package eager to replicate the original AnnData API as much as possible, 
+while providing additional features for efficient data manipulation for heavy datasets.
+
+## Installation
+Install CAP-AnnData via pip:
+
+```commandline
+pip install -U cap-anndata
+```
+
+## Basic Example
+
+The example below displayes how to read a single `obs` column, create new obs column and propagate it to the `.h5ad` file.
+```python
+from cap_anndata import read_h5ad
+
+file_path = "your_data.h5ad"
+with read_h5ad(file_path=file_path, edit=True) as cap_adata:
+    print(cap_adata.obs_keys())  # ['a', 'b', 'c']
+    print(cap_adata.obs) # Empty DataFrame
+    cap_adata.read_obs(columns=['a'])
+    print(cap_adata.obs.columns) # ['a']
+    cap_adata.obs['new_col'] = cap_adata.obs['a']
+    cap_adata.overwrite(fields=['obs'])
+```
+
+More example can be found in the [How-TO](https://github.com/cellannotation/cap-anndata/blob/main/HOWTO.md) file. 

cap_anndata-0.5.1/README.md

@@ -0,0 +1,35 @@
+# CAP-AnnData: Partial I/O for AnnData (.h5ad) Files
+
+[![PyPI version](https://img.shields.io/pypi/v/cap-anndata)](https://pypi.org/project/cap-anndata/) [![Build Status](https://github.com/cellannotation/cap-anndata/actions/workflows/python-app.yml/badge.svg)](https://github.com/cellannotation/cap-anndata/actions)
+
+## Overview
+CAP-AnnData offering functionalities for selective reading and writing of [AnnData](https://pypi.org/project/anndata/) 
+file fields without the need for loading entire dataset (or even entire field) into memory. 
+For example, it allows to read and modify the single `obs` column taking nothing into memory except the column itself.
+Package eager to replicate the original AnnData API as much as possible, 
+while providing additional features for efficient data manipulation for heavy datasets.
+
+## Installation
+Install CAP-AnnData via pip:
+
+```commandline
+pip install -U cap-anndata
+```
+
+## Basic Example
+
+The example below displayes how to read a single `obs` column, create new obs column and propagate it to the `.h5ad` file.
+```python
+from cap_anndata import read_h5ad
+
+file_path = "your_data.h5ad"
+with read_h5ad(file_path=file_path, edit=True) as cap_adata:
+    print(cap_adata.obs_keys())  # ['a', 'b', 'c']
+    print(cap_adata.obs) # Empty DataFrame
+    cap_adata.read_obs(columns=['a'])
+    print(cap_adata.obs.columns) # ['a']
+    cap_adata.obs['new_col'] = cap_adata.obs['a']
+    cap_adata.overwrite(fields=['obs'])
+```
+
+More example can be found in the [How-TO](https://github.com/cellannotation/cap-anndata/blob/main/HOWTO.md) file. 

cap_anndata-0.5.1/cap_anndata/__init__.py

@@ -0,0 +1,10 @@
+from .backed_df import CapAnnDataDF
+from .backed_dict import CapAnnDataDict
+from .cap_anndata import CapAnnData
+from .reader import (
+    read_directly,
+    read_h5ad,
+)
+
+
+__all__ = ["CapAnnData"]

cap_anndata-0.5.1/cap_anndata/backed_df.py

@@ -0,0 +1,85 @@
+import pandas as pd
+import numpy as np
+from typing import List, Any, Union
+
+from pandas.core.generic import bool_t
+
+try:
+    from typing import Self  # Python 3.11+
+except ImportError:
+    from typing_extensions import Self  # Python 3.10
+
+
+class CapAnnDataDF(pd.DataFrame):
+    """
+    The class to expand the pandas DataFrame behaviour to support partial
+    reading and writing of AnnData obs and var (raw.var) fields.
+    The main feature of the class is handling <column-order> attribute
+    which must be a copy of h5py.Group attribute
+    """
+
+    _metadata = ["column_order"]
+
+    def column_order_array(self) -> np.array:
+        order = self.column_order
+        if order is not None and isinstance(order, List):
+            # Convert it to numpy array of str elements
+            return np.array(order, dtype=object)
+        else:
+            return order
+
+    def rename_column(self, old_name: str, new_name: str) -> None:
+        i = np.where(self.column_order_array() == old_name)[0]
+        tmp_array = self.column_order_array().copy()
+        tmp_array[i] = new_name
+        self.column_order = tmp_array.copy()
+        self.rename(columns={old_name: new_name}, inplace=True)
+
+    def remove_column(self, col_name: str) -> None:
+        i = np.where(self.column_order_array() == col_name)[0]
+        self.column_order = np.delete(self.column_order_array(), i)
+        self.drop(columns=[col_name], inplace=True)
+
+    def __setitem__(self, key, value) -> None:
+        if key not in self.column_order_array():
+            self.column_order = np.append(self.column_order_array(), key)
+        return super().__setitem__(key, value)
+
+    @classmethod
+    def from_df(cls, df: pd.DataFrame, column_order: Union[np.array, List[str], None] = None) -> Self:
+        if column_order is None:
+            column_order = df.columns.to_numpy()
+        elif isinstance(column_order, List):
+            column_order = np.array(column_order)
+        new_inst = cls(df)
+        new_inst.column_order = column_order
+        return new_inst
+
+    def join(self, other: Any, **kwargs) -> Self:
+        result = super().join(other=other, **kwargs)
+        if isinstance(other, CapAnnDataDF):
+            new_columns = [
+                col for col in other.column_order_array() if col not in self.column_order_array()
+            ]
+        else:
+            new_columns = [col for col in other.columns if col not in self.column_order_array()]
+        column_order = np.append(self.column_order_array(), new_columns)
+        df = self.from_df(result, column_order=column_order)
+        return df
+
+    def merge(self, right, **kwargs) -> Self:
+        result = super().merge(right=right, **kwargs)
+        if isinstance(right, CapAnnDataDF):
+            new_columns = [
+                col for col in right.column_order_array() if col not in self.column_order_array()
+            ]
+        else:
+            new_columns = [col for col in right.columns if col not in self.column_order_array()]
+        column_order = np.append(self.column_order_array(), new_columns)
+        df = self.from_df(result, column_order=column_order)
+        return df
+
+    def copy(self, deep: Union[bool_t, None] = True) -> Self:
+        column_order = self.column_order_array()
+        df = self.from_df(super().copy(deep=deep), column_order=column_order)
+        return df

cap_anndata-0.5.1/cap_anndata/backed_dict.py

@@ -0,0 +1,34 @@
+from typing import Set, Any
+
+
+class CapAnnDataDict(dict):
+    __keys_to_remove: Set[str] = None
+
+    def __delitem__(self, __key: Any) -> None:
+        self.keys_to_remove.add(__key)
+        return super().__delitem__(__key)
+
+    def __setitem__(self, __key: Any, __value: Any) -> None:
+        if __value is not None:
+            if __key in self.keys_to_remove:
+                self.keys_to_remove.remove(__key)
+        else:
+            self.keys_to_remove.add(__key)
+        return super().__setitem__(__key, __value)
+
+    @property
+    def keys_to_remove(self) -> Set[str]:
+        if self.__keys_to_remove is None:
+            self.__keys_to_remove = set()
+        return self.__keys_to_remove
+
+    def pop(self, __key: Any, __default: Any = None) -> Any:
+        if __key in self:
+            self.keys_to_remove.add(__key)
+        return super().pop(__key, __default)
+
+    def popitem(self) -> Any:
+        item = super().popitem()
+        key = item[0]
+        self.keys_to_remove.add(key)
+        return item