"""Draft methods and results text for a systematic review report. Built only from data the tool already stores (protocol, search run, PRISMA counts), so every number and query in the text is the real one. The wording follows the PRISMA 2020 items for eligibility criteria, information sources, search strategy, selection process, automation tools and study selection results. Text in [square brackets] needs the authors' input. """ from __future__ import annotations from datetime import date, datetime from typing import Any, Sequence SOURCE_LABELS = { "pubmed": "PubMed", "europe_pmc": "Europe PMC", "openalex": "OpenAlex", "scopus": "Scopus", "wos": "Web of Science", "embase": "Embase", "epa_iris": "EPA IRIS", "echa": "ECHA", "efsa": "EFSA", "atsdr": "ATSDR", "ntp": "NTP", "iarc": "IARC", } HAND_SOURCES = {"embase", "epa_iris", "echa", "efsa", "atsdr", "ntp", "iarc"} def _v(value: Any) -> Any: return getattr(value, "value", value) def _label(source: Any) -> str: return SOURCE_LABELS.get(_v(source), str(_v(source))) def _date(value: Any) -> str: if value is None: return "[date]" if isinstance(value, str): try: value = date.fromisoformat(value[:10]) except ValueError: return value if isinstance(value, datetime): value = value.date() return f"{value.day} {value.strftime('%B %Y')}" def _n(value: int | None) -> str: return "not recorded" if value is None else f"{value:,}" def _join(items: Sequence[str]) -> str: items = [i for i in items if i] if len(items) <= 1: return "".join(items) return ", ".join(items[:-1]) + " and " + items[-1] def _questions(numbers: Sequence[int]) -> str: return ", ".join(f"Q{q}" for q in numbers) if numbers else "none selected" def build_methods_report( protocol: Any, run: Any, counts: Any, include_ranking: bool = False ) -> tuple[str, list[str]]: """Returns (report text in Markdown, list of things to check).""" warnings: list[str] = [] out: list[str] = [] dual = counts.reviewers_required >= 2 # --- Protocol and eligibility ------------------------------------------------ out.append("## Protocol and eligibility criteria") out.append( f"The review question was framed with population: {protocol.population}; " f"exposure or intervention: {protocol.intervention}; " f"comparator: {protocol.comparator or 'none specified'}; " f"outcome: {protocol.outcome}." ) out.append( "The protocol, including eligibility criteria, search strategy and sources, was fixed " f"before the search and locked on {_date(protocol.locked_at)} (version 1). " "[Add the registration number if the protocol was registered, for example in PROSPERO, " "or state that it was not registered.]" ) out.append("Inclusion criteria:\n" + "\n".join(f"- {c}" for c in protocol.inclusion_criteria)) out.append("Exclusion criteria:\n" + "\n".join(f"- {c}" for c in protocol.exclusion_criteria)) if protocol.amendments: lines = [] for a in protocol.amendments: fields = _join([str(c.field).replace("_", " ") for c in a.changes]) lines.append(f"- Version {a.version} ({_date(a.amended_at)}): {a.reason} (changed: {fields})") out.append( f"The protocol was amended {len(protocol.amendments)} time" f"{'' if len(protocol.amendments) == 1 else 's'} after locking " f"(current version {protocol.version}):\n" + "\n".join(lines) ) else: out.append("The protocol was not amended after locking.") # --- Information sources and search strategy ----------------------------------- out.append("## Information sources and search strategy") searched_on = _date(run.executed_at) out.append( f"The automated searches were run on {searched_on} (search run {run.run_number}, " f"protocol version {run.protocol_version if run.protocol_version else 1})." ) if protocol.intervention_terms or protocol.outcome_terms: out.append( "Search terms were grouped by concept. Exposure terms: " + (", ".join(f'"{t}"' for t in protocol.intervention_terms) or "(protocol text)") + ". Outcome terms: " + (", ".join(f'"{t}"' for t in protocol.outcome_terms) or "(protocol text)") + ". Terms within a concept were combined with OR and the concepts with AND, " "restricted to title and abstract." ) else: out.append( "No separate search terms were defined, so a free-text search built from the " "protocol's exposure and outcome text was used." ) searched_lines: list[str] = [] not_searched_lines: list[str] = [] for c in run.source_counts: label = _label(c.source) availability = _v(c.availability) is_hand = _v(c.source) in HAND_SOURCES query = f"`{c.query}`" if c.query else "(not recorded)" if availability == "unavailable_no_api": reason = c.note or "no search was recorded" not_searched_lines.append(f"- {label}: {reason}") if is_hand: warnings.append( f"{label} was selected but no search was recorded for it. Record the " "search on the Search tab, or remove it from the protocol through an amendment." ) else: warnings.append(f"{label} was selected but not searched: {reason}") elif is_hand and availability == "manual": searched_lines.append( f"- {label}: searched by hand on {_date(c.searched_on)}. Query: {query}. " f"Records identified: {_n(c.identified_count)} (counts only; the records were not " "imported for screening)." ) warnings.append( f"{label}: only the result count ({_n(c.identified_count)}) is recorded. Those " "records were not screened in the tool. Import the exported file, or report that " "they were handled outside the tool." ) elif is_hand: searched_lines.append( f"- {label}: searched by hand on {_date(c.searched_on)}. Query: {query}. " f"Records identified: {_n(c.identified_count)}; imported for screening: " f"{_n(c.retrieved_count)}." ) else: searched_lines.append( f"- {label}: searched on {searched_on}. Query: {query}. " f"Records identified: {_n(c.identified_count)}; downloaded for screening: " f"{_n(c.retrieved_count)}." ) if searched_lines: out.append("Sources searched and the exact query used for each:\n" + "\n".join(searched_lines)) if not_searched_lines: out.append("Sources named in the protocol but not searched:\n" + "\n".join(not_searched_lines)) out.append( "For the automated sources the tool downloads the highest-ranked records returned, up to " "a limit per source (about 200 records). [State any limits or filters applied, such as " "date, language or study type.]" ) previous = list(getattr(run, "previous_runs", []) or []) if previous: history = [ f"- Run {p.run_number} ({_date(p.executed_at)})" + (f": {p.rerun_reason}" if getattr(p, "rerun_reason", None) else "") for p in previous ] out.append( "Earlier search runs are kept in the search history:\n" + "\n".join(history) + f"\n- Run {run.run_number} ({searched_on})" + (f": {run.rerun_reason}" if run.rerun_reason else "") ) # --- Study selection ------------------------------------------------------------ out.append("## Study selection") out.append( "Records from all sources were combined and duplicates were removed automatically. " "Two records were treated as the same paper when their DOIs matched, or when their " "normalised titles matched (title of at least 25 characters and 4 words, publication " "years within one year, and no conflicting DOIs). The first copy was kept and every " "source that found the record was listed." ) if dual: selection = ( "Titles and abstracts, and then full texts, were screened in the tool by two " "independent reviewers who could not see each other's decisions. Disagreements were " "resolved by adjudication, and a written justification was recorded for each resolution." ) else: selection = "Titles and abstracts, and then full texts, were screened in the tool by one reviewer." out.append( selection + " Every decision, including the reviewer, the time and the reason for exclusion, is " "stored in an append-only audit trail." ) for stat in counts.agreement or []: stage = "title and abstract" if _v(stat.stage) == "title_abstract" else "full-text" kappa = ( f"Cohen's kappa {stat.kappa:.2f}" if stat.kappa is not None else "Cohen's kappa was undefined because every decision was identical" ) out.append( f"Agreement at {stage} screening between {stat.reviewer_a} and {stat.reviewer_b}: " f"{kappa}; {stat.percent_agreement:.1f}% agreement over {stat.records_compared} records." ) if include_ranking: out.append( "To prioritise screening, records were ordered by a text-relevance score (TF-IDF cosine " "similarity between each record's title and abstract and the protocol's search terms, " "PICO fields and inclusion criteria, with a bonus for records mentioning both exposure " "and outcome terms). Once at least three included and three excluded records had " "been screened, the ordering was updated with Rocchio relevance feedback from the " "reviewers' decisions. The ranking only set the order of screening: no record was " "excluded automatically, and every record received a decision from a human reviewer." ) # --- Risk of bias -------------------------------------------------------------- out.append("## Risk of bias") rob = ( "Risk of bias was assessed for each included study and outcome with the OHAT risk-of-bias " "tool. The key questions that determine a study's tier were " f"{_questions(protocol.rob_key_questions_observational)} for observational studies and " f"{_questions(protocol.rob_key_questions_experimental)} for animal studies and human trials." ) if dual: rob += " Two reviewers rated each study, and disagreements were resolved by adjudication." out.append(rob) if protocol.rob_criteria: out.append("Review-specific risk-of-bias criteria:\n" + protocol.rob_criteria) # --- Results ------------------------------------------------------------------- out.append("## Results of the search and selection") per_source = _join( [ f"{_label(c.source)} {_n(c.identified_count)}" for c in run.source_counts if _v(c.availability) != "unavailable_no_api" ] ) text = f"The searches identified {_n(counts.identified)} records ({per_source})." if counts.retrieved is not None: text += f" {_n(counts.retrieved)} records were downloaded or imported for screening." if (counts.not_retrieved or 0) > 0: text += ( f" {_n(counts.not_retrieved)} identified records were not downloaded because of the " "per-source limit (or because they were searched by hand without import) and were " "not screened." ) warnings.append( f"{_n(counts.not_retrieved)} identified records were not downloaded or screened. " "PRISMA 2020 expects every identified record to be screened. Narrow the search " "terms, or report this as a limitation." ) text += f" After removing {_n(counts.duplicates_removed)} duplicates, " else: text += " After removing duplicates, " warnings.append( "This search was saved before retrieval counts were recorded, so the duplicate count " "is unknown. Re-run the search to record it." ) text += ( f"{_n(counts.after_dedup)} records remained and {_n(counts.screened)} were screened by " f"title and abstract; {_n(counts.excluded_title_abstract)} were excluded." ) out.append(text) full = ( f"{_n(counts.sought_for_retrieval)} reports were sought for full-text assessment and " f"{_n(counts.excluded_full_text)} were excluded" ) reasons = [f"{r.reason} (n = {r.count})" for r in counts.excluded_full_text_reasons or []] full += f" ({'; '.join(reasons)})." if reasons else "." full += f" {_n(counts.included)} studies were included in the review." out.append(full) # --- Checks -------------------------------------------------------------------- if counts.awaiting_screening > 0 or counts.awaiting_full_text > 0: warnings.insert( 0, f"Screening is not finished ({counts.awaiting_screening} records without a final " f"title/abstract decision, {counts.awaiting_full_text} awaiting a full-text decision). " "The numbers in the results section will change.", ) if dual and (counts.conflicts_title_abstract or counts.conflicts_full_text): warnings.append( f"There are unresolved reviewer conflicts ({counts.conflicts_title_abstract} at " f"title/abstract, {counts.conflicts_full_text} at full text)." ) warnings.append("Replace the text in [square brackets] before you use the report.") return "\n\n".join(out) + "\n", warnings