Skip to content

log1p

Short Description

sm.pp.log1p applies a log1p transformation to the raw data of an AnnData object and saves the transformed data in a specified layer. If a string path to an AnnData file is provided, the file is loaded, transformed, and overwritten with the transformed data. The function ensures the raw data exists before applying the transformation and allows for verbose output.

Function

log1p(adata, layer='log', verbose=True)

Parameters:

Name Type Description Default
adata str or AnnData

The AnnData object or a string path to an AnnData file. If a path is provided, the function will load the AnnData object from the file. The transformation is applied to the raw data of this object.

 required
layer str

Name of the new layer where the log-transformed data will be stored. Default is 'log'. If the layer already exists, it will be overwritten with the new log-transformed data.

 'log'
verbose bool

If True, the function will print messages about its progress and actions, including warnings if the specified layer already exists and confirmation when the AnnData object is saved to a file. Default is True.

 True

Returns:

Name Type Description
adata anndata

The modified AnnData object, only if the input is an AnnData object and not a file path. If a file path is provided and successfully processed, the function returns None.
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Using a path to an AnnData file:
# will overwrite the original file with the transformed AnnData object.

sm.pp.log1p("path/to/your/adata.h5ad", layer="log", verbose=True)

# Using an AnnData object directly:
# Assuming `adata` is your pre-loaded into memory
# This will apply log1p transformation and the modified AnnData object

adata = sm.pp.log1p(adata, layer="log", verbose=True)
Source code in scimap/preprocessing/log1p.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def log1p (adata,
           layer='log',  
           verbose=True):

    """
Parameters:
    adata (str or anndata.AnnData): 
        The AnnData object or a string path to an AnnData file. If a path is provided, the function will load the AnnData object from the file. The transformation is applied to the raw data of this object.

    layer (str): 
        Name of the new layer where the log-transformed data will be stored. Default is 'log'. If the layer already exists, it will be overwritten with the new log-transformed data.

    verbose (bool): 
        If True, the function will print messages about its progress and actions, including warnings if the specified layer already exists and confirmation when the AnnData object is saved to a file. Default is True.


Returns:
    adata (anndata): 
        The modified AnnData object, only if the input is an AnnData object and not a file path. If a file path is provided and successfully processed, the function returns None.

Example:
    ```python

    # Using a path to an AnnData file:
    # will overwrite the original file with the transformed AnnData object.

    sm.pp.log1p("path/to/your/adata.h5ad", layer="log", verbose=True)

    # Using an AnnData object directly:
    # Assuming `adata` is your pre-loaded into memory
    # This will apply log1p transformation and the modified AnnData object

    adata = sm.pp.log1p(adata, layer="log", verbose=True)

    ```
"""

    # load adata
    if isinstance(adata, str):
        adata_path = Path(adata)
        if not adata_path.exists():
            raise FileNotFoundError(f"The file {adata} does not exist.")
        adata = ad.read_h5ad(adata_path)
    else:
        adata_path = None


    if layer in adata.layers:
        if verbose:
            print(f"Warning: Layer '{layer}' already exists. It will be overwritten with the new log-transformed data.")

    if adata.raw is None:
        raise AttributeError("adata.raw does not exist. Please assign RAW data to adata.raw before proceeding (e.g., adata.raw = adata).")

    # perform the operation
    adata.layers[layer] = np.log1p(adata.raw.X)

    # return 
    # Overwrite the original file with the modified AnnData object if requested
    if isinstance(adata_path, Path):
        adata.write_h5ad(adata_path)
        if verbose: 
            print(f"Modified AnnData object has been saved to {adata_path}")
    else:
        return adata