Metadata-Version: 2.5
Name: pepkio-safe-table-bio
Version: 0.1.0
Summary: Python client for Pepkio safe-table-bio tool
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# 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

```bash
pip install pepkio-safe-table-bio
```

# Quick Example

```python
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:

```bash
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
