alphapepttools.pp.add_metadata

Contents

alphapepttools.pp.add_metadata#

alphapepttools.pp.add_metadata(adata, incoming_metadata, axis, *, keep_data_shape=False, keep_existing_metadata=False, verbose=False)#

Add metadata to an AnnData object while checking for matching indices or shape

If axis is 0, assume metadata.index <-> data.index and add metadata as ‘.obs’ of the AnnData object. If axis is 1, assume metadata.index <-> data.columns and add metadata as ‘.var’ of the AnnData object.

Parameters:

  • adata (AnnData) – AnnData object to add metadata to

  • incoming_metadata (DataFrame) – Metadata dataframe to add. The matching entity is always the INDEX, depending on axis it is matched against obs (axis = 0) or var (axis = 1)

  • axis (int) – Axis to add metadata to. 0 for obs and 1 for var

  • keep_data_shape (bool (default: False)) – If True, the incoming data is left-joined to the existing data, which may result in nan-padded rows in the incoming data. If False, incoming data is added via inner join, which may change the shape of the adata object

  • keep_existing_metadata (bool (default: False)) – If True, incoming metadata is added to the existing metadata. If False, incoming metadata replaces existing metadata. If columns between existing and incoming metadata are synonymous, the corresponding incoming metadata columns are ignored

  • verbose (bool (default: False)) – If True, print additional information about the operation

Return type:

AnnData

Returns:

AnnData object with metadata added

Examples

import numpy as np
import anndata as ad
import pandas as pd
from alphapepttools.pp.data import add_metadata

# Create example AnnData
adata = ad.AnnData(
    X=np.array([[1, 2], [5, 1], [6, 6], [9, 3]]),
    obs=pd.DataFrame({"batch": ["A", "A", "B", "B"]}, index=["sample1", "sample2", "sample3", "sample4"]),
    var=pd.DataFrame(index=["protein1", "protein2"]),
)

# New metadata to add
new_metadata = pd.DataFrame(
    {"condition": ["control", "control", "treated", "treated"]},
    index=["sample1", "sample2", "sample3", "sample4"],
)

# Method 1: Replace existing metadata (keep_existing_metadata=False, default)
adata1 = adata.copy()
adata1 = add_metadata(adata1, new_metadata, axis=0)
print(adata1.obs.columns.tolist())  # ['condition'] - batch is replaced

# Method 2: Add to existing metadata (keep_existing_metadata=True)
adata2 = adata.copy()
adata2 = add_metadata(adata2, new_metadata, axis=0, keep_existing_metadata=True)
print(adata2.obs.columns.tolist())  # ['batch', 'condition'] - both preserved
Contents