Download backend/app/methods_report.py from Smart-Slate/Systematic-tool-review: direct link, hf CLI and curl.
- Browser
- Download file 14.2 kB
-
https://huggingface.co/spaces/Smart-Slate/Systematic-tool-review/resolve/main/backend/app/methods_report.py
- Command line
-
hf download hf://spaces/Smart-Slate/Systematic-tool-review/backend/app/methods_report.py
-
curl -L -o methods_report.py https://huggingface.co/spaces/Smart-Slate/Systematic-tool-review/resolve/main/backend/app/methods_report.py
14.2 kB
| """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 | |