miRClass

miRClass is a genome-wide plant miRNA discovery pipeline. Its cross-species core uses only precursor sequence and predicted secondary-structure features, while optional plugins can incorporate species-specific experimental evidence.

Species and plugin boundaries

• Set the prediction species with species.scientific_name in config/config.yaml.
• The sequence–structure model is the core workflow. It can run on any species, but cross-species predictions require independent validation or recalibration.
• arabidopsis_multimutant_v1 supports only Arabidopsis thaliana. The plugin is skipped automatically for other species, and unavailable mutant evidence is never interpreted as negative evidence.
• Integrated output tables retain core_mirna_score and species_specific_mutant_score separately. The mutant_plugin_applied and species_specific_evidence_status columns record whether the evidence is applicable.
• High-confidence thresholds from the target model apply only to the calibration species. For other species, the model produces ranking scores and leaves high_confidence_prediction unset.

Current dataset definition

• Labels were derived from all_308_miRNA_reclassification.csv in the curated publication package.
• Positive set: 203 high_conf_miRNA precursors.
• Explicit negative set: 54 non_miRNA precursor-like loci.
• Unlabeled audit set: 51 ambiguous loci, excluded from model training and threshold selection.
• The publication GFF was used to verify the 203 positive identifiers. Coordinates and strand assignments were standardized against the corresponding miRBase GFF because the publication GFF contained 75 one-base coordinate offsets and 16 entries without strand information.
• V1 was trained only on local A. thaliana data and has not yet demonstrated cross-plant generalization.

Method overview

1. Split data by miRNA family and lock an independent test set to prevent leakage between homologous precursors.
2. Extract 1–4-mer frequencies, GC content, sequence entropy, MFE, centroid, MEA, ensemble diversity, stem/loop, and sequence–structure triplet features.
3. Compare elastic-net and random-forest models using nested StratifiedGroupKFold, then perform Platt calibration using out-of-fold development predictions.
4. Select two development-set thresholds to classify candidates as high_conf_miRNA, ambiguous, or non_miRNA.
5. During genome scanning, use RNALfold on both strands to identify local hairpins. The V1 prefilter uses a maximum 150-nt pairing span and normalized MFE ≤ -0.25 before applying the classifier.

The reported “probability” is a score calibrated against the current curated development set. It is not an absolute posterior probability under the true genome-wide class prevalence.

Installation and usage

Input data and trained models are intentionally excluded from this repository. Update the paths in config/config.yaml before running the workflow.

cd miRClass
mamba env create -p .conda -f environment.yml
conda activate "$(pwd)/.conda"export XDG_CACHE_HOME="$(pwd)/.cache"
snakemake -s workflow/Snakefile --cores 24

After training, run the integrated genome scan with:

snakemake -s workflow/Snakefile --cores 24 genome_scan_complete

Main outputs

• data/processed/labeled_precursors.tsv: labels, coordinates, families, and precursor sequences.
• data/processed/precursor_features.tsv: sequence–structure feature matrix.
• models/mirna_seqstruct_v1.joblib: fitted model, calibrator, thresholds, and feature schema.
• results/training_report.json: nested validation and locked-test metrics.
• results/locked_test_predictions.tsv: predictions for the locked test set.
• results/all_308_sequence_structure_predictions.tsv: compact predictions for all 308 curated loci, including the 51 ambiguous audit loci.
• results/figures/: model curves, score distributions, structural features, confusion matrices, and candidate-recall figures in PNG and PDF formats.

Regenerate the core model figures with:

Rscript scripts/plot_model_results.R

miRNA–target model (V1)

The downstream target-ranking model is trained from data/Arabidopsis_thaliana_targetGene.txt. To reduce label circularity, pairs supported by degradome categories 0–2 and a validation library are treated as strong positives. Category 3–4 pairs and pairs supported only by prediction tools are retained as an audit set. Negative examples are explicitly labeled unreported pseudo-negatives and must not be interpreted as experimentally confirmed negatives.

Transcript sequences must be spliced transcripts generated from the Araport11 GFF and TAIR10 genome, for example data/reference/Araport11_spliced_transcripts.fa. Gene-locus FASTA files containing introns are not suitable.

Run the target model with:

bash scripts/run_target_model.sh

The model uses GroupKFold by miRNA family and extracts the globally best complementary site, seed and position 10–11 mismatches, G:U pairs, consecutive mismatches, site position, and a local duplex score. Adding --use-rnahybrid also calculates RNAhybrid MFE, but substantially increases runtime. A newly predicted precursor must first have a 20–24 nt mature miRNA sequence inferred from a small-RNA peak before target prediction.

Important limitations

• The current dataset contains only 54 explicit negatives. Future hard-negative mining must use hairpins with reliable non-miRNA annotations.
• unclassified, low-expression, and ordinary unannotated hairpins must not be used directly as negative examples.
• Before a production genome scan, the candidate generator must recover at least 95% of the 203 known positive loci.
• The current prefilter recovers 194 of 203 known positives (95.6%). Genome-wide runs should still be parallelized by chromosome and report candidate density.
• The locked test set must never be used for parameter selection, threshold selection, or feature selection.