1use 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
16pub enum CitationFormat {
17 Text,
19 Bibtex,
21 Ris,
23 Cff,
25}
26
27#[derive(Clone, Copy, Debug, Default)]
30pub struct Cited<'a> {
31 pub results: Option<&'a Results>,
33 pub hcs: Option<&'a HcsResults>,
35}
36
37impl<'a> Cited<'a> {
38 #[must_use]
40 pub const fn results(results: &'a Results) -> Self {
41 Self {
42 results: Some(results),
43 hcs: None,
44 }
45 }
46
47 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
56fn 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
87fn 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#[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
140enum Entry<'a> {
142 Software(&'a str),
144 Known(&'static Citation),
146 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
202fn 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
215fn one_line(s: &str) -> String {
217 s.split(['\r', '\n'])
218 .filter(|l| !l.is_empty())
219 .collect::<Vec<_>>()
220 .join(" ")
221}
222
223fn 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#[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#[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#[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 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 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 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 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, ¶ms).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 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 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}