4.5.5 Merge density¶

Purpose¶

Merge per-sample RPF/RNA density files generated by rpf_Density / rna_Density into a single multi-sample density file. Merged density is the core input for periodicity, metaplot, coverage, correlation, gene-level analysis, codon-level analysis, and smORF analysis.

merge_dst_list    # Scan density files (JSONL or TXT) -> tab-delimited sample list
rpf_Merge         # Merge density files listed in the sample list -> merged density + summary

Both JSONL and the legacy TXT density files are supported. The workflow produces a four-column sample list first, then merges the files into a gzip-compressed JSONL (default) or a codon-level TXT table.

Step 1: Run `merge_dst_list`¶

Scan the per-sample density files (or glob patterns) and create a sample list for rpf_Merge. Supported density file suffixes are *_rpf.jsonl.gz, *_rpf.jsonl, *_rpf.json, *_rpf.txt and the corresponding *_rna.* forms.

1.1 Parameters¶

Parameter	Required	Description
`-l`, `--list`	Yes	Input density files or glob patterns, e.g. `'_rpf.jsonl.gz'`, `'_rpf.txt'`, or explicit file paths.
`-o`, `--output`	No	Output sample list file name. Default is `RPF.file.list` for Ribo, `RNA.file.list` for RNA, and `Density.file.list` for mixed lists.
`--allow-mixed-type`	No	Allow Ribo and RNA density files in the same output list. Disabled by default.
`--allow-mixed-format`	No	Allow JSON and TXT density files in the same output list. This is usually not recommended for `rpf_Merge`. Disabled by default.

1.2 Example¶

cd ./sce/4.ribo-seq/05.merge/

# JSONL density files
merge_dst_list -l '*_rpf.jsonl.gz' -o RPF.file.list

# Legacy TXT density files
merge_dst_list -l '*_rpf.txt' -o RPF.file.list

# Multiple explicit files
merge_dst_list -l sample1_rpf.jsonl.gz sample2_rpf.jsonl.gz -o RPF.file.list

1.3 Output¶

The sample list is a tab-delimited table with four columns (Name, File, Type, Format). Name is inferred from the file name, File is the absolute path, Type is Ribo or RNA, and Format is json or txt.

Name        File                                                         Type    Format
SRR1944912  /path/to/SRR1944912_rpf.jsonl.gz                             Ribo    json
SRR1944913  /path/to/SRR1944913_rpf.jsonl.gz                             Ribo    json

Errors are raised for duplicated sample names, unsupported file suffixes, and mixed types/formats (unless explicitly allowed).

Step 2: Run `rpf_Merge`¶

Merge all density files listed in the sample list into a single multi-sample density file.

2.1 Parameters¶

Parameter	Required	Description
`-l`, `--list`	Yes	Sample list table. Required columns: `Name` and `File`. Optional columns: `Type` and `Format`.
`-o`, `--output`	Yes	Output prefix. The output files are `<prefix>_merged.jsonl.gz` and/or `<prefix>_merged.txt`.
`-if`, `--input-format`	No	Input density format: `auto` (default), `json`, or `txt`. In `auto` mode the format is inferred from the file names.
`-of`, `--output-format`	No	Output density format: `auto` (default), `json`, `txt`, or `both`. In `auto` mode, JSON input produces JSON output and TXT input produces TXT output.
`-c`, `--density-encoding`	No	Density encoding used when converting TXT input to JSON: `sparse` (default) or `dense`.
`--thread`	No	Reserved for compatibility. The default streaming merge is usually faster than the worker-based dictionary merge and does not need extra workers. Default is `1`.

2.2 Example¶

cd ./sce/4.ribo-seq/05.merge/

# JSONL input -> merged JSONL (default)
rpf_Merge -l RPF.file.list -o SRR

# Force TXT output (e.g. for legacy downstream tools)
rpf_Merge -l RPF.file.list -o SRR -of txt

# Convert TXT input to merged JSONL
rpf_Merge -l RPF.file.list -o SRR -if txt -of json

2.3 Output¶

Output	Description
`<prefix>_merged.jsonl.gz`	Gzip-compressed merged density JSONL, written when the output format is `json` or `both`. Contains one record per transcript with per-sample density arrays.
`<prefix>_merged.txt`	Merged codon-level TXT density table, written when the output format is `txt` or `both`.
`<prefix>_merged.summary.json`	Merge summary containing the tool name, input/output formats, sample records, output file list, and elapsed time. Always written.

Notes¶

Use the same annotation and transcript FASTA for all samples so that transcript IDs are consistent across density files.
rpf_Merge merges by transcript ID; JSONL records additionally carry per-sample profile names in the samples field.
Mixed JSON/TXT inputs are usually not recommended; convert the TXT files to JSONL with rpf_Density --output-format json first if needed.
Use rpf_Json2txt to convert a JSONL density file (merged or single-sample) to the legacy TXT format for compatibility.