cap-anndata 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

cap_anndata/reader.py

@@ -1,44 +1,57 @@
-import logging
-import contextlib
-import h5py
-
-from cap_anndata import CapAnnData
-
-
-logger = logging.getLogger(__name__)
-
-
-@contextlib.contextmanager
-def read_h5ad(file_path: str, edit: bool = False):
-    """
-    This is the main read method for CapAnnData.
-    Must be used in 'with' context.
-    """
-    mode = "r+" if edit else "r"
-    logger.debug(f"Read file {file_path} mode={mode} in context...")
-
-    try:
-        file = h5py.File(file_path, mode)
-        cap_adata = CapAnnData(file)
-        logger.debug(f"Successfully read anndata file path {file_path}")
-        yield cap_adata
-
-    except Exception as error:
-        logger.error(f"Error during read anndata file at path: {file_path}, error = {error}!")
-        raise error
-
-    finally:
-        file.close()
-        logger.debug("AnnData closed!")
-
-
-def read_directly(file_path: str, edit: bool = False) -> CapAnnData:
-    """
-    Must be used only in specific cases.
-    User is responsible to close the h5py file when the work with CapAnnData instance done.
-    """
-    mode = "r+" if edit else "r"
-    logger.debug(f"Read file {file_path} mode={mode} directly...")
-    file = h5py.File(file_path, mode)
-    cap_adata = CapAnnData(file)
-    return cap_adata
+import logging
+import h5py
+import warnings
+
+from cap_anndata import CapAnnData
+
+
+logger = logging.getLogger(__name__)
+
+
+def read_h5ad(file_path: str, edit: bool = False):
+    """
+    This is the main read method for CapAnnData.
+    Must be used in 'with' context.
+    """
+    mode = "r+" if edit else "r"
+    logger.debug(f"Read file {file_path} mode={mode} in context...")
+
+    try:
+        file = h5py.File(file_path, mode)
+        cap_adata = CapAnnData(file)
+        logger.debug(f"Successfully read anndata file path {file_path}")
+        return cap_adata
+
+    except Exception as error:
+        logger.error(
+            f"Error during read anndata file at path: {file_path}, error = {error}!"
+        )
+        raise error
+
+
+def deprecated(message):
+    def deprecated_decorator(func):
+        def deprecated_func(*args, **kwargs):
+            warnings.warn(
+                "{} is a deprecated function. {}".format(func.__name__, message),
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            warnings.simplefilter("default", DeprecationWarning)
+            return func(*args, **kwargs)
+
+        return deprecated_func
+
+    return deprecated_decorator
+
+
+# TODO: remove deprecated function
+@deprecated(
+    "It will be removed in the next version of package. Please replace it with `read_h5ad`."
+)
+def read_directly(file_path: str, edit: bool = False) -> CapAnnData:
+    """
+    Must be used only in specific cases.
+    User is responsible to close the h5py file when the work with CapAnnData instance done.
+    """
+    return read_h5ad(file_path, edit)

{cap_anndata-0.2.2.dist-info → cap_anndata-0.3.1.dist-info}/LICENSE

@@ -1,28 +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.
+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.3.1.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.1
+Name: cap_anndata
+Version: 0.3.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'
+
+# CAP-AnnData: Partial I/O for AnnData (.h5ad) Files
+
+## 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.3.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+cap_anndata/__init__.py,sha256=WRAQEDsWTvLbJWVUA5FmKCVrD2GN4oRd5I3c8jc9ajo,197
+cap_anndata/backed_df.py,sha256=bMNsArbPjA-TN7eQB4-9Y2l3s8o03-dM4hPnOR9tROc,2622
+cap_anndata/backed_dict.py,sha256=Hb1SjnKuQ13mBUitQ5sL3kmcQ1j3GgB19r3yXkC0oIo,1019
+cap_anndata/cap_anndata.py,sha256=uQh49Kwu2cE4-ebgOvb78mMGA_afkZcsr71j6f8EX2I,20600
+cap_anndata/reader.py,sha256=UpZBCjaS4-K2w_9m6IuYetO9LwmEEJ5KvAw9aAoMRno,1609
+cap_anndata-0.3.1.dist-info/LICENSE,sha256=XXTH6JikkxH7Gqy9VEj4crSizuwxzv04ROzkQ-ZS6o4,1532
+cap_anndata-0.3.1.dist-info/METADATA,sha256=688YuF45IuOvu1Hqxbt_O1aeYkoMX4tjV0b2hb1WY8I,2304
+cap_anndata-0.3.1.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+cap_anndata-0.3.1.dist-info/top_level.txt,sha256=GKi_Uk4LUhXwWBfFCTIyJvEoJqFREt_4uH4CWgeLsg4,12
+cap_anndata-0.3.1.dist-info/RECORD,,

{cap_anndata-0.2.2.dist-info → cap_anndata-0.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (75.3.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

cap_anndata/backed_uns.py

@@ -1,28 +0,0 @@
-from typing import List, Any
-
-
-class CapAnnDataUns(dict):
-    __keys_to_remove: List[str] = []
-
-    def __delitem__(self, __key: Any) -> None:
-        self.__keys_to_remove.append(__key)
-        return super().__delitem__(__key)
-
-    def __setitem__(self, __key: Any, __value: Any) -> None:
-        if __key in self.__keys_to_remove:
-            self.__keys_to_remove.remove(__key)
-        return super().__setitem__(__key, __value)
-
-    @property
-    def keys_to_remove(self):
-        return self.__keys_to_remove
-
-    def pop(self, __key: Any, __default: Any = None) -> Any:
-        if __key in self:
-            self.__keys_to_remove.append(__key)
-        return super().pop(__key, __default)
-
-    def popitem(self) -> Any:
-        item = super().popitem()
-        self.__keys_to_remove.append(item[0])
-        return item

cap_anndata-0.2.2.dist-info/METADATA

@@ -1,253 +0,0 @@
-Metadata-Version: 2.1
-Name: cap_anndata
-Version: 0.2.2
-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
-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.26.3
-Requires-Dist: pandas ~=2.2.0
-Requires-Dist: anndata ~=0.10.5
-Requires-Dist: h5py ~=3.5.0
-Provides-Extra: dev
-Requires-Dist: pytest >=8.0.0 ; extra == 'dev'
-Requires-Dist: setuptools ~=69.1.1 ; extra == 'dev'
-
-# CAP-AnnData: Enhanced Partial I/O for AnnData Files
-
-## Overview
-CAP-AnnData enriches the AnnData ecosystem by offering tailored functionalities for partial reading and writing of AnnData files. This enhancement allows for selective manipulation of sections such as `obs`, `var`, `X`, `raw.X`, `obsm`, and `uns` without the need for loading entire datasets into memory. Leveraging AnnData's native methods, CAP-AnnData aims to maintain backward compatibility while improving efficiency, especially useful for large-scale single-cell genomics data.
-
-## Getting Started
-
-### Installation
-Install CAP-AnnData via pip:
-
-```commandline
-pip install -U cap-anndata
-```
-
-### Running Tests
-Ensure the integrity and reliability of CAP-AnnData on your system by running the unit tests via `pytest` from the root of the repo.
-
-```commandline
-pip install pytest
-pytest test
-```
-
-Make sure Python 3.9 or newer is used, along with all requirements specified in requirements.txt
-
-## How-TO:
-
-#### 1. Access AnnData File DataFrames
-
-##### Basic Reading
-By default, `CapAnnData` does not automatically read any data. To begin working with dataframes, you need to explicitly read the data from the AnnData file. You can read the entire dataframe or select specific columns. For partial reading, provide a list of column names.
-
-```python
-from cap_anndata import read_h5ad
-
-file_path = "your_data.h5ad"
-with read_h5ad(file_path=file_path, edit=False) as cap_adata:
-    # Get the list of all obs columns in AnnData file
-    cap_adata.obs_keys()  # ['a', 'b', 'c']
-    # Read all columns of 'obs'
-    cap_adata.read_obs()
-    # Get the list of columns of DataFrame in memory
-    cap_adata.obs.columns  # ['a', 'b', 'c']
-
-    # Get the list of all var columns in AnnData file
-    cap_adata.var_keys()  # ['d', 'e', 'f']
-    # Read specific columns of 'var'
-    cap_adata.read_var(columns=['d'])
-    cap_adata.var.columns  # ['d']
-    # Read additional column
-    cap_adata.read_var(columns=['e'])
-    cap_adata.var.columns  # ['d', 'e']
-
-    # Read column and reset the in-memory DataFrame before that
-    cap_adata.read_var(columns=['f'], reset=True)
-    cap_adata.var.columns  # ['f']
-
-    # Read no columns of raw.var (only the index)
-    cap_adata.raw.read_var(columns=[])
-```
-
-##### Difference between `obs_keys()` and `obs.columns`
-`obs_keys()` returns the list of columns in the on-disc AnnData file, while `obs.columns` returns the list of columns in the in-memory DataFrame. The two lists may differ if you read only specific columns. If you modify the in-memory DataFrame, the `obs_keys()` will reflect the changes. BTW it is recommended to check the `obs_keys()` before the `overwrite()` call to avoid the AnnData file damage.
-
-If a column doesn't exist in the file, no error will be raised but the column will be missing in the resulting DataFrame. So, the list of columns saying more like "try to read this columns from the file". It is needed because we there is no way yet to check if the column exists before the read. Exactly the same behavior is for the `var_keys()` and `var.columns`. 
-
-#### 2. Modify the AnnData File DataFrames In-Place
-
-You can directly modify the dataframe by adding, renaming, or removing columns.
-
-```python
-# Create a new column
-cap_adata.obs['new_col'] = [value1, value2, value3]
-
-# Rename a column
-cap_adata.obs.rename_column('old_col_name', 'new_col_name')
-
-# Remove a column
-cap_adata.obs.remove_column('col_to_remove')
-```
-
-After modifications, you can overwrite the changes back to the AnnData file. If a value doesn't exist, it will be created.
-Note: `read_h5ad` must be called with `edit=True` argument to open `.h5ad` file in `r+` mode.
-
-```python
-# overwrite all values which were read
-cap_adata.overwrite()
-
-# overwrite choosen fields
-cap_adata.overwrite(['obs', 'var'])
-```
-
-The full list of supported fields: `obs`, `var`, `raw.var`, `obsm`, `uns`.
-
-#### 3. How to Read Few Columns but Overwrite One in a Dataframe
-
-The only way yet to do that is to drop all columns from in-memory dataframe (with `pandas.drop`!) before the call of `overwrite` method.
-
-```python
-# Read specific columns
-cap_adata.read_obs(columns=['cell_type', 'sample'])
-
-# Drop a column in-memory
-# DON'T USE remove_column here!
-cap_adata.obs.drop(columns='sample', inplace=True)
-
-# Overwrite changes
-cap_adata.overwrite(['obs'])
-
-# NOTE that the line 
-# cap_adata.read_obs(columns=['sample'], reset=True)
-# Will override in-memory changes with values from the AnnData file
-```
-
-#### 4. How to work with X and raw.X
-
-The CapAnnData package won't read any field by default. However, the `X` and `raw.X` will be linked to the backed matrices automatically upon the first request to those fields. 
-The X object will be returned as the `h5py.Dataset` or `AnnData.experimental.sparse_dataset`.
-
-```python
-with read_h5ad(file_path=file_path, edit=False) as cap_adata:
-    # self.X is None here
-    cap_adata = CapAnnData(file)  
-
-    # will return the h5py.Dataset or CSRDataset
-    x = cap_adata.X  
-
-    # The same for raw.X
-    raw_x = cap_adata.raw.X 
-
-    # take whole matrix in memory
-    x = cap_adata.X[:] 
-```
-
-The CapAnnData supports the standard `numpy`/`h5py` sclising rules
-
-```python
-# slice rows
-s_ = np.s_[0:5]
-# slice columns
-s_ = np.s_[:, 0:5]
-# boolean mask + slicing
-mask = np.array([i < 5 for i in range(adata.shape[0])])
-s_ = np.s_[mask, :5]
-```
-
-#### 5. How to handle obsm embeddings matrixes
-
-By the default the CapAnnData will not read the embeddings matrix. 
-The link to the h5py objects will be created upon the first call of the `.obsm` property. 
-Alike the AnnData package the call like `cap_adata.obsm["X_tsne"]` will not return the in-memory matrix but will return the backed version instead. 
-It is possible to get the information about the name and shape of the embeddings without taking the whole matrix in the memory.
-
-```python
-with read_h5ad(file_path=file_path, edit=False) as cap_adata:
-    # will return the list of strings
-    obsm_keys = cap_adata.obsm_keys()  
-
-    # return the shape of the matrix in backed mode
-    embeddings = obsm_keys[0]
-    shape = cap_adata.obsm[embeddings].shape  
-
-    # take the whole matrix in memory
-    matrix = cap_adata.obsm[embeddings][:]
-```
-
-#### 6. How to read and modify uns section
-
-The `CapAnnData` class will lazely link the uns section upon the first call but ***WILL NOT*** read it into memory. Instead, the dictionary of the pairs `{'key': "__NotLinkedObject"}` will be creted. It allow to get the list of keys before the actual read. To read the uns section in the memory the `.read_uns(keys)` method must be called.
-
-```python
-with read_h5ad(file_path=file_path, edit=True) as cap_adata:
-    # will return the keys() object
-    keys = cap_adata.uns.keys()  
-
-    # read in memory the first key only
-    cap_adata.read_uns([keys[0]])
-
-    # read the whole uns section into memory
-    cap_adata.read_uns()
-```
-
-Since the `.uns` section is in the memory (partially or completely) we can work with it as with the regular `dict()` python object. The main feature of the `CapAnnDataUns` class which inherited from `dict` is the tracking of the keys which must be removed from the `.h5ad` file upon overwrite. 
-
-```python
-# get the value
-v = cap_adata.uns["key1"]
-v = cap_adata.uns.get("key1")
-
-# modify values
-cap_adata.uns["key1"] = "new_value"
-
-# create new keys
-cap_adata.uns["new_key"] = "value"
-
-# remove keys
-cap_adata.uns.pop("key1")  # is recommended way
-del cap_adata.uns.pop("key2")
-cap_adata.uns.popitem()
-```
-
-To save `uns` changes the method `CapAnnData.overwrite()` must be called. 
-
-```python
-cap_adata.overwrite()  # all in-memory fields will be overwritten
-cap_adata.overwrite(["uns"])  # overwrite the uns secion only
-```
-
-#### 7. Join and Merge DataFrames
-
-Cap-AnnData provides enhanced methods for joining and merging dataframes, preserving column order and data integrity
-
-```python
-from cap_anndata import CapAnnDataDF
-import pandas as pd
-
-data1 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
-data2 = pd.DataFrame({'D': [7, 8, 9], 'E': [10, 11, 12]})
-cap_anndata_df1 = CapAnnDataDF.from_df(data1, column_order=['A', 'B', 'C'])
-
-cap_df = cap_anndata_df1.join(data2, how='left')
-
-cap_df.columns  # ['A', 'B', 'D', 'E']
-cap_df.column_order  # ['A', 'B', 'C', 'D', 'E']
-
-data3 = pd.DataFrame({'A': [2, 3, 4], 'D': [10, 11, 12]})
-cap_df = cap_anndata_df1.merge(data3, on='A')
-
-cap_df.columns  # ['A', 'B', 'D']
-cap_df.column_order  # ['A', 'B', 'C', 'D']
-cap_df.shape  # (2, 3)
-```

cap_anndata-0.2.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-cap_anndata/__init__.py,sha256=l9lvFpcMsQksp8_dI-fjUgrImoMdztbu3jVSdmxNPmA,205
-cap_anndata/backed_df.py,sha256=06wZwEjszFQ8lkvy6-GgD_SD14idu9857RtlfMQiBjE,2691
-cap_anndata/backed_uns.py,sha256=Tfxoz3RgcgENf4SvxFOox9w048K2QmBTh1VbAf4yqVI,854
-cap_anndata/cap_anndata.py,sha256=fEaIwWIKKDJpIsQ7cwOfUTmUReIyryv5qRDqRjRsWhU,10185
-cap_anndata/reader.py,sha256=kg9xoS_S0gY6WpsHE8PwGMa14VXh9Ibqjw4bwoerYsE,1267
-cap_anndata-0.2.2.dist-info/LICENSE,sha256=JAV0w7TBl6wQe9iFcCKjAWgpurym0f-Q0B75zm2PrKw,1560
-cap_anndata-0.2.2.dist-info/METADATA,sha256=h41dgoz3w2rDHnic828FahjEoKq1lt_Bi1jm-ZX-goA,9569
-cap_anndata-0.2.2.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-cap_anndata-0.2.2.dist-info/top_level.txt,sha256=GKi_Uk4LUhXwWBfFCTIyJvEoJqFREt_4uH4CWgeLsg4,12
-cap_anndata-0.2.2.dist-info/RECORD,,