rpf_Retrieve¶

rpf_Retrieve retrieves selected transcript/gene records from a merged RPF density table and optionally filters, normalizes, reshapes, or splits the result.

Function¶

Use this command when you want to:

keep only transcripts listed in a gene/transcript ID file;
keep only transcripts with enough RPF counts;
convert raw RPF counts to RPM;
convert frame-specific columns into a longer table;
export one retrieved file per gene/transcript.

Input¶

The input file should be a merged RPF density table generated by RiboParser, usually from rpf_Merge. The table is expected to contain the annotation columns followed by sample frame columns:

name  now_nt  from_tis  from_tts  region  codon  sample1_f0  sample1_f1  sample1_f2  ...

The optional gene list should be a plain text file with one transcript/gene ID per line.

Parameters¶

Parameter	Required	Meaning
`-r`	yes	Input merged RPF density file in TXT/TSV format.
`-o`	yes	Output prefix. The main output is written as `<prefix>_retrieve.txt`. In the current implementation, provide this argument to avoid an empty output prefix.
`-l`	no	Transcript/gene ID list file. Each line should contain one ID. If omitted, filtering is only controlled by `-m`.
`-m`	no	Minimum total RPF count used to retain transcripts. Default: `0`.
`-n`	no	Normalize RPF counts to RPM. Default: disabled.
`-f`	no	Convert frame-specific columns such as `sample_f0`, `sample_f1`, and `sample_f2` into a longer table with frame information. Default: disabled.
`-s`	no	Split retrieved results into one TXT file per gene/transcript. Default: disabled.

Output¶

When -s is not used, the command writes:

<prefix>_retrieve.txt

When -s is used, the command writes one file per gene/transcript:

<gene_id>_retrieve.txt

If -n is enabled, the output values are RPM-normalized. If -f is enabled, the table is converted from frame-specific wide columns to a longer format that is easier to use for plotting or downstream summaries.

Examples¶

Retrieve transcripts with at least 50 RPF counts:

rpf_Retrieve \
  -r RIBO_merged.txt \
  -m 50 \
  -o RIBO.min50

Retrieve a selected gene/transcript list:

rpf_Retrieve \
  -r RIBO_merged.txt \
  -l target_gene_ids.txt \
  -o RIBO.targets

Retrieve selected genes and normalize counts to RPM:

rpf_Retrieve \
  -r RIBO_merged.txt \
  -l target_gene_ids.txt \
  -n \
  -o RIBO.targets.rpm

Convert the retrieved table to a longer frame-aware format:

rpf_Retrieve \
  -r RIBO_merged.txt \
  -m 0 \
  -f \
  -o RIBO.long

Split retrieved transcripts into separate files:

rpf_Retrieve \
  -r RIBO_merged.txt \
  -l target_gene_ids.txt \
  -s \
  -o RIBO.targets

Notes¶

The command works on RiboParser merged RPF density tables, not directly on BAM files.
Use -l when you need a specific gene set, and use -m when you need expression/count-based filtering.
-f is useful before drawing gene-level density profiles or combining frame information in downstream scripts.
In split mode, the per-gene output file names are based on gene/transcript IDs rather than the -o prefix.