py2ls 0.2.4.3__py3-none-any.whl → 0.2.4.4__py3-none-any.whl

py2ls/bio.py

@@ -1,8 +1,12 @@
 import GEOparse
+import gseapy as gp
 from typing import Union
 import pandas as pd
+import numpy as np
 import os
 import logging
+
+from sympy import use
 from . import ips
 from . import plot 
 import matplotlib.pyplot as plt 
@@ -123,11 +127,32 @@ def get_meta(geo: dict, dataset: str = "GSE25097", verbose=True) -> pd.DataFrame
 
     # Convert the list of dictionaries to a DataFrame
     meta_df = pd.DataFrame(meta_list)
+    col_rm = [
+        "channel_count",
+        "contact_web_link",
+        "contact_address",
+        "contact_city",
+        "contact_country",
+        "contact_department",
+        "contact_email",
+        "contact_institute",
+        "contact_laboratory",
+        "contact_name",
+        "contact_phone",
+        "contact_state",
+        "contact_zip/postal_code",
+        "contributor",
+        "manufacture_protocol",
+        "taxid",
+        "web_link",
+    ]
+    # rm unrelavent columns
+    meta_df = meta_df.drop(columns=[col for col in col_rm if col in meta_df.columns])
     if verbose:
         print(
             f"Meta info columns for dataset '{dataset}': \n{sorted(meta_df.columns.tolist())}"
         )
-        display(meta_df[:3].T)
+        display(meta_df[:1].T)
     return meta_df
 
 
@@ -142,13 +167,14 @@ def get_probe(
         df_meta = get_meta(geo=geo, dataset=dataset, verbose=False)
         platform_id = df_meta["platform_id"].unique().tolist()
         platform_id = platform_id[0] if len(platform_id) == 1 else platform_id
-        print(platform_id)
+        print(f"Platform: {platform_id}")
     df_probe = geo[dataset].gpls[platform_id].table
     if df_probe.empty:
         print(
-            f"above is meta info, failed to find the probe info. 看一下是不是在单独的文件中包含了probe信息"
+            f"Warning: cannot find the probe info. 看一下是不是在单独的文件中包含了probe信息"
         )
-        return get_meta(geo, dataset, verbose=True)
+        display(f"🔗: https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc={platform_id}")
+        return get_meta(geo, dataset, verbose=verbose)
     if verbose:
         print(f"columns in the probe table: \n{sorted(df_probe.columns.tolist())}")
     return df_probe
@@ -181,19 +207,25 @@ def get_expression_data(geo: dict, dataset: str = "GSE25097") -> pd.DataFrame:
     return expression_values
 
 
-def get_data(geo: dict, dataset: str = "GSE25097", verbose=True):
+def get_data(geo: dict, dataset: str = "GSE25097", verbose=False):
+    print(f"\n\ndataset: {dataset}\n")
     # get probe info
     df_probe = get_probe(geo, dataset=dataset, verbose=False)
     # get expression values
     df_expression = get_expression_data(geo, dataset=dataset)
-    print(
-        f"df_expression.shape: {df_expression.shape} \ndf_probe.shape: {df_probe.shape}"
-    )
+    if not df_expression.select_dtypes(include=["number"]).empty:
+        # 如果数据全部是counts类型的话, 则使用TMM进行normalize
+        if 'counts' in get_data_type(df_expression): 
+            print(f"{dataset}'s type is raw read counts, nomalized(transformed) via 'TMM'")
+            df_expression=counts2expression(df_expression.T).T 
     if any([df_probe.empty, df_expression.empty]):
         print(
-            f"above is meta info, failed to find the probe info. 看一下是不是在单独的文件中包含了probe信息"
+            f"got empty values, check the probe info. 看一下是不是在单独的文件中包含了probe信息"
         )
         return get_meta(geo, dataset, verbose=True)
+    print(
+        f"\n\tdf_expression.shape: {df_expression.shape} \n\tdf_probe.shape: {df_probe.shape}"
+    )
     df_exp = pd.merge(
         df_probe,
         df_expression,
@@ -237,14 +269,39 @@ def get_data(geo: dict, dataset: str = "GSE25097", verbose=True):
     df_exp.set_index(col_gene_symbol, inplace=True)
     df_exp = df_exp[col_gsm].T  # transpose, so that could add meta info
 
-    df_merged = ips.df_merge(df_meta, df_exp)
+    df_merged = ips.df_merge(df_meta, df_exp,use_index=True)
+    
+    print(
+        f"\ndataset:'{dataset}' n_sample = {df_merged.shape[0]}, n_gene={df_exp.shape[1]}"
+    )
     if verbose:
-        print(
-            f"\ndataset:'{dataset}' n_sample = {df_merged.shape[0]}, n_gene={df_exp.shape[1]}"
-        )
         display(df_merged.sample(5))
     return df_merged
 
+def get_data_type(data: pd.DataFrame) -> str:
+    """
+    Determine the type of data: 'read counts' or 'normalized expression data'.
+    usage:
+        get_data_type(df_counts)
+    """
+    numeric_data = data.select_dtypes(include=["number"])
+    if numeric_data.empty:
+        raise ValueError(f"找不到数字格式的数据, 请先进行转换")
+    # Check if the data contains only integers
+    if numeric_data.apply(lambda x: x.dtype == "int").all():
+        # Check for values typically found in raw read counts (large integers)
+        if numeric_data.max().max() > 10000:  # Threshold for raw counts
+            return "read counts"
+    # Check if all values are floats
+    if numeric_data.apply(lambda x: x.dtype == "float").all():
+        # If values are small, it's likely normalized data
+        if numeric_data.max().max() < 1000:  # Threshold for normalized expression
+            return "normalized expression data"
+        else:
+            print(f"the max value: {numeric_data.max().max()}, it could be a raw read counts data. but needs you to double check it")
+            return "read counts"
+    # If mixed data types or unexpected values
+    return "mixed or unknown"
 
 def split_at_lower_upper(lst):
     """
@@ -261,6 +318,13 @@ def split_at_lower_upper(lst):
                 return lst[: i + 1], lst[i + 1 :]
     return lst, []
 
+def find_condition(data:pd.DataFrame, columns=["characteristics_ch1","title"]):
+    if data.shape[1]>=data.shape[0]:
+        display(data.iloc[:1,:40].T)
+    # 详细看看每个信息的有哪些类, 其中有数字的, 要去除
+    for col in columns:
+        print(f"{"="*10} {col} {"="*10}")
+        display(ips.flatten([ips.ssplit(i, by="numer")[0] for i in data[col]]))
 
 def add_condition(
     data: pd.DataFrame,
@@ -305,7 +369,7 @@ def add_condition(
             lambda x: by_not_name if not by_not in x else by_name
         )
     if verbose:
-        display(data)
+        display(data.sample(5))
     if not inplace:
         return data
 
@@ -370,13 +434,13 @@ def add_condition_multi(
 
     # Display the updated DataFrame if verbose is True
     if verbose:
-        display(data)
+        display(data.sample(5))
 
     if not inplace:
         return data
 
 def clean_dataset(
-    data: pd.DataFrame, dataset: str = "GSE25097", condition: str = "condition",sep="///"
+    data: pd.DataFrame, dataset: str = None, condition: str = "condition",sep="///"
 ):
     """
     #* it has been involved in bio.batch_effects(), but default: False
@@ -386,6 +450,14 @@ def clean_dataset(
     4. add the 'condition' and 'dataset info' to the columns
     5. set genes as index
     """
+    usage_str="""clean_dataset(data: pd.DataFrame, dataset: str = None, condition: str = "condition",sep="///")
+    """
+    if dataset is None:
+        try: 
+            dataset=data["dataset"][0]
+        except:
+            print("cannot find 'dataset' name")
+            print(f"example\n {usage_str}")
     #! (4.1) clean data set and prepare super_datasets
     # df_data_2, 左边的列是meta,右边的列是gene_symbol
     col_gene = split_at_lower_upper(data.columns.tolist())[1][0]
@@ -420,7 +492,7 @@ def clean_dataset(
     return df_gene
 
 def batch_effect(
-    data: list = "[df_gene_1, df_gene_2, df_gene_3]",
+    data: list = "[df_gene_1, df_gene_2, df_gene_3]", # index (genes),columns(samples)
     datasets: list = ["GSE25097", "GSE62232", "GSE65372"],
     clean_data:bool=False, # default, not do data cleaning
     top_genes:int=10,# only for plotting
@@ -510,4 +582,869 @@ def batch_effect(
 
 def get_common_genes(elment1, elment2):
     common_genes=ips.shared(elment1, elment2)
-    return common_genes
+    return common_genes
+
+def counts2expression(
+    counts: pd.DataFrame,# index(samples); columns(genes)
+    method: str = "TMM",  # 'CPM', 'FPKM', 'TPM', 'UQ', 'TMM', 'CUF', 'CTF'
+    length: list = None,
+    uq_factors: pd.Series = None,
+    verbose: bool = False,
+) -> pd.DataFrame:
+    """
+    https://www.linkedin.com/pulse/snippet-corner-raw-read-count-normalization-python-mazzalab-gzzyf?trk=public_post
+    Convert raw RNA-seq read counts to expression values
+    counts: pd.DataFrame
+        index: samples
+        columns: genes
+    usage:
+        df_normalized = counts2expression(df_counts, method='TMM', verbose=True)
+    recommend cross datasets:
+        cross-datasets:
+            TMM (Trimmed Mean of M-values); Very suitable for merging datasets, especially
+                for cross-sample and cross-dataset comparisons; commonly used in
+                differential expression analysis
+            CTF (Counts adjusted with TMM factors); Suitable for merging datasets, as
+                TMM-based normalization. Typically used as input for downstream analyses
+                like differential expression
+            TPM (Transcripts Per Million); Good for merging datasets. TPM is often more
+                suitable for cross-dataset comparisons because it adjusts for gene length
+                and ensures that the expression levels sum to the same total in each sample
+            UQ (Upper Quartile);  less commonly used than TPM or TMM
+            CUF (Counts adjusted with UQ factors); Can be used, but UQ normalization is
+                generally not as standardized as TPM or TMM for merging datasets.
+        within-datasets:
+            CPM(Counts Per Million); it doesn’t adjust for gene length or other
+                variables that could vary across datasets
+            FPKM(Fragments Per Kilobase Million); FPKM has been known to be inconsistent
+                across different experiments
+    Parameters:
+    - counts: pd.DataFrame
+        Raw read counts with genes as rows and samples as columns.
+    - method: str, default='TMM'
+        CPM (Counts per Million): Scales counts by total library size.
+        FPKM (Fragments per Kilobase Million): Requires gene length; scales by both library size and gene length.
+        TPM (Transcripts per Million): Scales by gene length and total transcript abundance.
+        UQ (Upper Quartile): Normalizes based on the upper quartile of the counts.
+        TMM (Trimmed Mean of M-values): Adjusts for compositional biases.
+        CUF (Counts adjusted with Upper Quartile factors): Counts adjusted based on UQ factors.
+        CTF (Counts adjusted with TMM factors): Counts adjusted based on TMM factors.
+    - gene_lengths: pd.Series, optional
+        Gene lengths (e.g., in kilobases) for FPKM/TPM normalization. Required for FPKM/TPM.
+    - verbose: bool, default=False
+        If True, provides detailed logging information.
+    - uq_factors: pd.Series, optional
+        Precomputed Upper Quartile factors, required for UQ and CUF normalization.
+
+
+    Returns:
+    - normalized_counts: pd.DataFrame
+        Normalized expression values.
+    """
+    import rnanorm
+    print(f"'counts' data shoule be: index(samples); columns(genes)")
+    if "length" in method: # 有时候记不住这么多不同的名字
+        method="FPKM"
+    methods = ["CPM", "FPKM", "TPM", "UQ", "TMM", "CUF", "CTF"]
+    method = ips.strcmp(method, methods)[0]
+    if verbose:
+        print(
+            f"Starting normalization using method: {method},supported methods: {methods}"
+        )
+    columns_org = counts.columns.tolist()
+    # Check if gene lengths are provided when necessary
+    if method in ["FPKM", "TPM"]:
+        if length is None:
+            raise ValueError(f"Gene lengths must be provided for {method} normalization.")
+        if isinstance(length, list):
+            df_genelength = pd.DataFrame({"gene_length": length})
+            df_genelength.index = counts.columns # set gene_id as index
+            df_genelength.index = df_genelength.index.astype(str).str.strip()
+            # length = np.array(df_genelength["gene_length"]).reshape(1,-1)
+            length = df_genelength["gene_length"]
+            counts.index = counts.index.astype(str).str.strip()
+        elif isinstance(length, pd.Series):
+            
+            length.index=length.index.astype(str).str.strip()
+            counts.columns = counts.columns.astype(str).str.strip()
+            shared_genes=ips.shared(length.index, counts.columns)
+            length=length.loc[shared_genes]
+            counts=counts.loc[:,shared_genes]
+            columns_org = counts.columns.tolist()
+            
+
+    # # Ensure gene lengths are aligned with counts if provided
+    # if length is not None:
+    #     length = length[counts.index]
+
+    # Start the normalization based on the chosen method
+    if method == "CPM":
+        normalized_counts = (
+            rnanorm.CPM().set_output(transform="pandas").fit_transform(counts)
+        )
+
+    elif method == "FPKM":
+        if verbose:
+            print("Performing FPKM normalization using gene lengths.")
+        normalized_counts = (
+            rnanorm.CPM().set_output(transform="pandas").fit_transform(counts)
+        )
+        # convert it to FPKM by, {FPKM= gene length /read counts ×1000} is applied using row-wise division and multiplication.
+        normalized_counts=normalized_counts.div(length.values,axis=1)*1e3
+
+    elif method == "TPM":
+        if verbose:
+            print("Performing TPM normalization using gene lengths.")
+        normalized_counts = (
+            rnanorm.TPM(gene_lengths=length)
+            .set_output(transform="pandas")
+            .fit_transform(counts)
+        )
+
+    elif method == "UQ":
+        if verbose:
+            print("Performing Upper Quartile (UQ) normalization.")
+        if uq_factors is None:
+            uq_factors = rnanorm.upper_quartile_factors(counts)
+        normalized_counts = (
+            rnanorm.UQ(factors=uq_factors)()
+            .set_output(transform="pandas")
+            .fit_transform(counts)
+        )
+
+    elif method == "TMM":
+        if verbose:
+            print("Performing TMM normalization (Trimmed Mean of M-values).")
+        normalized_counts = (
+            rnanorm.TMM().set_output(transform="pandas").fit_transform(counts)
+        )
+
+    elif method == "CUF":
+        if verbose:
+            print("Performing Counts adjusted with UQ factors (CUF).")
+        if uq_factors is None:
+            uq_factors = rnanorm.upper_quartile_factors(counts)
+        normalized_counts = (
+            rnanorm.CUF(factors=uq_factors)()
+            .set_output(transform="pandas")
+            .fit_transform(counts)
+        )
+
+    elif method == "CTF":
+        if verbose:
+            print("Performing Counts adjusted with TMM factors (CTF).")
+        normalized_counts = (rnanorm.CTF().set_output(transform="pandas").fit_transform(counts))
+
+    else:
+        raise ValueError(f"Unknown normalization method: {method}")
+    normalized_counts.columns=columns_org
+    if verbose:
+        print(f"Normalization complete using method: {method}")
+
+    return normalized_counts
+
+def counts_deseq(counts_sam_gene: pd.DataFrame, 
+                 meta_sam_cond: pd.DataFrame,
+                 design_factors:list=None,
+                 kws_DeseqDataSet:dict={},
+                 kws_DeseqStats:dict={}):
+    """
+    https://pydeseq2.readthedocs.io/en/latest/api/docstrings/pydeseq2.ds.DeseqStats.html
+    Note: Using normalized expression data in a DeseqDataSet object is generally not recommended 
+            because the DESeq2 framework is designed to work with raw count data. 
+    baseMean:
+        - This value represents the average normalized count (or expression level) of a 
+            gene across all samples in your dataset.
+        - For example, a baseMean of 0.287 for 4933401J01Rik indicates that this gene has 
+            low expression levels in the samples compared to others with higher baseMean 
+            values like Xkr4 (591.015).
+    log2FoldChange: the magnitude and direction of change in expression between conditions.
+    lfcSE (Log Fold Change Standard Error): standard error of the log2FoldChange. It 
+        indicates the uncertainty in the estimate of the fold change.A lower value indicates 
+        more confidence in the fold change estimate.
+    padj: This value accounts for multiple testing corrections (e.g., Benjamini-Hochberg).
+    Log10transforming: The columns -log10(pvalue) and -log10(FDR) are transformations of 
+        the p-values and adjusted p-values, respectively
+    """
+    from pydeseq2.dds import DeseqDataSet
+    from pydeseq2.ds import DeseqStats
+    from pydeseq2.default_inference import DefaultInference
+
+    # data filtering
+    # counts_sam_gene = counts_sam_gene.loc[:, ~(counts_sam_gene.sum(axis=0) < 10)]
+    if design_factors is None:
+        design_factors=meta_sam_cond.columns.tolist()
+
+    kws_DeseqDataSet.pop("design_factors",{})
+    refit_cooks=kws_DeseqDataSet.pop("refit_cooks",True)
+    
+    #! DeseqDataSet
+    inference = DefaultInference(n_cpus=8)
+    dds = DeseqDataSet(
+        counts=counts_sam_gene,
+        metadata=meta_sam_cond,
+        design_factors=meta_sam_cond.columns.tolist(),
+        refit_cooks=refit_cooks,
+        inference=inference,
+        **kws_DeseqDataSet
+    )
+    dds.deseq2()
+    #* results
+    dds_explain="""
+        res[0]:
+        # X stores the count data,
+        # obs stores design factors,
+        # obsm stores sample-level data, such as "design_matrix" and "size_factors",
+        # varm stores gene-level data, such as "dispersions" and "LFC"."""
+    print(dds_explain)
+    #! DeseqStats
+    stat_res = DeseqStats(dds,**kws_DeseqStats)
+    stat_res.summary()
+    diff = stat_res.results_df.assign(padj=lambda x: x.padj.fillna(1))
+    
+    # handle '0' issue, which will case inf when the later cal (e.g., log10)
+    diff["padj"] = diff["padj"].replace(0, 1e-10)
+    diff["pvalue"] = diff["pvalue"].replace(0, 1e-10)
+
+    diff["-log10(pvalue)"] = diff["pvalue"].apply(lambda x: -np.log10(x))
+    diff["-log10(FDR)"] = diff["padj"].apply(lambda x: -np.log10(x))
+    diff=diff.reset_index().rename(columns={"index": "gene"})
+    # sig_diff = (
+    #     diff.query("log2FoldChange.abs()>0.585 & padj<0.05")
+    #     .reset_index()
+    #     .rename(columns={"index": "gene"})
+    # )
+    return dds, diff,stat_res
+
+def scope_genes(gene_list: list, scopes:str=None, fields: str = "symbol", species="human"):
+    """
+    usage:
+        scope_genes(df_counts.columns.tolist()[:1000], species="mouse")
+    """
+    import mygene
+
+    if scopes is None:
+        # copy from: https://docs.mygene.info/en/latest/doc/query_service.html#scopes
+        scopes = ips.fload(
+            "/Users/macjianfeng/Dropbox/github/python/py2ls/py2ls/data/mygenes_fields_241022.txt",
+            kind="csv",
+            verbose=False,
+        )
+        scopes = ",".join([i.strip() for i in scopes.iloc[:, 0]])
+    mg = mygene.MyGeneInfo()
+    results = mg.querymany(
+        gene_list,
+        scopes=scopes,
+        fields=fields,
+        species=species,
+    )
+    return pd.DataFrame(results)
+
+def get_enrichr(gene_symbol_list, 
+                gene_sets:str, 
+                species='Human', 
+                dir_save="./", 
+                plot_=False, 
+                n_top=30,
+                palette=None,
+                check_shared=True,
+                figsize=(5,8),
+                show_ring=False,
+                xticklabels_rot=0,
+                title=None,# 'KEGG'
+                cutoff=0.05,
+                cmap="coolwarm",
+                **kwargs):
+    """
+    Note: Enrichr uses a list of Entrez gene symbols as input.
+    
+    """
+    kws_figsets = {}
+    for k_arg, v_arg in kwargs.items():
+        if "figset" in k_arg:
+            kws_figsets = v_arg
+            kwargs.pop(k_arg, None)
+            break
+    species_org=species
+    # organism (str) – Select one from { ‘Human’, ‘Mouse’, ‘Yeast’, ‘Fly’, ‘Fish’, ‘Worm’ }
+    organisms=['Human', 'Mouse', 'Yeast', 'Fly', 'Fish', 'Worm']
+    species=ips.strcmp(species,organisms)[0]
+    if species_org.lower()!= species.lower():
+        print(f"species was corrected to {species}, becasue only support {organisms}")
+    if os.path.isfile(gene_sets):
+        gene_sets_name=os.path.basename(gene_sets)
+        gene_sets = ips.fload(gene_sets)
+    else:
+        lib_support_names = gp.get_library_name()
+        # correct input gene_set name
+        gene_sets_name=ips.strcmp(gene_sets,lib_support_names)[0]
+        # download it
+        gene_sets = gp.get_library(name=gene_sets_name, organism=species)
+    print(f"gene_sets get ready: {gene_sets_name}")
+
+    # gene symbols are uppercase
+    gene_symbol_list=[str(i).upper() for i in gene_symbol_list]
+
+    # # check how shared genes
+    if check_shared:
+        shared_genes=ips.shared(ips.flatten(gene_symbol_list,verbose=False), ips.flatten(gene_sets,verbose=False))
+    
+    #! enrichr 
+    try:
+        enr = gp.enrichr(
+            gene_list=gene_symbol_list,
+            gene_sets=gene_sets,
+            organism=species,
+            outdir=None,  # don't write to disk
+            **kwargs
+        )
+    except ValueError as e:
+        print(f"\n{'!'*10}  Error  {'!'*10}\n{' '*4}{e}\n{'!'*10}  Error  {'!'*10}")
+        return None
+    
+    results_df = enr.results
+    print(f"got enrichr reslutls; shape: {results_df.shape}")
+    results_df["-log10(Adjusted P-value)"] = -np.log10(results_df["Adjusted P-value"])
+    results_df.sort_values("-log10(Adjusted P-value)", inplace=True, ascending=False)
+
+    if plot_:
+        if palette is None:
+            palette=plot.get_color(n_top, cmap="coolwarm")[::-1]
+        #! barplot
+        if n_top<5:
+            height_=4
+        elif 5<=n_top<10:
+            height_=5
+        elif 5<=n_top<10:
+            height_=6
+        elif 10<=n_top<15:
+            height_=7
+        elif 15<=n_top<20:
+            height_=8
+        elif 25<=n_top<30:
+            height_=9
+        else:
+            height_=int(n_top/3)
+        plt.figure(figsize=[5, height_])
+        ax1=plot.plotxy(
+            data=results_df.head(n_top),
+            kind="barplot",
+            x="-log10(Adjusted P-value)",
+            y="Term",
+            hue="Term",
+            palette=palette,
+            legend=None,
+        )
+        if dir_save: 
+            ips.figsave(f"{dir_save} enr_barplot.pdf")
+        plot.figsets(ax=ax1, **kws_figsets)
+        plt.show()
+
+        #! dotplot 
+        cutoff_curr = cutoff
+        step=0.05
+        cutoff_stop = 0.5
+        while cutoff_curr <=cutoff_stop:
+            try:
+                print(kws_figsets)
+                if cutoff_curr!=cutoff:
+                    plt.clf()
+                ax2 = gp.dotplot(enr.res2d, 
+                                column="Adjusted P-value",
+                                show_ring=show_ring,
+                                xticklabels_rot=xticklabels_rot,
+                                title=title,
+                                cmap=cmap,
+                                cutoff=cutoff_curr,
+                                top_term=n_top,
+                                figsize=[6, height_])
+                if len(ax2.collections)>=n_top: 
+                    print(f"cutoff={cutoff_curr} done! ")
+                    break 
+                if cutoff_curr==cutoff_stop:
+                    break
+                cutoff_curr+=step
+            except Exception as e:
+                cutoff_curr+=step
+                print(f"Warning: trying cutoff={cutoff_curr}, cutoff={cutoff_curr-step} failed: {e} ")
+            ax = plt.gca()
+            plot.figsets(ax=ax,**kws_figsets)
+            
+        if dir_save:
+            ips.figsave(f"{dir_save}enr_dotplot.pdf")
+
+    return results_df
+
+
+#! https://string-db.org/help/api/
+
+import pandas as pd
+import requests
+import networkx as nx
+import matplotlib.pyplot as plt
+from io import StringIO
+from py2ls import ips
+
+
+def get_ppi(
+    target_genes:list,
+    species:int=9606, # "human"
+    ci:float=0.1, # int 1~1000
+    max_nodes:int=50,
+    base_url:str="https://string-db.org",
+    gene_mapping_api:str="/api/json/get_string_ids?",
+    interaction_api:str="/api/tsv/network?",
+):
+    """
+    Generate a Protein-Protein Interaction (PPI) network using STRINGdb data.
+
+    return:
+    the STRING protein-protein interaction (PPI) data, which contains information about 
+    predicted and experimentally validated associations between proteins.
+    
+    stringId_A and stringId_B: Unique identifiers for the interacting proteins based on the 
+    STRING database.
+    preferredName_A and preferredName_B: Standard gene names for the interacting proteins.
+    ncbiTaxonId: The taxon ID (9606 for humans).
+    score: A combined score reflecting the overall confidence of the interaction, which aggregates different sources of evidence.
+
+    nscore, fscore, pscore, ascore, escore, dscore, tscore: These are sub-scores representing the confidence in the interaction based on various evidence types:
+    - nscore: Neighborhood score, based on genes located near each other in the genome.
+    - fscore: Fusion score, based on gene fusions in other genomes.
+    - pscore: Phylogenetic profile score, based on co-occurrence across different species.
+    - ascore: Coexpression score, reflecting the likelihood of coexpression.
+    - escore: Experimental score, based on experimental evidence.
+    - dscore: Database score, from curated databases.
+    - tscore: Text-mining score, from literature co-occurrence.
+
+    Higher score values (closer to 1) indicate stronger evidence for an interaction.
+    - Combined score: Useful for ranking interactions based on overall confidence. A score >0.7 is typically considered high-confidence.
+    - Sub-scores: Interpret the types of evidence supporting the interaction. For instance:
+    - High ascore indicates strong evidence of coexpression.
+    - High escore suggests experimental validation.
+
+    """
+    print("check api: https://string-db.org/help/api/")
+    
+    # 将species转化为taxon_id
+    if isinstance(species,str):
+        print(species)
+        species=list(get_taxon_id(species).values())[0]
+        print(species)
+        
+    
+    string_api_url = base_url + gene_mapping_api
+    interaction_api_url = base_url + interaction_api
+    # Map gene symbols to STRING IDs
+    mapped_genes = {}
+    for gene in target_genes:
+        params = {"identifiers": gene, "species": species, "limit": 1}
+        response = requests.get(string_api_url, params=params)
+        if response.status_code == 200:
+            try:
+                json_data = response.json()
+                if json_data:
+                    mapped_genes[gene] = json_data[0]["stringId"]
+            except ValueError:
+                print(
+                    f"Failed to decode JSON for gene {gene}. Response: {response.text}"
+                )
+        else:
+            print(
+                f"Failed to fetch data for gene {gene}. Status code: {response.status_code}"
+            )
+    if not mapped_genes:
+        print("No mapped genes found in STRING database.")
+        return None
+
+    # Retrieve PPI data from STRING API
+    string_ids = "%0d".join(mapped_genes.values())
+    params = {
+        "identifiers": string_ids,
+        "species": species,
+        "required_score": int(ci * 1000),
+        "limit": max_nodes,
+    }
+    response = requests.get(interaction_api_url, params=params)
+
+    if response.status_code == 200:
+        try:
+            interactions = pd.read_csv(StringIO(response.text), sep="\t")
+        except Exception as e:
+            print("Error reading the interaction data:", e)
+            print("Response content:", response.text)
+            return None
+    else:
+        print(
+            f"Failed to retrieve interaction data. Status code: {response.status_code}"
+        )
+        print("Response content:", response.text)
+        return None
+    display(interactions.head())
+    # Filter interactions by ci score
+    if "score" in interactions.columns:
+        interactions = interactions[interactions["score"] >= ci]
+        if interactions.empty:
+            print("No interactions found with the specified confidence.")
+            return None
+    else:
+        print("The 'score' column is missing from the retrieved data. Unable to filter by confidence interval.")
+    if "fdr" in interactions.columns:
+        interactions=interactions.sort_values(by="fdr",ascending=False)
+    return interactions
+# * usage
+# interactions = get_ppi(target_genes, ci=0.0001)
+
+def plot_ppi(
+    interactions,
+    player1="preferredName_A",
+    player2="preferredName_B",
+    weight="score",
+    n_layers=None,  # Number of concentric layers
+    n_rank=[5, 10],  # Nodes in each rank for the concentric layout
+    dist_node = 10,  # Distance between each rank of circles
+    layout="degree", 
+    size='auto',#700,
+    facecolor="skyblue",
+    cmap='coolwarm',
+    edgecolor="k",
+    edgelinewidth=1.5,
+    alpha=.5,
+    marker="o",
+    node_hideticks=True,
+    linecolor="gray",
+    linewidth=1.5,
+    linestyle="-",
+    line_arrowstyle='-',
+    fontsize=10,
+    fontcolor="k",
+    ha:str="center",
+    va:str="center",
+    figsize=(12, 10),
+    k_value=0.3,    
+    bgcolor="w",
+    dir_save="./ppi_network.html",
+    physics=True,
+    notebook=False,
+    scale=1,
+    ax=None,
+    **kwargs
+):
+    """
+    Plot a Protein-Protein Interaction (PPI) network with adjustable appearance.
+    """
+    from pyvis.network import Network
+    import networkx as nx 
+    from IPython.display import IFrame
+    from matplotlib.colors import Normalize
+    from matplotlib import cm
+    # Check for required columns in the DataFrame
+    for col in [player1, player2, weight]:
+        if col not in interactions.columns:
+            raise ValueError(f"Column '{col}' is missing from the interactions DataFrame.")
+    
+    # Initialize Pyvis network
+    net = Network(height="750px", width="100%", bgcolor=bgcolor, font_color=fontcolor)
+    net.force_atlas_2based(
+        gravity=-50, central_gravity=0.01, spring_length=100, spring_strength=0.1
+    ) 
+    net.toggle_physics(physics)
+
+    kws_figsets = {}
+    for k_arg, v_arg in kwargs.items():
+        if "figset" in k_arg:
+            kws_figsets = v_arg
+            kwargs.pop(k_arg, None)
+            break
+
+    # Create a NetworkX graph from the interaction data
+    G = nx.Graph()
+    for _, row in interactions.iterrows():
+        G.add_edge(row[player1], row[player2], weight=row[weight])
+
+    # Calculate node degrees
+    degrees = dict(G.degree())
+    norm = Normalize(vmin=min(degrees.values()), vmax=max(degrees.values()))
+    colormap = cm.get_cmap(cmap)  # Get the 'coolwarm' colormap
+
+    # Set properties based on degrees
+    if not isinstance(size, (int,float,list)):
+        size = [deg * 50 for deg in degrees.values()]  # Scale sizes
+    if not ips.isa(facecolor, 'color'):
+        facecolor = [colormap(norm(deg)) for deg in degrees.values()]  # Use colormap
+    if size is None:
+        size = [700] * G.number_of_nodes()  # Default size for all nodes
+    elif isinstance(size, (int, float)):
+        size = [size] * G.number_of_nodes()  # If a scalar, apply to all nodes
+    # else:
+    #     size = size.tolist()  # Ensure size is a list
+    if len(size)>G.number_of_nodes():
+        size=size[:G.number_of_nodes()]
+
+    for node in G.nodes():
+        net.add_node(
+            node,
+            label=node,
+            size=size[list(G.nodes()).index(node)] if isinstance(size,list) else size[0],
+            color=facecolor[list(G.nodes()).index(node)] if isinstance(facecolor,list) else facecolor,
+            font={"size": fontsize, "color": fontcolor},
+        )
+
+    for edge in G.edges(data=True):
+        net.add_edge(
+            edge[0],
+            edge[1],
+            weight=edge[2]["weight"],
+            color=edgecolor,
+            width=edgelinewidth * edge[2]["weight"],
+        )
+    layouts = [
+        "spring",
+        "circular",
+        "kamada_kawai",
+        "random",
+        "shell",
+        "planar",
+        "spiral",
+        "degree"
+    ]
+    layout = ips.strcmp(layout, layouts)[0]
+    print(layout)
+    # Choose layout
+    if layout == "spring":
+        pos = nx.spring_layout(G, k=k_value)
+    elif layout == "circular":
+        pos = nx.circular_layout(G)
+    elif layout == "kamada_kawai":
+        pos = nx.kamada_kawai_layout(G)
+    elif layout == "spectral":
+        pos = nx.spectral_layout(G)
+    elif layout == "random":
+        pos = nx.random_layout(G)
+    elif layout == "shell":
+        pos = nx.shell_layout(G)
+    elif layout == "planar":
+        if nx.check_planarity(G)[0]:
+            pos = nx.planar_layout(G)
+        else:
+            print("Graph is not planar; switching to spring layout.")
+            pos = nx.spring_layout(G, k=k_value)
+    elif layout == "spiral":
+        pos = nx.spiral_layout(G)
+    elif layout=='degree':
+        # Calculate node degrees and sort nodes by degree
+        degrees = dict(G.degree())
+        sorted_nodes = sorted(degrees.items(), key=lambda x: x[1], reverse=True)
+
+        # Create positions for concentric circles based on n_layers and n_rank
+        pos = {}
+        n_layers=len(n_rank)+1 if n_layers is None else n_layers
+        for rank_index in range(n_layers):
+            if rank_index < len(n_rank):
+                nodes_per_rank = n_rank[rank_index]
+                rank_nodes = sorted_nodes[sum(n_rank[:rank_index]): sum(n_rank[:rank_index + 1])]
+            else:
+                # 随机打乱剩余节点的顺序
+                remaining_nodes = sorted_nodes[sum(n_rank[:rank_index]):]
+                random_indices = np.random.permutation(len(remaining_nodes)) 
+                rank_nodes = [remaining_nodes[i] for i in random_indices]
+
+            radius = (rank_index + 1) * dist_node  # Radius for this rank
+
+            # Arrange nodes in a circle for the current rank
+            for i, (node, degree) in enumerate(rank_nodes):
+                angle = (i / len(rank_nodes)) * 2 * np.pi  # Distribute around circle
+                pos[node] = (radius * np.cos(angle), radius * np.sin(angle))
+
+    else:
+        print(f"Unknown layout '{layout}', defaulting to 'spring',or可以用这些: {layouts}")
+        pos = nx.spring_layout(G, k=k_value)
+
+    for node, (x, y) in pos.items():
+        net.get_node(node)["x"] = x * scale
+        net.get_node(node)["y"] = y * scale
+
+    # If ax is None, use plt.gca()
+    if ax is None:
+        fig, ax = plt.subplots(1,1,figsize=figsize)
+
+    # Draw nodes, edges, and labels with customization options
+    nx.draw_networkx_nodes(
+        G,
+        pos,
+        ax=ax,
+        node_size=size,
+        node_color=facecolor,
+        linewidths=edgelinewidth,
+        edgecolors=edgecolor,
+        alpha=alpha,
+        hide_ticks=node_hideticks,
+        node_shape=marker
+    )
+    nx.draw_networkx_edges(
+        G, 
+        pos, 
+        ax=ax, 
+        edge_color=linecolor, 
+        width=linewidth,
+        style=linestyle,
+        arrowstyle=line_arrowstyle, 
+        alpha=0.7
+    )
+    nx.draw_networkx_labels(
+        G, pos, ax=ax, font_size=fontsize, font_color=fontcolor,horizontalalignment=ha,verticalalignment=va
+    )
+    plot.figsets(ax=ax,**kws_figsets)
+    ax.axis("off")
+    net.write_html(dir_save)
+    return G,ax
+
+
+# * usage: 
+# G, ax = bio.plot_ppi(
+#     interactions,
+#     player1="preferredName_A",
+#     player2="preferredName_B",
+#     weight="score",
+#     # size="auto",
+#     # size=interactions["score"].tolist(),
+#     # layout="circ",
+#     n_rank=[5, 10, 15],
+#     dist_node=100,
+#     alpha=0.6,
+#     linecolor="0.8",
+#     linewidth=1,
+#     figsize=(8, 8.5),
+#     cmap="jet",
+#     edgelinewidth=0.5,
+#     # facecolor="#FF5F57",
+#     fontsize=10,
+#     # fontcolor="b",
+#     # edgecolor="r",
+#     # scale=100,
+#     # physics=False,
+#     figsets=dict(title="ppi networks"),
+# )
+# figsave("./ppi_network.pdf")
+  
+def top_ppi(interactions, n_top=10):
+    """
+    Analyzes protein-protein interactions (PPIs) to identify key proteins based on
+    degree and betweenness centrality.
+
+    Parameters:
+        interactions (pd.DataFrame): DataFrame containing PPI data with columns
+                                      ['preferredName_A', 'preferredName_B', 'score'].
+
+    Returns:
+        dict: A dictionary containing the top key proteins by degree and betweenness centrality.
+    """
+
+    # Create a NetworkX graph from the interaction data
+    G = nx.Graph()
+    for _, row in interactions.iterrows():
+        G.add_edge(row["preferredName_A"], row["preferredName_B"], weight=row["score"])
+
+    # Calculate Degree Centrality
+    degree_centrality = G.degree()
+    key_proteins_degree = sorted(degree_centrality, key=lambda x: x[1], reverse=True)
+
+    # Calculate Betweenness Centrality
+    betweenness_centrality = nx.betweenness_centrality(G)
+    key_proteins_betweenness = sorted(
+        betweenness_centrality.items(), key=lambda x: x[1], reverse=True
+    )
+    print(
+        {
+            "Top 10 Key Proteins by Degree Centrality": key_proteins_degree[:10],
+            "Top 10 Key Proteins by Betweenness Centrality": key_proteins_betweenness[
+                :10
+            ],
+        }
+    )
+    # Return the top n_top key proteins
+    if n_top == "all":
+        return key_proteins_degree, key_proteins_betweenness
+    else:
+        return key_proteins_degree[:n_top], key_proteins_betweenness[:n_top]
+
+
+# * usage: top_ppi(interactions)
+# top_ppi(interactions, n_top="all")
+# top_ppi(interactions, n_top=10)
+
+
+
+species_dict = {
+    "Human": "Homo sapiens",
+    "House mouse": "Mus musculus",
+    "Zebrafish": "Danio rerio",
+    "Norway rat": "Rattus norvegicus",
+    "Fruit fly": "Drosophila melanogaster",
+    "Baker's yeast": "Saccharomyces cerevisiae",
+    "Nematode": "Caenorhabditis elegans",
+    "Chicken": "Gallus gallus",
+    "Cattle": "Bos taurus",
+    "Rice": "Oryza sativa",
+    "Thale cress": "Arabidopsis thaliana",
+    "Guinea pig": "Cavia porcellus",
+    "Domestic dog": "Canis lupus familiaris",
+    "Domestic cat": "Felis catus",
+    "Horse": "Equus caballus",
+    "Domestic pig": "Sus scrofa",
+    "African clawed frog": "Xenopus laevis",
+    "Great white shark": "Carcharodon carcharias",
+    "Common chimpanzee": "Pan troglodytes",
+    "Rhesus macaque": "Macaca mulatta",
+    "Water buffalo": "Bubalus bubalis",
+    "Lettuce": "Lactuca sativa",
+    "Tomato": "Solanum lycopersicum",
+    "Maize": "Zea mays",
+    "Cucumber": "Cucumis sativus",
+    "Common grape vine": "Vitis vinifera",
+    "Scots pine": "Pinus sylvestris",
+}
+
+
+def get_taxon_id(species_list):
+    """
+    Convert species names to their corresponding taxon ID codes.
+
+    Parameters:
+    - species_list: List of species names (strings).
+
+    Returns:
+    - dict: A dictionary with species names as keys and their taxon IDs as values.
+    """
+    from Bio import Entrez
+
+    if not isinstance(species_list, list):
+        species_list = [species_list]
+    species_list = [
+        species_dict[ips.strcmp(i, ips.flatten(list(species_dict.keys())))[0]]
+        for i in species_list
+    ]
+    taxon_dict = {}
+
+    for species in species_list:
+        try:
+            search_handle = Entrez.esearch(db="taxonomy", term=species)
+            search_results = Entrez.read(search_handle)
+            search_handle.close()
+
+            # Get the taxon ID
+            if search_results["IdList"]:
+                taxon_id = search_results["IdList"][0]
+                taxon_dict[species] = int(taxon_id)
+            else:
+                taxon_dict[species] = None  # Not found
+        except Exception as e:
+            print(f"Error occurred for species '{species}': {e}")
+            taxon_dict[species] = None  # Error in processing
+    return taxon_dict
+
+
+# # * usage: get_taxon_id("human")
+# species_names = ["human", "nouse", "rat"]
+# taxon_ids = get_taxon_id(species_names)
+# print(taxon_ids)