bagel 0.5.1.dev7__py3-none-any.whl

bagel/logger.py

@@ -0,0 +1,63 @@
+import logging
+import sys
+from enum import Enum
+from typing import NoReturn
+
+import typer
+from rich.logging import RichHandler
+
+LOG_FMT = "%(message)s"
+DATETIME_FMT = "[%Y-%m-%d %X]"
+
+# Check if code is currently running in a test environment
+IS_TESTING = "pytest" in sys.modules
+
+logger = logging.getLogger("bagel.logger")
+
+
+class VerbosityLevel(str, Enum):
+    """Enum for verbosity levels."""
+
+    ERROR = "0"
+    INFO = "1"
+    # NOTE: We currently do not have any debug logs, but can add them in the future
+    DEBUG = "2"
+
+
+verbosity_log_levels = {
+    VerbosityLevel.ERROR: logging.ERROR,
+    VerbosityLevel.INFO: logging.INFO,
+    VerbosityLevel.DEBUG: logging.DEBUG,
+}
+
+
+def configure_logger(verbosity: VerbosityLevel = VerbosityLevel.INFO) -> None:
+    """Configure a logger with the specified logging level."""
+    level = verbosity_log_levels[verbosity]
+
+    # Prevent duplicate handlers when updating the logger
+    if not logger.handlers:
+        handler = RichHandler(
+            omit_repeated_times=False, show_path=False, rich_tracebacks=True
+        )
+        formatter = logging.Formatter(fmt=LOG_FMT, datefmt=DATETIME_FMT)
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    logger.setLevel(level)
+    for handler in logger.handlers:
+        handler.setLevel(level)
+
+    # propagate should be False to avoid duplicate messages from root logger
+    # except when testing because otherwise Pytest does not capture the logs
+    if not IS_TESTING:
+        logger.propagate = False
+
+
+def log_error(
+    logger: logging.Logger,
+    message: str,
+) -> NoReturn:
+    """Log an exception with an informative error message, and exit the app."""
+    logger.error(message)
+    raise typer.Exit(code=1)

bagel/mappings.py

@@ -0,0 +1,102 @@
+import json
+from collections import namedtuple
+from pathlib import Path
+
+import httpx
+
+from .logger import log_error, logger
+from .utilities import file_utils
+
+Namespace = namedtuple("Namespace", ["pf", "url"])
+COGATLAS = Namespace("cogatlas", "https://www.cognitiveatlas.org/task/id/")
+NB = Namespace("nb", "http://neurobagel.org/vocab/")
+NCIT = Namespace("ncit", "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#")
+NIDM = Namespace("nidm", "http://purl.org/nidash/nidm#")
+SNOMED = Namespace("snomed", "http://purl.bioontology.org/ontology/SNOMEDCT/")
+NP = Namespace(
+    "np", "https://github.com/nipoppy/pipeline-catalog/tree/main/processing/"
+)
+
+# Store all supported and deprecated namespaces in a list for easy iteration & testing
+SUPPORTED_NAMESPACES = [NB, NCIT, NIDM, SNOMED, NP]
+SUPPORTED_NAMESPACE_PREFIXES = [ns.pf for ns in SUPPORTED_NAMESPACES]
+# Keep deprecated namespaces for informative user messages
+DEPRECATED_NAMESPACES = [COGATLAS]
+DEPRECATED_NAMESPACE_PREFIXES = [ns.pf for ns in DEPRECATED_NAMESPACES]
+
+BIDS = {
+    "anat": NIDM.pf + ":Anatomical",
+    "func": NIDM.pf + ":Functional",
+    "dwi": NIDM.pf + ":DiffusionWeighted",
+    "bval": NIDM.pf + ":b-value",
+    "bvec": NIDM.pf + ":b-vector",
+    "T1w": NIDM.pf + ":T1Weighted",
+    "T2w": NIDM.pf + ":T2Weighted",
+    "inplaneT2": NIDM.pf + ":T2Weighted",
+    "bold": NIDM.pf + ":FlowWeighted",
+    "dti": NIDM.pf + ":DiffusionTensor",
+    "asl": NIDM.pf + ":ArterialSpinLabeling",
+}
+NEUROBAGEL = {
+    "participant": NB.pf + ":ParticipantID",
+    "session": NB.pf + ":SessionID",
+    "sex": NB.pf + ":Sex",
+    "age": NB.pf + ":Age",
+    "diagnosis": NB.pf + ":Diagnosis",
+    "healthy_control": NCIT.pf + ":C94342",
+    "assessment_tool": NB.pf + ":Assessment",
+}
+
+# TODO: Use importlib.resources.files(bagel) to get the path to the pipeline-catalog instead?
+PROCESSING_PIPELINE_PATH = (
+    Path(__file__).parent / "pipeline-catalog/processing/processing.json"
+)
+PROCESSING_PIPELINE_URL = "https://raw.githubusercontent.com/nipoppy/pipeline-catalog/refs/heads/main/processing/processing.json"
+
+
+def get_pipeline_catalog(url: str, path: Path) -> list[dict]:
+    """
+    Load the pipeline catalog from the remote location or, if that fails,
+    from the local backup.
+    """
+    try:
+        response = httpx.get(url)
+        response.raise_for_status()
+        return response.json()
+    # The JSONDecodeError should catch the case where the file is empty
+    except (httpx.HTTPError, json.JSONDecodeError):
+        logger.warning(
+            f"Unable to download pipeline catalog from {url}. Will revert to loading backup from {path}."
+        )
+        try:
+            # load_json() will catch JSONDecodeError which should catch when the file is empty
+            return file_utils.load_json(path)
+        except FileNotFoundError as e:
+            log_error(
+                logger,
+                f"Unable to find a local pipeline-catalog backup. Have you correctly initialized the submodules? {e}",
+            )
+
+
+def parse_pipeline_catalog() -> tuple[dict, dict]:
+    """
+    Load the pipeline catalog and return a dictionary of pipeline names and their URIs in the Nipoppy namespace,
+    and a dictionary of pipeline names and their supported versions in Nipoppy.
+    """
+    pipeline_catalog_arr = get_pipeline_catalog(
+        url=PROCESSING_PIPELINE_URL,
+        path=PROCESSING_PIPELINE_PATH,
+    )
+
+    version_dict = {}
+    uri_dict = {}
+    for pipeline in pipeline_catalog_arr:
+        version_dict[pipeline["name"]] = pipeline["versions"]
+        uri_dict[pipeline["name"]] = f"{NP.pf}:{pipeline['name']}"
+
+    return uri_dict, version_dict
+
+
+# TODO: consider refactoring this into a Mappings class that also
+# handles lazy loading of the remote content, i.e. only when accessed
+KNOWN_PIPELINE_URIS, KNOWN_PIPELINE_VERSIONS = parse_pipeline_catalog()

bagel/models.py

@@ -0,0 +1,97 @@
+import uuid
+from typing import List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+
+from bagel.mappings import NB
+
+UUID_PATTERN = r"[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$"
+BAGEL_UUID_PATTERN = rf"^{NB.pf}:{UUID_PATTERN}"
+
+
+class Bagel(BaseModel):
+    """identifier has to be a valid UUID prepended by the Neurobagel namespace
+    by default, a random (uuid4) string UUID will be created"""
+
+    identifier: str = Field(
+        pattern=BAGEL_UUID_PATTERN,
+        default_factory=lambda: NB.pf + ":" + str(uuid.uuid4()),
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ControlledTerm(BaseModel):
+    identifier: Union[str, HttpUrl]
+    schemaKey: str
+
+
+class Sex(ControlledTerm):
+    schemaKey: Literal["Sex"] = "Sex"
+
+
+class Diagnosis(ControlledTerm):
+    schemaKey: Literal["Diagnosis"] = "Diagnosis"
+
+
+class SubjectGroup(ControlledTerm):
+    schemaKey: Literal["SubjectGroup"] = "SubjectGroup"
+
+
+class Assessment(ControlledTerm):
+    schemaKey: Literal["Assessment"] = "Assessment"
+
+
+class Image(ControlledTerm):
+    schemaKey: Literal["Image"] = "Image"
+
+
+class Acquisition(Bagel):
+    hasContrastType: Image
+    schemaKey: Literal["Acquisition"] = "Acquisition"
+
+
+class Pipeline(ControlledTerm):
+    schemaKey: Literal["Pipeline"] = "Pipeline"
+
+
+class CompletedPipeline(Bagel):
+    hasPipelineVersion: str
+    hasPipelineName: Pipeline
+    schemaKey: Literal["CompletedPipeline"] = "CompletedPipeline"
+
+
+class Session(Bagel):
+    hasLabel: str
+
+
+class PhenotypicSession(Session):
+    hasAge: Optional[float] = None
+    hasSex: Optional[Sex] = None
+    isSubjectGroup: Optional[SubjectGroup] = None
+    hasDiagnosis: Optional[List[Diagnosis]] = None
+    hasAssessment: Optional[List[Assessment]] = None
+    schemaKey: Literal["PhenotypicSession"] = "PhenotypicSession"
+
+
+class ImagingSession(Session):
+    # NOTE: Do imaging session have to have at least one acquisition OR at least one completed pipeline to be valid?
+    hasFilePath: Optional[str] = None
+    hasAcquisition: Optional[List[Acquisition]] = None
+    hasCompletedPipeline: Optional[List[CompletedPipeline]] = None
+    schemaKey: Literal["ImagingSession"] = "ImagingSession"
+
+
+class Subject(Bagel):
+    hasLabel: str
+    hasSession: List[Union[PhenotypicSession, ImagingSession]]
+    schemaKey: Literal["Subject"] = "Subject"
+
+
+class Dataset(Bagel):
+    hasLabel: str
+    # NOTE: Since Pydantic v2, URL types no longer inherit from `str`
+    # (see https://docs.pydantic.dev/latest/migration/#url-and-dsn-types-in-pydanticnetworks-no-longer-inherit-from-str)
+    hasPortalURI: Optional[Union[str, HttpUrl]] = None
+    hasSamples: List[Subject]
+    schemaKey: Literal["Dataset"] = "Dataset"

bagel/pipeline-catalog/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/pipeline-catalog

bagel/pipeline-catalog/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: check-added-large-files
+    -   id: check-case-conflict
+    -   id: check-json
+    -   id: check-merge-conflict
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: mixed-line-ending
+    -   id: pretty-format-json
+        args: [--autofix, --indent, "4"]
+    -   id: trailing-whitespace

bagel/pipeline-catalog/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 nipoppy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bagel/pipeline-catalog/README.md

@@ -0,0 +1,2 @@
+# pipeline-catalog
+An index of processing pipelines and versions that are recognized by/are ready to use out-of-the-box with [Nipoppy](https://github.com/nipoppy/nipoppy).

bagel/pipeline-catalog/conversion/conversion.json

@@ -0,0 +1,20 @@
+[
+    {
+        "name": "bidscoin",
+        "versions": [
+            "4.3.2"
+        ]
+    },
+    {
+        "name": "dcm2bids",
+        "versions": [
+            "3.1.0"
+        ]
+    },
+    {
+        "name": "heudiconv",
+        "versions": [
+            "0.12.2"
+        ]
+    }
+]

bagel/pipeline-catalog/processing/processing.json

@@ -0,0 +1,36 @@
+[
+    {
+        "name": "fmriprep",
+        "versions": [
+            "20.2.0",
+            "20.2.7",
+            "23.1.3",
+            "24.1.1"
+        ]
+    },
+    {
+        "name": "freesurfer",
+        "versions": [
+            "6.0.1",
+            "7.3.2"
+        ]
+    },
+    {
+        "name": "mriqc",
+        "versions": [
+            "23.1.0"
+        ]
+    },
+    {
+        "name": "qsiprep",
+        "versions": [
+            "0.23.0"
+        ]
+    },
+    {
+        "name": "tractoflow",
+        "versions": [
+            "2.4.2"
+        ]
+    }
+]

bagel/utilities/bids_utils.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+from typing import Optional
+
+from bids import BIDSLayout
+from typer import BadParameter
+
+from bagel import mappings, models
+
+
+def check_absolute_bids_path(bids_path: Path) -> Path:
+    """
+    Raise an error if the input BIDS path does not look like an absolute path.
+    This is a workaround for --source-bids-dir not requiring the path to exist (and thus not being able to resolve the path automatically),
+    since it refers to a path on a host machine which may not be mounted as-is when the CLI is running in a container.
+    """
+    if not bids_path.is_absolute():
+        raise BadParameter("BIDS directory path must be an absolute path.")
+    return bids_path
+
+
+def map_term_to_namespace(term: str, namespace: dict) -> str:
+    """Returns the mapped namespace term if it exists, or False otherwise."""
+    return namespace.get(term, False)
+
+
+def get_bids_subjects_simple(bids_dir: Path) -> list:
+    """Returns list of subject IDs (in format of sub-<SUBJECT>) for a BIDS directory inferred from the names of non-empty subdirectories."""
+    bids_subject_list = []
+    for path in bids_dir.iterdir():
+        if (
+            path.name.startswith("sub-")
+            and path.is_dir()
+            and any(path.iterdir())
+        ):
+            bids_subject_list.append(path.name)
+    return bids_subject_list
+
+
+def create_acquisitions(
+    layout: BIDSLayout,
+    bids_sub_id: str,
+    session: Optional[str],
+) -> list:
+    """Parses BIDS image files for a specified session/subject to create a list of Acquisition objects."""
+    image_list = []
+    for bids_file in layout.get(
+        subject=bids_sub_id,
+        session=session,
+        extension=[".nii", ".nii.gz"],
+    ):
+        # If the suffix of a BIDS file is not recognized, then ignore
+        mapped_term = map_term_to_namespace(
+            bids_file.get_entities().get("suffix"),
+            namespace=mappings.BIDS,
+        )
+        if mapped_term:
+            image_list.append(
+                models.Acquisition(
+                    hasContrastType=models.Image(identifier=mapped_term)
+                )
+            )
+
+    return image_list
+
+
+def get_session_path(
+    source_bids_dir: Path,
+    bids_sub_id: str,
+    session: Optional[str],
+) -> str:
+    """Construct the session directory from the source BIDS directory path if session layer exists, otherwise returns subject directory."""
+    subject_path = source_bids_dir / f"sub-{bids_sub_id}"
+    session_path = subject_path / f"ses-{session}" if session else subject_path
+    return session_path.as_posix()

bagel/utilities/derivative_utils.py

@@ -0,0 +1,138 @@
+from typing import Iterable
+
+import pandas as pd
+
+from bagel import mappings, models
+from bagel.logger import log_error, logger
+
+# Shorthands for expected column names in a Nipoppy processing status file
+# TODO: While there are multiple session ID columns in a Nipoppy processing status file,
+# we only only look at `bids_session_id` right now. We should revisit this after the schema is finalized,
+# to see if any other logic is needed to avoid issues with session ID discrepancies across columns.
+PROC_STATUS_COLS = {
+    "participant": "bids_participant_id",
+    "session": "bids_session_id",
+    "pipeline_name": "pipeline_name",
+    "pipeline_version": "pipeline_version",
+    "status": "status",
+}
+
+
+def get_recognized_pipelines(pipelines: Iterable[str]) -> list:
+    """
+    Check that all pipelines in the processing status file are supported by Nipoppy.
+    Log an error if all pipelines are unrecognized, otherwise warn about unrecognized pipelines.
+    """
+    recognized_pipelines = list(
+        set(pipelines).intersection(mappings.KNOWN_PIPELINE_URIS)
+    )
+    unrecognized_pipelines = list(
+        set(pipelines).difference(mappings.KNOWN_PIPELINE_URIS)
+    )
+
+    unrecognized_pipelines_details = (
+        f"Unrecognized processing pipelines: {unrecognized_pipelines}. "
+        f"Supported pipelines are found in the Nipoppy pipeline catalog (https://github.com/nipoppy/pipeline-catalog): "
+        f"{list(mappings.KNOWN_PIPELINE_URIS.keys())}"
+    )
+    if not recognized_pipelines:
+        log_error(
+            logger,
+            f"The processing status file contains no recognized pipelines in the column: '{PROC_STATUS_COLS['pipeline_name']}'.\n"
+            f"{unrecognized_pipelines_details}",
+        )
+    if unrecognized_pipelines:
+        logger.warning(
+            f"The processing status file contains unrecognized pipelines in the column: '{PROC_STATUS_COLS['pipeline_name']}' - "
+            "these will be ignored. "
+            f"{unrecognized_pipelines_details}"
+        )
+    return recognized_pipelines
+
+
+def validate_pipeline_versions(
+    pipeline: str, versions: Iterable[str]
+) -> tuple[list, list]:
+    """
+    For a given pipeline, return the recognized and unrecognized pipeline versions in the processing status file
+    based on the Nipoppy pipeline catalog, and return both as lists.
+    """
+    recognized_versions = list(
+        set(versions).intersection(mappings.KNOWN_PIPELINE_VERSIONS[pipeline])
+    )
+    unrecognized_versions = list(
+        set(versions).difference(mappings.KNOWN_PIPELINE_VERSIONS[pipeline])
+    )
+
+    return recognized_versions, unrecognized_versions
+
+
+def check_at_least_one_pipeline_version_is_recognized(status_df: pd.DataFrame):
+    """
+    Check that at least one pipeline name and version combination found in the processing status file is supported by Nipoppy.
+    """
+    recognized_pipelines = get_recognized_pipelines(
+        status_df[PROC_STATUS_COLS["pipeline_name"]].unique()
+    )
+
+    any_recognized_versions = False
+    unrecognized_pipeline_versions = {}
+    for pipeline in recognized_pipelines:
+        versions = status_df[
+            status_df[PROC_STATUS_COLS["pipeline_name"]] == pipeline
+        ][PROC_STATUS_COLS["pipeline_version"]].unique()
+
+        recognized_versions, unrecognized_versions = (
+            validate_pipeline_versions(pipeline, versions)
+        )
+        if recognized_versions:
+            any_recognized_versions = True
+        if unrecognized_versions:
+            unrecognized_pipeline_versions[pipeline] = unrecognized_versions
+
+    unrecognized_versions_details = (
+        f"Unrecognized processing pipeline versions: {unrecognized_pipeline_versions}. "
+        "Supported pipeline versions are found in the Nipoppy pipeline catalog (https://github.com/nipoppy/pipeline-catalog)."
+    )
+    if not any_recognized_versions:
+        log_error(
+            logger,
+            f"The processing status file contains no recognized versions of any pipelines in the column '{PROC_STATUS_COLS['pipeline_version']}'.\n"
+            f"{unrecognized_versions_details}",
+        )
+    if unrecognized_pipeline_versions:
+        logger.warning(
+            f"The processing status file contains unrecognized versions of pipelines in the column '{PROC_STATUS_COLS['pipeline_version']}' - "
+            "these will be ignored. "
+            f"{unrecognized_versions_details}"
+        )
+
+
+def create_completed_pipelines(session_proc_df: pd.DataFrame) -> list:
+    """
+    Create a list of CompletedPipeline objects for a single subject-session based on the completion status
+    info of pipelines for that session from the processing status dataframe.
+    """
+    completed_pipelines = []
+    for (pipeline, version), session_pipe_df in session_proc_df.groupby(
+        [
+            PROC_STATUS_COLS["pipeline_name"],
+            PROC_STATUS_COLS["pipeline_version"],
+        ]
+    ):
+        if (
+            pipeline in mappings.KNOWN_PIPELINE_URIS
+            and version in mappings.KNOWN_PIPELINE_VERSIONS[pipeline]
+        ) and (
+            session_pipe_df[PROC_STATUS_COLS["status"]].str.lower()
+            == "success"
+        ).all():
+            completed_pipeline = models.CompletedPipeline(
+                hasPipelineName=models.Pipeline(
+                    identifier=mappings.KNOWN_PIPELINE_URIS[pipeline]
+                ),
+                hasPipelineVersion=version,
+            )
+            completed_pipelines.append(completed_pipeline)
+
+    return completed_pipelines

bagel/utilities/file_utils.py

@@ -0,0 +1,96 @@
+import json
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import typer
+
+from ..logger import log_error, logger
+
+
+def file_encoding_error_message(input_p: Path) -> str:
+    """Return a message for when a file cannot be read due to encoding issues."""
+    return (
+        f"Failed to decode the input file {input_p}. "
+        "Please ensure that both your phenotypic .tsv file and .json data dictionary have UTF-8 encoding.\n"
+        "Tip: Need help converting your file? Try a tool like iconv (http://linux.die.net/man/1/iconv) or https://www.freeformatter.com/convert-file-encoding.html."
+    )
+
+
+def load_tabular(
+    input_p: Path, input_type: str = "phenotypic"
+) -> pd.DataFrame:
+    """Load a .tsv pheno file and do some basic validation of the file type."""
+    if input_p.suffix == ".tsv":
+        try:
+            tabular_df = pd.read_csv(
+                input_p,
+                sep="\t",
+                keep_default_na=False,
+                dtype=str,
+                encoding="utf-8",
+            )
+        except UnicodeDecodeError:
+            log_error(
+                logger,
+                file_encoding_error_message(input_p),
+            )
+
+        if tabular_df.shape[1] > 1:
+            return tabular_df
+
+        # If we have only one column, but splitting by ',' gives us several elements
+        # then there is a good chance the user accidentally renamed a .csv into .tsv
+        # and we should give them some extra info with our error message to fix this.
+        note_misnamed_csv = (
+            f"Note that your {input_type} input file also looks like a .csv file "
+            "as it contains several ',' commas. It is possible that "
+            "you have accidentally renamed a .csv file as a .tsv."
+        )
+        log_error(
+            logger,
+            f"Your {input_type} input file {input_p} has only one column "
+            f"and is therefore not valid as a Neurobagel {input_type} file. "
+            f"Please provide a valid .tsv {input_type} file!"
+            f"\n{note_misnamed_csv if len(tabular_df.columns[0].split(',')) > 1 else ''}",
+        )
+
+    log_error(
+        logger,
+        f"Your ({input_p}) is not a .tsv file. "
+        f"Please provide a valid .tsv {input_type} file!",
+    )
+
+
+def load_json(input_p: Path) -> Any:
+    """Load a user-specified json type file."""
+    try:
+        with open(input_p, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except UnicodeDecodeError:
+        log_error(
+            logger,
+            file_encoding_error_message(input_p),
+        )
+    except json.JSONDecodeError:
+        log_error(
+            logger,
+            f"The provided file is not valid JSON: {input_p}. Please provide a valid JSON file.",
+        )
+
+
+def check_overwrite(output: Path, overwrite: bool):
+    """Exit program gracefully if an output file already exists but --overwrite has not been set."""
+    if output.exists() and not overwrite:
+        raise typer.Exit(
+            typer.style(
+                f"Output file {output} already exists. Use --overwrite or -f to overwrite.",
+                fg=typer.colors.RED,
+            )
+        )
+
+
+def save_jsonld(data: dict, filename: Path):
+    with open(filename, "w") as f:
+        f.write(json.dumps(data, indent=2))
+    logger.info(f"Saved output to:  {filename}")