Skip to main content

dima_core/
methods.rs

1//! A methods paragraph and the reference list of a run, for `dima cite --from` and the GUI's
2//! "Export methods & references" (D89): built from the run's recorded parameters and its
3//! `run.references` — and, when given, from the conserved sequences computed from it and their
4//! `references` — so it states exactly what was done and cites exactly what was used.
5
6use std::fmt::Write as _;
7
8use crate::citations::{self, Citation, Cite};
9use crate::config::{Alphabet, Estimator};
10use crate::diagnostics::plural;
11use crate::model::{HcsEligibility, HcsResults, Reference, Results};
12use crate::provenance::SOFTWARE_REFERENCE_KEY;
13
14/// Output formats of a reference list.
15#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
16pub enum CitationFormat {
17    /// Numbered plain-text references.
18    Text,
19    /// BibTeX entries.
20    Bibtex,
21    /// RIS records.
22    Ris,
23    /// A complete `CITATION.cff` with the references.
24    Cff,
25}
26
27/// What a methods text and reference list describe: an analysis, the conserved sequences
28/// computed from one, both, or neither (DiMA itself).
29#[derive(Clone, Copy, Debug, Default)]
30pub struct Cited<'a> {
31    /// The results of an analysis.
32    pub results: Option<&'a Results>,
33    /// Conserved sequences.
34    pub hcs: Option<&'a HcsResults>,
35}
36
37impl<'a> Cited<'a> {
38    /// An analysis.
39    #[must_use]
40    pub const fn results(results: &'a Results) -> Self {
41        Self {
42            results: Some(results),
43            hcs: None,
44        }
45    }
46
47    /// The DiMA version that wrote what is cited, or this one.
48    fn version(&self) -> &'a str {
49        self.results
50            .map(|r| r.run.tool.version.as_str())
51            .or_else(|| self.hcs.map(|h| h.tool.version.as_str()))
52            .unwrap_or(citations::SOFTWARE_VERSION)
53    }
54}
55
56/// A parenthetical citation of several works: `(Rao 1945; Blackwell 1947)`.
57fn cited(keys: &[&'static str]) -> String {
58    let labels: Vec<String> = keys.iter().map(|&k| Cite::new(k).short()).collect();
59    format!("({})", labels.join("; "))
60}
61
62fn estimator_text(e: Estimator) -> String {
63    match e {
64        Estimator::Dima => format!(
65            "the rarefaction-regression correction of {}, computed as its exact expectation {}",
66            Cite::new(citations::DIMA_PAPER).at("Fig. 2").narrative(),
67            cited(&["rao1945", "blackwell1947"])
68        ),
69        Estimator::ChaoWangJost => {
70            format!("the estimator of {}", Cite::new("chao2013").narrative())
71        }
72        Estimator::MillerMadow => {
73            format!("the Miller–Madow correction {}", cited(&["miller1955"]))
74        }
75        Estimator::Raw => "the plug-in (observed) estimator".to_owned(),
76    }
77}
78
79fn alphabet_text(a: Alphabet) -> &'static str {
80    match a {
81        Alphabet::Protein => "protein",
82        Alphabet::Dna => "DNA",
83        Alphabet::Rna => "RNA",
84    }
85}
86
87/// What eligibility (support above T) meant for a run: only the paper's estimator corrects
88/// eligible positions alone; the others estimate every position alike.
89fn eligible_for(e: Estimator) -> &'static str {
90    match e {
91        Estimator::Dima => "the corrected entropy and the summary statistics",
92        Estimator::ChaoWangJost | Estimator::MillerMadow | Estimator::Raw => {
93            "the summary statistics"
94        }
95    }
96}
97
98/// A methods paragraph describing the run.
99#[must_use]
100pub fn sentence(r: &Results) -> String {
101    let p = &r.run.parameters;
102    let mut s = format!(
103        "Sequence diversity was analysed with DiMA {} using dima {}. In the {} \
104         alignment of {} ({} columns), the overlapping {}-mers at each of the {} were counted; \
105         positions supported by more than {} were eligible for {}. Shannon entropy {} was \
106         estimated with {}, and sample coverage after {}. Variants were classified as Index, \
107         Major, Minor and Unique motifs {}.",
108        cited(&[citations::DIMA_PAPER]),
109        r.run.tool.version,
110        alphabet_text(p.alphabet.value),
111        plural(r.sequence_count, "sequence", "sequences"),
112        r.run.alignment_length,
113        r.kmer_length,
114        plural(r.position_count, "position", "positions"),
115        plural(r.support_threshold, "sequence", "sequences"),
116        eligible_for(p.estimator.value),
117        cited(&["shannon1948"]),
118        estimator_text(p.estimator.value),
119        Cite::new("chao2012").narrative(),
120        cited(&["hu2013"]),
121    );
122    let unknown = r.run.validation.unknown_total;
123    if unknown > 0 {
124        s.push_str(&format!(
125            " K-mers containing characters that are not symbols of the {} alphabet ({}) \
126             were excluded.",
127            alphabet_text(p.alphabet.value),
128            plural(unknown, "occurrence", "occurrences"),
129        ));
130    }
131    if let Some(fields) = &p.metadata_fields.value {
132        s.push_str(&format!(
133            " Variant counts were stratified by the header fields {}.",
134            fields.join(", ")
135        ));
136    }
137    s
138}
139
140/// One entry of a reference list.
141enum Entry<'a> {
142    /// This software, at the given version.
143    Software(&'a str),
144    /// A reference this version knows.
145    Known(&'static Citation),
146    /// A reference recorded by a run that this version does not know (for example from a newer
147    /// dima): rendered from the text stored in the results.
148    Recorded(&'a Reference),
149}
150
151impl Entry<'_> {
152    fn text(&self) -> String {
153        match self {
154            Self::Software(v) => citations::software_text(v),
155            Self::Known(c) => c.text(),
156            Self::Recorded(r) => r.citation.clone(),
157        }
158    }
159
160    fn bibtex(&self) -> String {
161        match self {
162            Self::Software(v) => citations::software_bibtex(v),
163            Self::Known(c) => c.bibtex(),
164            Self::Recorded(r) => {
165                let mut s = format!(
166                    "@misc{{{},\n  note      = {{{}}},\n",
167                    bibtex_key(&r.key),
168                    citations::bibtex_escape(&r.citation)
169                );
170                if let Some(d) = &r.doi {
171                    let _ = writeln!(s, "  doi       = {{{d}}},");
172                }
173                if let Some(u) = &r.url {
174                    let _ = writeln!(s, "  url       = {{{u}}},");
175                }
176                s.push('}');
177                s
178            }
179        }
180    }
181
182    fn ris(&self) -> String {
183        match self {
184            Self::Software(v) => citations::software_ris(v),
185            Self::Known(c) => c.ris(),
186            Self::Recorded(r) => {
187                let mut s = String::from("TY  - GEN\n");
188                let _ = writeln!(s, "N1  - {}", one_line(&r.citation));
189                if let Some(d) = &r.doi {
190                    let _ = writeln!(s, "DO  - {d}");
191                }
192                if let Some(u) = &r.url {
193                    let _ = writeln!(s, "UR  - {u}");
194                }
195                s.push_str("ER  - \n");
196                s
197            }
198        }
199    }
200}
201
202/// A BibTeX key made of the characters BibTeX accepts in keys.
203fn bibtex_key(key: &str) -> String {
204    let k: String = key
205        .chars()
206        .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | ':' | '.'))
207        .collect();
208    if k.is_empty() {
209        "reference".to_owned()
210    } else {
211        k
212    }
213}
214
215/// Line breaks replaced by spaces (RIS and YAML comments are line-based).
216fn one_line(s: &str) -> String {
217    s.split(['\r', '\n'])
218        .filter(|l| !l.is_empty())
219        .collect::<Vec<_>>()
220        .join(" ")
221}
222
223/// The references of a run, in the order recorded. The software is cited at the version that
224/// produced the results.
225/// The reference list, in order and without repeats: the analysis's references (or the paper
226/// and this software), then those of the conserved sequences not already listed.
227fn entries<'a>(c: Cited<'a>) -> Vec<Entry<'a>> {
228    let version = c.version();
229    let mut out: Vec<Entry<'a>> = Vec::new();
230    let mut seen: Vec<&'a str> = Vec::new();
231    let mut add = |key: &'a str, recorded: Option<&'a Reference>| {
232        if seen.contains(&key) {
233            return;
234        }
235        seen.push(key);
236        let entry = if key == SOFTWARE_REFERENCE_KEY {
237            Some(Entry::Software(version))
238        } else {
239            citations::by_key(key)
240                .map(Entry::Known)
241                .or(recorded.map(Entry::Recorded))
242        };
243        out.extend(entry);
244    };
245    match c.results {
246        Some(r) => r.run.references.iter().for_each(|x| add(&x.key, Some(x))),
247        None => {
248            add(citations::DIMA_PAPER, None);
249            add(SOFTWARE_REFERENCE_KEY, None);
250        }
251    }
252    if let Some(h) = c.hcs {
253        h.references.iter().for_each(|x| add(&x.key, Some(x)));
254    }
255    out
256}
257
258/// A methods sentence for conserved sequences.
259#[must_use]
260pub fn hcs_sentence(h: &HcsResults) -> String {
261    let p = &h.parameters;
262    let t = plural(h.source.support_threshold, "sequence", "sequences");
263    let mut s = format!(
264        "Historically conserved sequences were identified as runs of {}-mer positions whose \
265         Index k-mer had an incidence of at least {}% {}, joining k-mers that overlap or are \
266         adjacent and agree on their shared columns {}; each was given the exact 95% \
267         Clopper–Pearson lower bound of its conservation {}.",
268        h.source.kmer_length,
269        p.threshold_percent,
270        cited(&[citations::DIMA_PAPER]),
271        cited(&["raman2020"]),
272        cited(&["clopper1934"]),
273    );
274    match p.eligibility {
275        HcsEligibility::AllPositions => {
276            let _ = write!(
277                s,
278                " Regions that include positions supported by at most {t} were flagged."
279            );
280        }
281        HcsEligibility::SupportGtThreshold => {
282            let _ = write!(
283                s,
284                " Only positions supported by more than {t} were used; positions with less \
285                 support ended a region {}.",
286                cited(&["castresana2000"])
287            );
288        }
289    }
290    s
291}
292
293/// The methods text and its numbered references, as plain text: what `dima cite --from`
294/// prints and the desktop app's "Methods & references" export writes. `None` when nothing is
295/// cited (no results and no conserved sequences).
296#[must_use]
297pub fn methods_text(c: Cited<'_>) -> Option<String> {
298    let paragraph = match (c.results, c.hcs) {
299        (Some(r), Some(h)) => format!("{} {}", sentence(r), hcs_sentence(h)),
300        (Some(r), None) => sentence(r),
301        (None, Some(h)) => hcs_sentence(h),
302        (None, None) => return None,
303    };
304    Some(format!(
305        "Methods:\n\n{paragraph}\n\nReferences:\n\n{}\n",
306        references(c, CitationFormat::Text)
307    ))
308}
309
310/// The reference list of what is cited (DiMA itself when nothing is).
311#[must_use]
312pub fn references(c: Cited<'_>, format: CitationFormat) -> String {
313    let list = entries(c);
314    match format {
315        CitationFormat::Text => list
316            .iter()
317            .enumerate()
318            .map(|(i, e)| format!("{}. {}", i + 1, e.text()))
319            .collect::<Vec<_>>()
320            .join("\n"),
321        CitationFormat::Bibtex => list
322            .iter()
323            .map(Entry::bibtex)
324            .collect::<Vec<_>>()
325            .join("\n\n"),
326        CitationFormat::Ris => list.iter().map(Entry::ris).collect::<Vec<_>>().join("\n"),
327        CitationFormat::Cff => {
328            let version = c.version();
329            let extra: Vec<&Citation> = list
330                .iter()
331                .filter_map(|e| match e {
332                    Entry::Known(c) if c.key != citations::DIMA_PAPER => Some(*c),
333                    _ => None,
334                })
335                .collect();
336            let mut doc = citations::cff_document(version, &extra);
337            // CFF references need structured authors and titles, which a recorded reference
338            // does not have; they are kept as comments so nothing the run cited is lost.
339            let recorded: Vec<&Reference> = list
340                .iter()
341                .filter_map(|e| match e {
342                    Entry::Recorded(r) => Some(*r),
343                    _ => None,
344                })
345                .collect();
346            if !recorded.is_empty() {
347                doc.push_str("# Also cited by this run (unknown to this dima version):\n");
348                for r in recorded {
349                    let _ = writeln!(doc, "# - {}", one_line(&r.citation));
350                }
351            }
352            doc
353        }
354    }
355}
356
357#[cfg(test)]
358mod tests {
359    use super::*;
360
361    #[test]
362    fn dima_only() {
363        let t = references(Cited::default(), CitationFormat::Text);
364        assert!(t.starts_with("1. Tharanga S, Ünlü ES"));
365        assert!(t.contains("\n2. Tharanga S. dima: sequence diversity"));
366        assert!(
367            references(Cited::default(), CitationFormat::Bibtex).contains("@software{dima_rs_")
368        );
369        assert!(references(Cited::default(), CitationFormat::Ris).contains("TY  - COMP"));
370        // A user's CFF does not carry the repository file's "do not edit" comment.
371        assert!(
372            references(Cited::default(), CitationFormat::Cff).starts_with("cff-version: 1.2.0")
373        );
374    }
375
376    #[test]
377    fn a_run_is_cited_as_recorded() {
378        let mut r: Results = serde_json::from_slice(
379            &std::fs::read(concat!(
380                env!("CARGO_MANIFEST_DIR"),
381                "/../../tests/golden/tiny/results.json"
382            ))
383            .unwrap(),
384        )
385        .unwrap();
386        // Results written by another version cite that version.
387        r.run.tool.version = "0.9.1".to_owned();
388        r.run.references.push(Reference {
389            key: "future2030".to_owned(),
390            citation: "Doe J. A method from the future. J Future. 2030;1:1. doi:10.0/x".to_owned(),
391            doi: Some("10.0/x".to_owned()),
392            url: None,
393        });
394        let n = r.run.references.len();
395        let t = references(Cited::results(&r), CitationFormat::Text);
396        assert_eq!(t.lines().count(), n);
397        assert_eq!(t.matches("[software]").count(), 1);
398        assert!(t.contains(", version 0.9.1 [software]. "));
399        assert!(t.ends_with(&format!(
400            "{n}. Doe J. A method from the future. J Future. 2030;1:1. doi:10.0/x"
401        )));
402        let b = references(Cited::results(&r), CitationFormat::Bibtex);
403        assert_eq!(b.matches("\n@").count() + 1, n);
404        assert!(b.contains("@software{dima_rs_0_9_1,"));
405        assert!(b.ends_with(
406            "@misc{future2030,\n  note      = {Doe J. A method from the future. J Future. \
407             2030;1:1. doi:10.0/x},\n  doi       = {10.0/x},\n}"
408        ));
409        let ris = references(Cited::results(&r), CitationFormat::Ris);
410        assert_eq!(ris.matches("TY  - ").count(), n);
411        assert!(ris.contains("ET  - 0.9.1\n"));
412        assert!(ris.ends_with("TY  - GEN\nN1  - Doe J. A method from the future. J Future. 2030;1:1. doi:10.0/x\nDO  - 10.0/x\nER  - \n"));
413        let cff = references(Cited::results(&r), CitationFormat::Cff);
414        assert!(cff.contains("version: \"0.9.1\"\n"));
415        assert!(cff.ends_with(
416            "# Also cited by this run (unknown to this dima version):\n# - Doe J. A method from \
417             the future. J Future. 2030;1:1. doi:10.0/x\n"
418        ));
419    }
420
421    #[test]
422    fn the_paragraph_cites_with_the_registry_labels() {
423        let r: Results = serde_json::from_slice(
424            &std::fs::read(concat!(
425                env!("CARGO_MANIFEST_DIR"),
426                "/../../tests/golden/tiny/results.json"
427            ))
428            .unwrap(),
429        )
430        .unwrap();
431        let s = sentence(&r);
432        for cite in [
433            "DiMA (Tharanga et al. 2025)",
434            "Shannon entropy (Shannon 1948)",
435            "sample coverage after Chao & Jost (2012)",
436            "motifs (Hu et al. 2013).",
437        ] {
438            assert!(s.contains(cite), "{cite:?} not in {s:?}");
439        }
440        assert_eq!(
441            estimator_text(Estimator::Dima),
442            "the rarefaction-regression correction of Tharanga et al. (2025, Fig. 2), computed \
443             as its exact expectation (Rao 1945; Blackwell 1947)"
444        );
445        assert_eq!(
446            estimator_text(Estimator::ChaoWangJost),
447            "the estimator of Chao et al. (2013)"
448        );
449        assert_eq!(
450            estimator_text(Estimator::MillerMadow),
451            "the Miller–Madow correction (Miller 1955)"
452        );
453        assert!(s.contains("were eligible for the corrected entropy and the summary statistics"));
454        // Other estimators estimate every position alike: eligibility is only for summaries.
455        let mut raw = r.clone();
456        raw.run.parameters.estimator.value = Estimator::Raw;
457        raw.run.validation.unknown_total = 3;
458        let s = sentence(&raw);
459        assert!(
460            s.contains("were eligible for the summary statistics. "),
461            "{s}"
462        );
463        assert!(s.contains("the plug-in (observed) estimator"), "{s}");
464        assert!(
465            s.contains("not symbols of the protein alphabet (3 occurrences) were excluded."),
466            "{s}"
467        );
468    }
469
470    #[test]
471    fn conserved_sequences_add_their_sentence_and_references() {
472        let r: Results = serde_json::from_slice(
473            &std::fs::read(concat!(
474                env!("CARGO_MANIFEST_DIR"),
475                "/../../tests/golden/tiny/results.json"
476            ))
477            .unwrap(),
478        )
479        .unwrap();
480        let params = crate::hcs::HcsParams {
481            threshold: "75".parse().unwrap(),
482            eligible_only: true,
483        };
484        let h = crate::hcs::compute(&r, &params).unwrap();
485        let both = Cited {
486            results: Some(&r),
487            hcs: Some(&h),
488        };
489        let text = methods_text(both).unwrap();
490        assert!(
491            text.contains("an incidence of at least 75% (Tharanga et al. 2025)"),
492            "{text}"
493        );
494        assert!(text.contains("positions with less support ended a region (Castresana 2000)."));
495        // Every reference once, the run's first, then the conserved sequences' new ones.
496        let list = references(both, CitationFormat::Text);
497        let run_only = references(Cited::results(&r), CitationFormat::Text);
498        assert!(list.starts_with(&run_only), "{list}");
499        for key in ["raman2020", "clopper1934", "castresana2000"] {
500            let c = citations::by_key(key).unwrap();
501            assert_eq!(list.matches(&c.text()).count(), 1, "{key}");
502        }
503        assert_eq!(list.matches("Tharanga S, Ünlü ES").count(), 1);
504        // Conserved sequences alone: the paper and the software head the list.
505        let alone = Cited {
506            results: None,
507            hcs: Some(&h),
508        };
509        let list = references(alone, CitationFormat::Text);
510        assert!(list.starts_with("1. Tharanga S, Ünlü ES"), "{list}");
511        assert!(
512            list.contains("\n2. Tharanga S. dima: sequence diversity"),
513            "{list}"
514        );
515        assert!(
516            methods_text(alone)
517                .unwrap()
518                .starts_with("Methods:\n\nHistorically conserved")
519        );
520        assert_eq!(methods_text(Cited::default()), None);
521    }
522}