cap-anndata 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

cap_anndata/__init__.py

@@ -1,6 +1,10 @@
 from .backed_df import CapAnnDataDF
 from .backed_uns import CapAnnDataUns
 from .cap_anndata import CapAnnData
+from .reader import (
+    read_directly,
+    read_h5ad,
+)
 
 
 __all__ = ["CapAnnData"]

cap_anndata/backed_df.py

@@ -1,8 +1,11 @@
 import pandas as pd
 import numpy as np
-from typing import List
+from typing import List, Any
 import logging
 
+from pandas._typing import Self
+from pandas.core.generic import bool_t
+
 logger = logging.getLogger(__name__)
 
 
@@ -13,7 +16,8 @@ class CapAnnDataDF(pd.DataFrame):
     The main feature of the class is handling <column-order> attribute
     which must be a copy of h5py.Group attribute
     """
-    _metadata = ['column_order']
+
+    _metadata = ["column_order"]
 
     def rename_column(self, old_name: str, new_name: str) -> None:
         i = np.where(self.column_order == old_name)[0]
@@ -31,10 +35,35 @@ class CapAnnDataDF(pd.DataFrame):
         return super().__setitem__(key, value)
 
     @classmethod
-    def from_df(cls, df: pd.DataFrame, column_order: List[str] = None):
+    def from_df(cls, df: pd.DataFrame, column_order: List[str] = None) -> Self:
         if column_order is None:
             column_order = df.columns.to_numpy()
 
         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 if col not in self.column_order
+            ]
+        else:
+            new_columns = [col for col in other.columns if col not in self.column_order]
+        column_order = np.append(self.column_order, new_columns)
+        return self.from_df(result, column_order=column_order)
+
+    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 if col not in self.column_order
+            ]
+        else:
+            new_columns = [col for col in right.columns if col not in self.column_order]
+        column_order = np.append(self.column_order, new_columns)
+        return self.from_df(result, column_order=column_order)
+
+    def copy(self, deep: bool_t | None = True) -> Self:
+        return self.from_df(super().copy(deep=deep), column_order=self.column_order)

cap_anndata/cap_anndata.py

@@ -1,13 +1,13 @@
 import logging
-import contextlib
 import anndata as ad
+import numpy as np
 import h5py
 from typing import List, Union, Dict, Tuple, Final
 from anndata._io.specs import read_elem, write_elem
-from dataclasses import dataclass
 
 from cap_anndata import CapAnnDataDF, CapAnnDataUns
 
+
 logger = logging.getLogger(__name__)
 
 X_NOTATION = Union[h5py.Dataset, ad.experimental.CSRDataset, ad.experimental.CSCDataset]
@@ -16,21 +16,132 @@ OBSM_NOTATION = Dict[str, X_NOTATION]
 NotLinkedObject: Final = "__NotLinkedObject"
 
 
-@dataclass
-class RawLayer:
-    var: CapAnnDataDF = None
-    X: X_NOTATION = None
+class BaseLayerMatrixAndDf:
+    def __init__(self, file: h5py.File, path_to_content: str = "/") -> None:
+        self._file = file
+        self._path_to_content = path_to_content
+        self._X: X_NOTATION = None
+
+    @property
+    def X(self) -> X_NOTATION:
+        if self._X is None:
+            self._link_x()
+        return self._X
+
+    def _link_x(self) -> None:
+        x = self._file[self._path_to_content + "X"]
+        if isinstance(x, h5py.Dataset):
+            # dense X
+            self._X = x
+        else:
+            # sparse dataset
+            self._X = ad.experimental.sparse_dataset(x)
 
     @property
     def shape(self) -> Tuple[int, int]:
-        return self.X.shape if self.X is not None else None
+        if self.X is not None:
+            shape = tuple(map(int, self.X.shape))
+        else:
+            shape = None
+        return shape
+
+    def _lazy_df_load(self, key: str) -> CapAnnDataDF:
+        df = CapAnnDataDF()
+        attribute = self._path_to_content + key
+        column_order = self._read_attr(self._file[attribute], "column-order")
+        df.column_order = column_order
+        if df.column_order.dtype != object:
+            # empty DataFrame will have column_order as float64
+            # which leads to failure in overwrite method
+            df.column_order = df.column_order.astype(object)
+        return df
+
+    @staticmethod
+    def _read_attr(obj: Union[h5py.Group, h5py.Dataset], attr_name: str) -> any:
+        attrs = dict(obj.attrs)
+        if attr_name not in attrs.keys():
+            raise KeyError(f"The {attr_name} doesn't exist!")
+        return attrs[attr_name]
+
+    def _read_df(self, key: str, columns: List[str]) -> CapAnnDataDF:
+        group_path = self._path_to_content + key
+        if group_path not in self._file.keys():
+            raise ValueError(f"The group {group_path} doesn't exist in the file!")
+
+        h5_group = self._file[group_path]
+
+        column_order = self._read_attr(h5_group, "column-order")
+
+        if columns is None:
+            # read whole df
+            df = CapAnnDataDF.from_df(read_elem(h5_group), column_order=column_order)
+        else:
+            cols_to_read = [c for c in columns if c in column_order]
+            df = CapAnnDataDF()
+            df.column_order = column_order
+            index_col = self._read_attr(h5_group, "_index")
+            df.index = read_elem(h5_group[index_col])
+
+            for col in cols_to_read:
+                df[col] = read_elem(h5_group[col])
+
+        if df.column_order.dtype != object:
+            # empty DataFrame will have column_order as float64
+            # which leads to failure in overwrite method
+            df.column_order = df.column_order.astype(object)
+        return df
+
+    def _write_elem_lzf(self, dest_key: str, elem: any) -> None:
+        write_elem(self._file, dest_key, elem, dataset_kwargs={"compression": "lzf"})
+
+    def _validate_cap_df(self, cap_df: CapAnnDataDF, axis: int) -> None:
+        if not isinstance(cap_df, CapAnnDataDF):
+            raise TypeError(
+                f"The input should be an instance of CapAnnDataDF class but {type(cap_df)} given!"
+            )
+
+        if axis not in [0, 1]:
+            raise ValueError("The axis should be either 0 or 1!")
+
+        if cap_df.shape[0] != self.shape[axis]:
+            items = "cells" if axis == 0 else "genes"
+            raise ValueError(
+                f"The number of rows in the input DataFrame should be equal to the number of {items} in the "
+                "AnnData object!"
+            )
+
+
+class RawLayer(BaseLayerMatrixAndDf):
+    def __init__(self, h5_file: h5py.File):
+        super().__init__(h5_file, path_to_content="/raw/")
+        self._var: CapAnnDataDF = None
+
+    @property
+    def var(self) -> CapAnnDataDF:
+        if self._var is None:
+            self._var = self._lazy_df_load("var")
+        return self._var
+
+    @var.setter
+    def var(self, cap_df: CapAnnDataDF) -> None:
+        self._validate_cap_df(cap_df, axis=1)
+        self._var = cap_df
+
+    def read_var(self, columns: List[str] = None, reset: bool = False) -> None:
+        df = self._read_df(key="var", columns=columns)
+        if self.var.empty or reset:
+            self._var = df
+        else:
+            for col in df.columns:
+                self._var[col] = df[col]
 
 
-class CapAnnData:
+class CapAnnData(BaseLayerMatrixAndDf):
     def __init__(self, h5_file: h5py.File) -> None:
+        super().__init__(h5_file, path_to_content="/")
         self._file: h5py.File = h5_file
-        self.obs: CapAnnDataDF = None
-        self.var: CapAnnDataDF = None
+        self._obs: CapAnnDataDF = None
+        self._var: CapAnnDataDF = None
         self._X: X_NOTATION = None
         self._obsm: OBSM_NOTATION = None
         self._uns: CapAnnDataUns = None
@@ -38,10 +149,26 @@ class CapAnnData:
         self._shape: Tuple[int, int] = None
 
     @property
-    def X(self) -> X_NOTATION:
-        if self._X is None:
-            self._link_x()
-        return self._X
+    def obs(self) -> CapAnnDataDF:
+        if self._obs is None:
+            self._obs = self._lazy_df_load("obs")
+        return self._obs
+
+    @obs.setter
+    def obs(self, cap_df: CapAnnDataDF) -> None:
+        self._validate_cap_df(cap_df, axis=0)
+        self._obs = cap_df
+
+    @property
+    def var(self) -> CapAnnDataDF:
+        if self._var is None:
+            self._var = self._lazy_df_load("var")
+        return self._var
+
+    @var.setter
+    def var(self, cap_df: CapAnnDataDF) -> None:
+        self._validate_cap_df(cap_df, axis=1)
+        self._var = cap_df
 
     @property
     def obsm(self) -> OBSM_NOTATION:
@@ -52,66 +179,43 @@ class CapAnnData:
     @property
     def raw(self) -> RawLayer:
         if self._raw is None:
-            self._link_raw_x()
+            if "raw" not in self._file.keys():
+                logger.warning("Can't read raw.var since raw layer doesn't exist!")
+                return
+
+            self._raw = RawLayer(self._file)
         return self._raw
 
     @property
     def uns(self) -> CapAnnDataUns:
         if self._uns is None:
-            self._uns = CapAnnDataUns({k: NotLinkedObject for k in self._file["uns"].keys()})
+            self._uns = CapAnnDataUns(
+                {k: NotLinkedObject for k in self._file["uns"].keys()}
+            )
         return self._uns
 
-    def read_obs(self, columns: List[str] = None) -> None:
-        self.obs = self._read_df(self._file["obs"], columns=columns)
-
-    def read_var(self, columns: List[str] = None, raw: bool = False) -> None:
-        if raw:
-            # Check if raw exists first
-            if "raw" not in self._file.keys():
-                logger.debug("Can't read raw.var since raw layer doesn't exist!")
-                return
-
-            if self._raw is None:
-                self._raw = RawLayer()
-                self._link_raw_x()
-
-            key = "raw/var"
-            self._raw.var = self._read_df(self._file[key], columns=columns)
+    def read_obs(self, columns: List[str] = None, reset: bool = False) -> None:
+        df = self._read_df("obs", columns=columns)
+        if self.obs.empty or reset:
+            self._obs = df
         else:
-            key = "var"
-            self.var = self._read_df(self._file[key], columns=columns)
-
-    def _read_df(self, h5_group: h5py.Group, columns: List[str]) -> CapAnnDataDF:
-        column_order = self._read_attr(h5_group, "column-order")
+            for col in df.columns:
+                self._obs[col] = df[col]
 
-        if columns is None:
-            # read whole df
-            df = CapAnnDataDF.from_df(read_elem(h5_group), column_order=column_order)
+    def read_var(self, columns: List[str] = None, reset: bool = False) -> None:
+        df = self._read_df("var", columns=columns)
+        if self.var.empty or reset:
+            self._var = df
         else:
-            cols_to_read = [c for c in columns if c in column_order]
-            df = CapAnnDataDF()
-            df.column_order = column_order
-
-            index_col = self._read_attr(h5_group, "_index")
-            df.index = read_elem(h5_group[index_col])
-
-            for col in cols_to_read:
-                df[col] = read_elem(h5_group[col])
-        return df
-
-    @staticmethod
-    def _read_attr(obj: Union[h5py.Group, h5py.Dataset], attr_name: str) -> any:
-        attrs = dict(obj.attrs)
-        if attr_name not in attrs.keys():
-            raise KeyError(f"The {attr_name} doesn't exist!")
-        return attrs[attr_name]
+            for col in df.columns:
+                self._var[col] = df[col]
 
     def overwrite(self, fields: List[str] = None) -> None:
         field_to_entity = {
             "obs": self.obs,
             "var": self.var,
             "raw.var": self.raw.var if self.raw is not None else None,
-            "uns": self.uns
+            "uns": self.uns,
         }
 
         if fields is None:
@@ -120,7 +224,9 @@ class CapAnnData:
             for f in fields:
                 if f not in field_to_entity.keys():
                     raise KeyError(
-                        f"The field {f} is not supported! The list of suported fields are equal to supported attributes of the CapAnnData class: obs, var, raw.var and uns.")
+                        f"The field {f} is not supported! The list of supported fields are equal to supported "
+                        f"attributes of the CapAnnData class: obs, var, raw.var and uns."
+                    )
 
         for key in ["obs", "var", "raw.var"]:
             if key in fields:
@@ -128,11 +234,17 @@ class CapAnnData:
                 if entity is None:
                     continue
 
-                key = key.replace(".", '/') if key == "raw.var" else key
+                key = key.replace(".", "/") if key == "raw.var" else key
 
                 for col in entity.columns:
                     self._write_elem_lzf(f"{key}/{col}", entity[col].values)
-                self._file[key].attrs['column-order'] = entity.column_order
+
+                column_order = entity.column_order
+                if (
+                    column_order.size == 0
+                ):  # Refs https://github.com/cellannotation/cap-anndata/issues/6
+                    column_order = np.array([], dtype=np.float64)
+                self._file[key].attrs["column-order"] = column_order
 
         if "uns" in fields:
             for key in self.uns.keys():
@@ -152,32 +264,6 @@ class CapAnnData:
                 sourse = self._file[f"uns/{key}"]
                 self.uns[key] = read_elem(sourse)
 
-    @property
-    def shape(self) -> tuple[int, int]:
-        return self.X.shape
-
-    def _link_x(self) -> None:
-        x = self._file["X"]
-        if isinstance(x, h5py.Dataset):
-            # dense X
-            self._X = x
-        else:
-            # sparse dataset
-            self._X = ad.experimental.sparse_dataset(x)
-
-    def _link_raw_x(self) -> None:
-        if "raw" in self._file.keys():
-            if self._raw is None:
-                self._raw = RawLayer()
-
-            raw_x = self._file["raw/X"]
-            if isinstance(raw_x, h5py.Dataset):
-                # dense X
-                self._raw.X = raw_x
-            else:
-                # sparse dataset
-                self._raw.X = ad.experimental.sparse_dataset(raw_x)
-
     def _link_obsm(self) -> None:
         self._obsm = {}
         if "obsm" in self._file.keys():
@@ -190,32 +276,12 @@ class CapAnnData:
                 else:
                     # sparse array
                     self._obsm[entity_name] = ad.experimental.sparse_dataset(entity)
-        logger.debug(f"obsm={self._obsm}")
 
     def obsm_keys(self) -> List[str]:
         return list(self.obsm.keys())
 
-    def _write_elem_lzf(self, dest_key: str, elem: any) -> None:
-        write_elem(self._file, dest_key, elem, dataset_kwargs={"compression": "lzf"})
+    def obs_keys(self) -> List[str]:
+        return self.obs.column_order.tolist()
 
-    @staticmethod
-    @contextlib.contextmanager
-    def read_anndata_file(file_path, backed='r'):
-        """The method to read anndata file using original AnnData package"""
-        logger.debug(f"Read file {file_path} in backed mode = {backed}...")
-
-        adata = None
-        try:
-            adata = ad.read_h5ad(file_path, backed=backed)
-            logger.debug(f"Successfully read anndata file path {file_path}")
-            yield adata
-
-        except Exception as error:
-            logger.error(f"Error during read anndata file at path: {file_path}, error = {error}!")
-            raise error
-
-        finally:
-            if adata is not None:
-                if adata.isbacked:
-                    adata.file.close()
-                logger.debug("AnnData closed!")
+    def var_keys(self) -> List[str]:
+        return self.var.column_order.tolist()

cap_anndata/reader.py

@@ -0,0 +1,44 @@
+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

{cap_anndata-0.1.0.dist-info → cap_anndata-0.2.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: cap_anndata
-Version: 0.1.0
-Summary: Partial read of AnnData files for low-memory operations with large datasets.
+Version: 0.2.0
+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
@@ -25,41 +25,65 @@ CAP-AnnData enriches the AnnData ecosystem by offering tailored functionalities
 
 ## 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 in `test/unit_test.py`.
+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. Read AnnData File Dataframes
+#### 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
-import h5py
-from cap_anndata import CapAnnData
+from cap_anndata import read_h5ad
 
 file_path = "your_data.h5ad"
-with h5py.File(file_path, 'r') as file:
-    cap_adata = CapAnnData(file)
-
+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=['gene_expression', 'dispersion'])
-
-    # Read all columns of raw.var
-    cap_adata.read_var(raw=True)
+    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=[])
 ```
 
-##### Non-existing 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. 
+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
+#### 2. Modify the AnnData File DataFrames In-Place
 
 You can directly modify the dataframe by adding, renaming, or removing columns.
 
@@ -68,13 +92,14 @@ You can directly modify the dataframe by adding, renaming, or removing columns.
 cap_adata.obs['new_col'] = [value1, value2, value3]
 
 # Rename a column
-cap_adata.rename_column('old_col_name', 'new_col_name')
+cap_adata.obs.rename_column('old_col_name', 'new_col_name')
 
 # Remove a column
-cap_adata.remove_column('col_to_remove')
+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
@@ -84,7 +109,7 @@ cap_adata.overwrite()
 cap_adata.overwrite(['obs', 'var'])
 ```
 
-The full list of supported fields: `X`, `raw.X`, `obs`, `var`, `raw.var`, `obsm`, `uns`.
+The full list of supported fields: `obs`, `var`, `raw.var`, `obsm`, `uns`.
 
 #### 3. How to Read Few Columns but Overwrite One in a Dataframe
 
@@ -100,14 +125,19 @@ 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 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 h5py.File(path) as file:
+with read_h5ad(file_path=file_path, edit=False) as cap_adata:
     # self.X is None here
     cap_adata = CapAnnData(file)  
 
@@ -135,13 +165,13 @@ 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. We can get the information about the name and shape of the embeddings without taking the whole matrixes in the memory!
+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 h5py.File(path) as file:
-    # initialization
-    cap_adata = CapAnnData(file) 
-
+with read_h5ad(file_path=file_path, edit=False) as cap_adata:
     # will return the list of strings
     obsm_keys = cap_adata.obsm_keys()  
 
@@ -158,10 +188,7 @@ with h5py.File(path) as file:
 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 h5py.File(path) as file:
-    # initialization
-    cap_adata = CapAnnData(file) 
-
+with read_h5ad(file_path=file_path, edit=True) as cap_adata:
     # will return the keys() object
     keys = cap_adata.uns.keys()  
 
@@ -197,3 +224,28 @@ To save `uns` changes the method `CapAnnData.overwrite()` must be called.
 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.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cap_anndata/__init__.py,sha256=l9lvFpcMsQksp8_dI-fjUgrImoMdztbu3jVSdmxNPmA,205
+cap_anndata/backed_df.py,sha256=wKtQ_LkTpfPIfBod9kGlEUrmJMYe7TGs9TZexvmz7QI,2678
+cap_anndata/backed_uns.py,sha256=Tfxoz3RgcgENf4SvxFOox9w048K2QmBTh1VbAf4yqVI,854
+cap_anndata/cap_anndata.py,sha256=nv5f7A9jyK_rZ2kx54XvnX-V65MFlE3CYQC-n_zBhB8,10097
+cap_anndata/reader.py,sha256=kg9xoS_S0gY6WpsHE8PwGMa14VXh9Ibqjw4bwoerYsE,1267
+cap_anndata-0.2.0.dist-info/LICENSE,sha256=JAV0w7TBl6wQe9iFcCKjAWgpurym0f-Q0B75zm2PrKw,1560
+cap_anndata-0.2.0.dist-info/METADATA,sha256=xh25tmJOKCeTnWL3Cir-PXixFmZYIUcKuaUw4Uzrarg,9487
+cap_anndata-0.2.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+cap_anndata-0.2.0.dist-info/top_level.txt,sha256=GKi_Uk4LUhXwWBfFCTIyJvEoJqFREt_4uH4CWgeLsg4,12
+cap_anndata-0.2.0.dist-info/RECORD,,

cap_anndata-0.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-cap_anndata/__init__.py,sha256=4Vex9i79uTgNQZo_yiEuNc0KoLXPs5Awv87KWmDbxzM,143
-cap_anndata/backed_df.py,sha256=Ce74WHzXhebYRORx7yjVJD02XCcF5j1SxvmbTIpwzCA,1418
-cap_anndata/backed_uns.py,sha256=Tfxoz3RgcgENf4SvxFOox9w048K2QmBTh1VbAf4yqVI,854
-cap_anndata/cap_anndata.py,sha256=VyIOKU9U7vR65_tB75DsFCb_EkYw7DgiA43cAk-ouOQ,7627
-cap_anndata-0.1.0.dist-info/LICENSE,sha256=JAV0w7TBl6wQe9iFcCKjAWgpurym0f-Q0B75zm2PrKw,1560
-cap_anndata-0.1.0.dist-info/METADATA,sha256=8iPDHNrN8fUdLd512yWzZdVrwED-IXjUwASFXq3IlEk,7123
-cap_anndata-0.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-cap_anndata-0.1.0.dist-info/top_level.txt,sha256=GKi_Uk4LUhXwWBfFCTIyJvEoJqFREt_4uH4CWgeLsg4,12
-cap_anndata-0.1.0.dist-info/RECORD,,