pepkio-safe-table-bio

A Python package and client for preserving gene identifiers in bioinformatics tables, resolving HGNC symbol aliases, and generating reproducible data cleaning workflows.

What It Does

safe-table-bio (and its Python client pepkio-safe-table-bio) provides identifier-safe tabular data processing for genomics and life science research. Standard spreadsheet tools often corrupt gene symbols (converting SEPT9, MARCH1, OCT4, or DEC1 to calendar dates) and truncate long numeric accessions (like RefSeq or Ensembl IDs) into scientific notation. safe-table-bio enforces strict string data types during parsing, reconciles outdated or alias gene names against current HUGO Gene Nomenclature Committee (HGNC) standards, filters expression matrices, executes relational joins, reshapes wide/long data, and generates reproducible workflow scripts in Python (pandas), R (dplyr), and csvtk.

Features

• Gene-Safe Identifier Preservation: Parses CSV/TSV files with string-locking rules to prevent Excel date coercion and numerical truncation of accession IDs.
• HGNC Symbol Reconciliation: Maps legacy gene symbols and historical aliases to approved HGNC standard names (e.g., MARCH1 $\rightarrow$ MARCHF1, SEPT9 $\rightarrow$ SEPTIN9).
• Matrix Filtering & Joins: Applies single or multi-column filter rules ($\text{Log}_2\text{FC}$, p-value, FDR) and performs inner/left/outer joins without key corruption.
• Tidy Data Reshaping: Converts between wide matrix layouts (gene-by-sample) and long tidy structures for downstream statistical analysis.
• Reproducible Code Generation: Automatically emits executable Python (pandas), R (dplyr), and csvtk bash scripts matching every table operation.
• Multi-Format Export: Generates clean CSV, TSV, and safe Excel (.xlsx) files.

Installation

pip install pepkio-safe-table-bio

Quick Example

from pepkio_safe_table_bio.client import PepkioClient

# Initialize client (uses PEPKIO_API_KEY environment variable)
with PepkioClient() as client:
    # 1. Fetch built-in genomics example dataset
    example_input = client.get_example_input("load_example")
    result = client.run(example_input)
    print(f"Loaded rows: {len(result.result['table']['rows'])}")

    # 2. Standardize gene symbols using HGNC reconciliation
    hgnc_input = {
        "tab": "editor",
        "table": result.result["table"],
        "apply_hgnc_column": "GENE_ID"
    }
    hgnc_result = client.run(hgnc_input)

    # 3. Filter for genes with LOG2FC > 1.0 and generate scripts
    filter_input = {
        "tab": "editor",
        "table": hgnc_result.result["table"],
        "apply_filter": [{"column": "LOG2FC", "operator": "gt", "value": "1.0"}],
        "generate_scripts": True
    }
    filter_result = client.run(filter_input)

    # Print auto-generated Python pandas code
    scripts = filter_result.result.get("scripts", {})
    if "python" in scripts:
        print("\n--- Generated Python (pandas) Code ---")
        print(scripts["python"])

Command-line usage:

pepkio-safe-table-bio run --example filter_high_fc

Typical Use Cases

• Gene Symbol Date Protection: Eliminate silent date conversion (SEPT9 to 09-Sep, MARCH1 to 01-Mar) in CSV/TSV supplementary tables.
• HGNC Symbol Reconciliation: Update outdated gene aliases to official HGNC symbols before manuscript submission.
• Differential Expression Cleanup: Filter RNA-seq or microarray results by $\text{Log}_2\text{FC}$ and FDR thresholds while preserving text IDs.
• Multi-Omics Annotation Merging: Perform left outer joins to combine intensity matrices with functional annotations without truncating accession IDs.
• Wide-to-Long Tidy Reshaping: Melt wide gene-by-sample expression matrices into long tidy tables for plotting with seaborn or ggplot2.
• qPCR & Assay Dilution Calculations: Prepare serial dilution series, standard curves, and plate layout calculations ($C_1 V_1 = C_2 V_2$).

Scientific Background

• Excel Date Coercion Mechanics: General-purpose spreadsheet applications parse unformatted CSV text against date patterns (D-MMM, MMM-D). Gene symbols such as SEPT9, MARCH1, OCT4, and DEC1 are automatically converted to calendar dates (09-Sep, 01-Mar) or serial integers, causing irreversible data loss when saved.
• HGNC Standardization Guidelines: In 2020, the HUGO Gene Nomenclature Committee updated gene symbols prone to spreadsheet date coercion (e.g., MARCH1 $\rightarrow$ MARCHF1, SEPT9 $\rightarrow$ SEPTIN9). Symbol reconciliation maps historical aliases to current approved standards.
• Key Formulas:
  • Base-2 Log Fold-Change: $\text{Log}2\text{FC} = \log_2(\bar{X}{\text{treatment}} / \bar{X}_{\text{control}})$
  • False Discovery Rate (FDR): Benjamini-Hochberg procedure controlling false positive rates across multi-hypothesis testing.
  • Dilution Conservation: $C_1 V_1 = C_2 V_2$ and dilution factor $\text{DF} = V_2 / V_1 = C_1 / C_2$.

Web Application

For researchers who prefer a graphical interface, an interactive web version is available.

Web Application: https://www.pepkio.com/tools/safe-table-bio

Key web-only features include:

• Interactive drag-and-drop CSV/TSV table editor with instant row delta previews.
• Visual HGNC symbol reconciliation dashboard linking directly to official HGNC locus entries.
• Dynamic column profiler providing missing-value diagnostics and histogram distributions.
• Step-by-step session history with one-click revert and shareable permalinks (https://tools.pepkio.com/r/<runId>).
• Clipboard-ready code export for Python (pandas), R (dplyr), and csvtk.

Documentation and Resources

GitHub Repository: https://github.com/pepkio/pepkio-safe-table-bio

Web Application: https://www.pepkio.com/tools/safe-table-bio

Source code and issue tracker: https://github.com/pepkio/pepkio-safe-table-bio

About Pepkio

Pepkio develops software tools and provides bioinformatics analysis services for life science research. See https://www.pepkio.com for additional tools and analysis services (https://www.pepkio.com/cro).

Keywords

safe-table-bio pepkio-safe-table-bio gene symbol protection Excel date corruption fix HGNC symbol reconciliation gene expression matrix cleaner CSV TSV table editor bioinformatics table processor SEPT9 MARCH1 date fix Ensembl ID preservation RefSeq accession protection RNA-seq matrix filter log2 fold change filter FDR adjusted p-value relational matrix join wide to long reshape tidy data conversion reproducible script generator pandas biological table dplyr gene table csvtk table editor qPCR standard curve serial dilution calculator C1V1 C2V2 dilution supplementary table cleaner laboratory dataset auditor

how to stop excel from changing gene names to dates prevent Excel date conversion of SEPT9 and MARCH1 HGNC gene symbol reconciliation tool filter RNA-seq differential expression matrix by log2 fold change convert wide gene expression matrix to long format reproducible script generator for biological CSV editing safe Excel export for gene lists without date corruption how to calculate dilution factor for qPCR standard curve C1V1 C2V2 stock dilution formula for laboratory assays merge gene expression matrix with annotations using left join how to fix corrupted gene symbols in supplementary tables python client for biological safe table processing bioinformatics table parser with text string enforcement automated script generation for pandas and dplyr