4.5.4 Read density

Purpose

Convert transcriptome-aligned BAM files into transcript-level density files. Read density is the core input for density merging, periodicity, metaplot, coverage, correlation, gene-level analysis, codon-level analysis, and smORF analysis.

rna_Density    # RNA-seq:  BAM + RNA-seq offset table -> transcript-level read density
rpf_Density    # Ribo-seq: BAM + P-site offset table  -> P-site density (compact JSONL)

The two commands share the same input layout (annotation, sequence, BAM, offset table) but differ in the offset table they consume and the density they compute:

• rna_Density uses the RNA-seq offset table from rna_Offset and reports transcript coverage.
• rpf_Density uses the P-site offset table from rpf_Offset / rpf_Offset_RSBM and reports offset-corrected ribosome P-site positions.

Both commands write a gzip-compressed compact JSONL by default, which carries a samples field for multi-sample merging, and optionally the legacy codon-level TXT table.

Step 1: Run rna_Density

1.1 Parameters

Parameter	Required	Description
-t, --transcript	Yes	Input transcript annotation file generated by rpf_Reference.
-s, --sequence	Yes	Input transcript sequence file in FASTA format.
-b, --bam	Yes	Input BAM alignment file.
-p, --psite	Yes	Input RNA-seq offset table in TXT format.
-o, --output	Yes	Output prefix. The default JSON output is <prefix>_rna.jsonl.gz.
-l, --longest	No	Only retain the transcript with the longest CDS of each gene. Disabled by default; recommended for gene-level analysis.
-m, --min	No	Minimum read length to keep. Default is 25.
-M, --max	No	Maximum read length to keep. Default is 150.
-r, --rolling	No	Use rolling read assignment. This is mainly suitable for long RNA-seq reads. Disabled by default.
--pe	No	Process paired-end RNA-seq alignments. Disabled by default.
--drop-warning	No	Drop offset rows whose warning column is not PASS when the offset file contains a warning column. Disabled by default.
--silence	No	Discard warning information. Disabled by default.
--output-format	No	Output format: json (default), txt, or both. json writes gzip-compressed compact JSONL; txt writes the legacy TXT table.
--density-encoding	No	Density encoding in JSONL: sparse (default) or dense. Sparse encoding is recommended.
--thread	No	Number of workers for indexed BAM parallel scanning. If the BAM is not indexed, stream mode is used. Default is 1.

1.2 Example

cd ./sce/4.ribo-seq/04.density/

for bam in ../01.qc/*.bam
do
    prefix_name=$(basename ${bam} .bam)

    rna_Density \
        -b ${bam} \
        -t ../../../1.reference/norm/gene.norm.txt \
        -s ../../../1.reference/norm/gene.norm.rna.fa \
        -p ../03.offset/${prefix_name}_offset.txt \
        -o ${prefix_name} \
        -l \
        -m 25 \
        -M 150 \
        --thread 10 \
        &> ${prefix_name}.log
done

1.3 Output

Output	Description
<prefix>_rna.jsonl.gz	Gzip-compressed compact RNA-seq density JSONL (default). The JSON uses a samples field to support downstream multi-sample merging.
<prefix>_rna.txt	Legacy codon-level TXT density table, written when --output-format is txt or both.
<prefix>_rna.summary.json	Running summary containing the sample name, input files, filter settings, and scan statistics.
<prefix>.log	Running log if redirected by the user.

Step 2: Run rpf_Density

2.1 Parameters

Parameter	Required	Description
-t, --transcript	Yes	Input transcript annotation file in RiboParser norm TXT or genePred format.
-s, --sequence	Yes	Input transcript sequence file in FASTA format.
-b, --bam	Yes	Input transcriptome-aligned mapping file in BAM or SAM format.
-p, --psite	Yes	Input P-site offset file in TXT format.
-o, --output	Yes	Output prefix. The default JSON output is <prefix>_rpf.jsonl.gz.
-l, --longest	No	Only retain the transcript with the longest CDS of each gene. Disabled by default; recommended.
-m, --min	No	Minimum read length to keep. Default is 27.
-M, --max	No	Maximum read length to keep. Default is 33.
--period	No	Minimum 3-nt periodicity to keep. Default is 40.
--drop-warning	No	Drop offset rows whose warning column is not PASS when the offset file contains a warning column. Disabled by default.
--silence	No	Discard warning information. Disabled by default.
--output-format	No	Output format: json (default), txt, or both. json writes gzip-compressed compact JSONL; txt writes the legacy TXT table.
--density-encoding	No	Density encoding in JSONL: sparse (default) or dense. Sparse encoding is recommended.
--thread	No	Number of workers for indexed BAM parallel scanning. If the BAM is not indexed, stream mode is used. Default is 1.

2.2 Example

for bam in ../01.qc/*.bam
do
    prefix_name=$(basename ${bam} .bam)

    rpf_Density \
        -b ${bam} \
        -t ../../../1.reference/norm/gene.norm.txt \
        -s ../../../1.reference/norm/gene.norm.rna.fa \
        -p ../03.offset/${prefix_name}_SSCBM_offset.txt \
        -o ${prefix_name} \
        -l \
        -m 27 \
        -M 33 \
        --period 40 \
        --output-format both \
        --thread 12 \
        &> ${prefix_name}.log
done

2.3 Output

Output	Description
<prefix>_rpf.jsonl.gz	Gzip-compressed compact RPF density JSONL (default). The JSON uses a samples field to support downstream multi-sample merging.
<prefix>_rpf.txt	Legacy codon-level TXT density table, written when --output-format is txt or both.
<prefix>_rpf.summary.json	Running summary containing the sample name, input files, filter settings, and scan statistics.
<prefix>.log	Running log if redirected by the user.

Notes

• RNA-seq density represents transcript coverage, whereas Ribo-seq density represents offset-corrected ribosome P-site positions.
• Use consistent transcript annotation and transcript FASTA files across all samples.
• Both rna_Density and rpf_Density write compact JSONL by default. Use --output-format txt or both if the legacy TXT table is required, or convert the JSONL afterwards.
• Use --drop-warning to discard P-site offset rows flagged as not PASS when the offset table contains a warning column.
• Ribo-seq density should be validated with periodicity and metagene analysis before codon-level interpretation.

Output file formats

rpf_Density writes two interchangeable density formats: a gzip-compressed compact JSONL file (default) and a legacy codon-level TXT file (written with --output-format txt or both).

JSON format (<prefix>_rpf.jsonl.gz)

The file is gzip-compressed; every line is one JSON record for one transcript, containing the transcript annotation, trimmed range, sequence, and per-sample density arrays.

Field	Description
record_type	Record type; always transcript.
transcript_id / gene_id / name	Transcript ID, gene ID, and transcript name.
chromosome / strand	Chromosome and strand of the transcript.
length_nt / utr5_nt / cds_nt / utr3_nt	Total transcript length and the UTR5/CDS/UTR3 lengths in nucleotides.
annotation	Source annotation metadata: coordinate system (0-based-half-open), exon structure (exon_starts/exon_ends/exon_frames), CDS completeness (cds_start_stat/cds_end_stat), and the representative flag.
genome_mapping	Transcript-to-genome mapping segments (transcript_start/transcript_end/genome_start/genome_end per exon).
trim	Trimming result: shifted/trimmed range (start_nt0/end_nt0), codon_count, and UTR/CDS codon counts.
sequence	Transcript nucleotide sequence.
samples	Per-sample density profiles, keyed by sample name.
samples.<sample>.profile	Read profile of the sample, e.g. monosome.
samples.<sample>.density	Density arrays: encoding (sparse_codon_frame), index_base (0), and the parallel arrays codon_index/frame/count.

TXT format (<prefix>_rpf.txt)

Tab-separated codon-level table. One row per codon position; the frame columns are repeated for every sample.

Column	Description
name	Transcript ID.
now_nt	Current position along the transcript in nucleotides (1-based).
from_tis	Distance from the translation initiation site, in codons (negative values are upstream of TIS).
from_tts	Distance from the translation termination site, in codons (negative values are upstream of TTS).
region	Region of the position: 5utr, cds, or 3utr.
codon	Codon sequence at this position.
<sample>_f0 / <sample>_f1 / <sample>_f2	P-site counts of the sample in reading frames 0, 1, and 2.

The JSONL format is recommended because it is compact, preserves the full transcript annotation, and carries the samples field for multi-sample merging; the TXT format is kept for compatibility with legacy workflows.