Metadata-Version: 2.4
Name: cell-extract
Version: 1.3.0
Summary: Extract specific columns from multiple tabular files and merge by row identifier.
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bioinformatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: python-semantic-release>=9.0; extra == "dev"

# cell-extract

**Extract specific columns from multiple tabular files and merge them by row identifier.**

`cell-extract` reads CSV or TSV files, extracts a user-specified column from each, and produces a single merged output table. The first column is treated as the row identifier, and rows are unioned across all input files.

## Installation

```bash
pip install -e .
```

Or with dev dependencies (for testing):

```bash
pip install -e ".[dev]"
```

## Quick Start

Given two files:

**alpha.csv**
```
gene,expr,pval
BRCA1,2.3,0.01
TP53,5.1,0.001
```

**beta.csv**
```
gene,expr,pval
BRCA1,4.7,0.02
TP53,3.2,0.05
```

Run:

```bash
cell-extract alpha.csv beta.csv --column expr
```

Output:

```csv
Origin,alpha,beta
BRCA1,2.3,4.7
TP53,5.1,3.2
```

## Usage

```
cell-extract [OPTIONS] FILE [FILE ...]
```

### Required Argument

| Option | Description |
|--------|-------------|
| `--column COLUMN`, `-c COLUMN` | Name of the column to extract from each file |

### Options

| Option | Description |
|--------|-------------|
| `--output FILE`, `-o FILE` | Write output to FILE instead of stdout |
| `--output-format {csv,tsv}`, `-f {csv,tsv}` | Output format (default: csv) |
| `--with-source`, `-s` | Add a `Source` column recording which original column was extracted (useful for tracing/debugging) |
| `--version`, `-V` | Show version and exit |
| `--help`, `-h` | Show help message |

## Behavior

- **Row union**: All row identifiers from all files are included. If a row exists in file A but not file B, the cell for file B will be empty.
- **Empty cells**: Missing values (NaN-equivalent) are written as empty fields.
- **Delimiter detection**: `.csv` → comma; `.tsv` or `.tab` → tab.
- **Output format**: CSV by default; use `-f tsv` for TSV output.
- **First column is the identifier**: The leftmost column is always treated as the row key; it appears as "Origin" in the output header.

## Examples

### Multiple files with different row sets

```bash
cell-extract set1.csv set2.csv set3.csv -c expression
```

### TSV input and output

```bash
cell-extract -c count -f tsv sample_A.tsv sample_B.tsv
```

### Save to file

```bash
cell-extract -c fold_change -o merged.csv *.csv
```

### With source tracing column

```bash
cell-extract alpha.csv beta.csv -c expr -s
# Origin,alpha,beta,Source
# BRCA1,2.3,4.7,expr
# TP53,5.1,3.2,expr
```

Useful when tracking which original column a value came from during debugging.

## Development

Run tests:

```bash
pip install -e ".[dev]"
pytest tests/
```

## License

MIT
