fw-bids-utils 0.1.0__py3-none-any.whl

fw_bids_utils/classifications.py

@@ -0,0 +1,148 @@
+"""Used by fw_bids_io.uploader and fw_bids_curate.match"""
+
+from .dependencies import Any, Dict, Optional, log
+
+classifications = {
+    "anat": {
+        "T1w": {"Measurement": "T1", "Intent": "Structural"},
+        "T2w": {"Measurement": "T2", "Intent": "Structural"},
+        "T1rho": {"Custom": "T1rho"},
+        "T1map": {
+            "Measurement": "T1",
+            "Intent": "Structural",
+            "Features": "Quantitative",
+        },
+        "T2map": {
+            "Measurement": "T2",
+            "Intent": "Structural",
+            "Features": "Quantitative",
+        },
+        "T2star": {"Measurement": "T2*", "Intent": "Structural"},
+        "FLAIR": {"Custom": "FLAIR"},
+        "FLASH": {"Custom": "FLASH"},
+        "PD": {"Measurement": "PD", "Intent": "Structural"},
+        "PDmap": {"Custom": "PD-Map"},
+        "PDT2": {"Measurement": ["PD", "T2"], "Intent": "Structural"},
+        "inplaneT1": {
+            "Measurement": "T1",
+            "Intent": "Structural",
+            "Features": "In-Plane",
+        },
+        "inplaneT2": {
+            "Measurement": "T2",
+            "Intent": "Structural",
+            "Features": "In-Plane",
+        },
+        "angio": {"Custom": "Angio"},
+        "defacemask": {"Custom": "Defacemask"},
+        "SWImagandphase": {"Custom": "SWI"},
+    },
+    "func": {
+        "bold": {"Intent": "Functional"},
+        "events": {"Intent": "Functional"},
+        "sbref": {"Intent": "Functional"},
+        "stim": {"Intent": "Functional", "Custom": "Stim"},
+        "physio": {"Intent": "Functional", "Custom": "Physio"},
+    },
+    "beh": {
+        "events": {"Custom": "Behavioral"},
+        "stim": {"Custom": "Stim"},
+        "physio": {"Custom": "Physio"},
+    },
+    "dwi": {
+        "dwi": {"Measurement": "Diffusion", "Intent": "Structural"},
+        "sbref": {"Measurement": "Diffusion", "Intent": "Structural"},
+    },
+    "fmap": {
+        "phasediff": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "magnitude1": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "magnitude2": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "phase1": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "phase2": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "magnitude": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "fieldmap": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "epi": {"Measurement": "B0", "Intent": "Fieldmap"},
+        "m0scan": {"Measurement": "B0", "Intent": "Fieldmap"},
+    },
+    "perf": {
+        "asl": {"Measurement": "Perfusion"},
+        "m0scan": {"Measurement": "Perfusion", "Intent": "Fieldmap"},
+        "stim": {"Measurement": "Perfusion", "Custom": "Stim"},
+        "physio": {"Measurement": "Perfusion", "Custom": "Physio"},
+        "aslcontext": {"Measurement": "Perfusion", "Custom": "Context"},
+        "asllabeling": {"Measurement": "Perfusion", "Intent": "Screenshot"},
+    },
+}
+
+
+def determine_modality(parent_dir_name: str) -> Optional[str]:
+    """Determine which modality a file belongs to based on the parent directory's name.
+
+    This function scans through the BIDS classifications dictionary to find matching keys
+    in the provided directory or filename, returning the appropriate BIDS modality.
+
+    Args:
+        parent_dir_name: Folder or filename containing matching information for BIDS classification.
+            The function performs a case-insensitive substring match against known BIDS entities.
+
+    Returns:
+        str: The BIDS format modality folder name (e.g., 'anat', 'func', 'dwi', 'fmap', 'perf').
+        None: If no match is found.
+
+    Examples:
+        >>> determine_modality("sub-01_T1w")
+        'anat'
+        >>> determine_modality("PCASL")
+        'perf'
+        >>> determine_modality("fieldmap_magnitude1")
+        'fmap'
+    """
+    for bids_folder, classificaton_dict in classifications.items():
+        for k in classificaton_dict.keys():
+            if k.lower() in parent_dir_name.lower():
+                return bids_folder
+    log.error(
+        "Could not match modality in classification table with %s" % parent_dir_name
+    )
+    return None
+
+
+def search_classifications(
+    bids_folder: str, search_name: str
+) -> Optional[Dict[str, Any]]:
+    """Robust search on a filename to determine classifications.
+
+    This function performs a case-insensitive search for BIDS entities within a filename
+    and returns the associated classification information for the best matching entity.
+    In case of multiple matches, it selects the longest matching entity name.
+
+    Args:
+        bids_folder: Modality folder, e.g., 'anat', 'func', 'dwi', 'fmap', 'perf'.
+            Must be a valid key in the classifications dictionary.
+        search_name: Filename containing matching information for BIDS classification.
+            The function performs a case-insensitive substring match against known BIDS entities.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing classification entries for the found entity.
+            Typically includes keys like 'Measurement', 'Intent', 'Features', or 'Custom'.
+        None: If no match is found.
+
+    Examples:
+        >>> search_classifications("anat", "T1w")
+        {'Measurement': 'T1', 'Intent': 'Structural'}
+        >>> search_classifications("func", "bold")
+        {'Intent': 'Functional'}
+    """
+    matches = []
+    for k in classifications[bids_folder].keys():
+        if k.lower() in search_name.lower():
+            matches.append(k)
+    if matches:
+        # In cases of multiple matches, choose the longest match
+        return classifications[bids_folder][max(matches, key=len)]
+    else:
+        log.error(
+            "Did not find info in the classification table under %s for %s"
+            % (bids_folder, search_name)
+        )
+        return None

fw_bids_utils/dependencies.py

@@ -0,0 +1,18 @@
+"""Common dependencies for fw_bids_utils."""
+
+# Standard library imports
+import collections  # noqa: F401
+import logging
+import re  # noqa: F401
+import subprocess  # noqa: F401
+import sys  # noqa: F401
+from typing import Any, Dict, List, Match, Optional, Pattern, Tuple, Union  # noqa: F401
+
+# Constants
+BIDS_VALIDATOR_PATHS = [
+    "/usr/local/bin/bids-validator",
+    "/usr/bin/bids-validator",
+    "/opt/conda/bin/bids-validator",
+]
+# Configure logging
+log = logging.getLogger(__name__)

fw_bids_utils/errors.py

@@ -0,0 +1,66 @@
+"""Error handling for BIDS operations."""
+
+from .dependencies import Any, Dict, log
+
+
+class BIDSException(Exception):
+    """Base exception for BIDS operations."""
+
+    status_code = 1
+
+    def __init__(
+        self,
+        msg: str = None,
+        errors: Dict = None,
+        log_error: bool = False,
+        log_msg: str = None,
+    ):
+        # If log_msg is provided and msg is None, use log_msg as the message
+        self.message = (
+            msg
+            if msg is not None
+            else (log_msg or "There was an error with the BIDS operation")
+        )
+        self.errors = errors or {}
+        self.should_log = log_error or bool(log_msg)
+        self.log_msg = log_msg or self.message
+        super().__init__(self.message)
+
+    def __str__(self):
+        return self.message
+
+
+class BIDSImportError(BIDSException):
+    """Exception raised during BIDS import."""
+
+    status_code = 2
+
+    def __init__(
+        self,
+        msg: str = "There was an error with the BIDS import",
+        errors: Dict = None,
+        log_error: bool = False,
+        log_msg: str = None,
+    ):
+        super().__init__(msg=msg, errors=errors, log_error=log_error, log_msg=log_msg)
+
+
+class BIDSExportError(BIDSException):
+    """Exception raised during BIDS export."""
+
+    status_code = 3
+
+    def __init__(
+        self,
+        msg: str = "There was an error with the BIDS export",
+        errors: Dict = None,
+        log_error: bool = False,
+        log_msg: str = None,
+    ):
+        super().__init__(msg=msg, errors=errors, log_error=log_error, log_msg=log_msg)
+
+
+def warn_if_bids_invalid(file_info: Dict[str, Any], namespace: str = "BIDS") -> None:
+    """Warn if file doesn't have BIDS metadata."""
+    if not file_info.get("info", {}).get(namespace):
+        log.warning(f"File {file_info['name']} is not properly BIDS curated")

fw_bids_utils/helpers.py

@@ -0,0 +1,448 @@
+# Miscellaneous helper functions for Flywheel BIDS operations.
+from .dependencies import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Pattern,
+    Tuple,
+    Union,
+    collections,
+    log,
+    re,
+    sys,
+)
+
+
+def get_project_id_from_subject_id(fw: Any, subject_id: str) -> str:
+    """Get project ID associated with a subject ID.
+
+    This function retrieves the project ID associated with a given subject
+    by querying the Flywheel API.
+
+    Args:
+        fw: Flywheel client instance with appropriate authentication
+        subject_id: Subject ID to look up
+
+    Returns:
+        str: Project ID associated with the subject
+
+    Raises:
+        SystemExit: If subject cannot be found in Flywheel
+
+    Example:
+        >>> client = flywheel.Client()
+        >>> project_id = get_project_id_from_subject_id(client, '5e1c2a95d5e9520d30fa0939')
+    """
+    # Find project id from subject
+    subject = fw.get_subject(subject_id)
+    if not subject:
+        log.error("Could not load subject %s." % subject_id)
+        sys.exit(1)
+    return subject["project"]
+
+
+def get_project_id_from_session_id(fw: Any, session_id: str) -> str:
+    """Get project ID associated with a session ID.
+
+    This function retrieves the project ID associated with a given session
+    by querying the Flywheel API.
+
+    Args:
+        fw: Flywheel client instance with appropriate authentication
+        session_id: Session ID to look up
+
+    Returns:
+        str: Project ID associated with the session
+
+    Raises:
+        SystemExit: If session cannot be found in Flywheel
+
+    Example:
+        >>> client = flywheel.Client()
+        >>> project_id = get_project_id_from_session_id(client, '5e1c2a95d5e9520d30fa0940')
+    """
+    # Find project id from session
+    session = fw.get_session(session_id)
+    if not session:
+        log.error("Could not load session %s." % session_id)
+        sys.exit(1)
+    return session["project"]
+
+
+def get_extension(fname: str) -> Optional[str]:
+    """Get the extension from a filename, including compound extensions.
+
+    Args:
+        fname: The filename (or path) to extract the extension from
+
+    Returns:
+        The extension (e.g. ".txt", ".nii.gz"), or None if there isn't one
+
+    Examples:
+        >>> get_extension("sub-01_T1w.nii.gz")
+        '.nii.gz'
+        >>> get_extension("README")
+    """
+    ext = re.search(r"\.[a-zA-Z]*[\.]?[A-Za-z0-9]+$", fname)
+    if ext:
+        return ext.group()
+    return None
+
+
+def dict_lookup(obj: Union[Dict, List], value: str, default: Any = None) -> Any:
+    """Recursively looks up a value in a nested dictionary or list using a dot-separated string.
+
+    This function traverses a complex nested structure (dictionaries or lists) using
+    a dot-separated path string to locate a value. If the path doesn't exist, it returns
+    the specified default value.
+
+    Args:
+        obj: The dictionary or list to search
+        value: The dot-separated string representing the path to the value
+        default: The value to return if the path does not exist (defaults to None)
+
+    Returns:
+        The value found at the specified path, or the default value if the path does not exist
+
+    Examples:
+        >>> data = {"a": {"b": {"c": 42}}, "list": [1, 2, {"x": "found"}]}
+        >>> dict_lookup(data, "a.b.c")
+        42
+        >>> dict_lookup(data, "list.2.x")
+        'found'
+        >>> dict_lookup(data, "a.b.d", "not found")
+        'not found'
+    """
+    # For now, we don't support escaping of dots
+    parts = value.split(".")
+    curr = obj
+    for part in parts:
+        if isinstance(curr, (dict, collections.abc.Mapping)) and part in curr:
+            curr = curr[part]
+        elif isinstance(curr, list) and part.isdigit() and int(part) < len(curr):
+            curr = curr[int(part)]
+        else:
+            curr = default
+            break
+    return curr
+
+
+def dict_set(obj: Dict, key: str, value: Any) -> None:
+    """Set a value in a nested dictionary using a dot-separated key path.
+
+    This function traverses a dictionary using a dot-separated path string
+    and sets a value at the specified location. It can also handle numeric
+    indices for lists within the nested structure.
+
+    Args:
+        obj: Target dictionary to modify
+        key: Dot-separated path where the value should be set
+        value: Value to set at the specified path
+
+    Raises:
+        ValueError: If the path cannot be traversed (intermediate keys don't exist)
+
+    Examples:
+        >>> data = {"a": {"b": {}}, "list": [1, 2, {}]}
+        >>> dict_set(data, "a.b.c", 42)
+        >>> data
+        {"a": {"b": {"c": 42}}, "list": [1, 2, {}]}
+        >>> dict_set(data, "list.2.x", "new value")
+        >>> data
+        {"a": {"b": {"c": 42}}, "list": [1, 2, {"x": "new value"}]}
+    """
+    parts = key.split(".")
+    curr = obj
+    for part in parts[:-1]:
+        if isinstance(curr, (dict, collections.abc.Mapping)) and part in curr:
+            curr = curr[part]
+        elif isinstance(curr, list) and part.isdigit() and int(part) < len(curr):
+            curr = curr[int(part)]
+        else:
+            raise ValueError("Could not set value for key: " + key)
+    curr[parts[-1]] = value
+
+
+def dict_match(matcher: Dict[str, Any], matchee: Dict[str, Any]) -> bool:
+    """Returns True if each key-value pair in matcher is present in the matchee.
+
+    This function checks if all key-value pairs from the matcher dictionary
+    exist in the matchee dictionary. For list values, it checks if each item
+    in the matcher's list is present in the matchee's corresponding list.
+
+    Args:
+        matcher: Dictionary with keys and values to match
+        matchee: Dictionary to check against
+
+    Returns:
+        bool: True if matchee contains all key/value pairs from matcher, False otherwise
+
+    Examples:
+        >>> dict_match({"a": 1, "b": 2}, {"a": 1, "b": 2, "c": 3})
+        True
+        >>> dict_match({"a": 1, "b": 3}, {"a": 1, "b": 2})
+        False
+        >>> dict_match({"a": [1, 2]}, {"a": [1, 2, 3]})
+        True
+    """
+    for key, val in matcher.items():
+        if key not in matchee:
+            return False
+        elif not isinstance(matchee.get(key), list):
+            mval = [matchee.get(key)]
+        else:
+            mval = matchee.get(key)
+        if isinstance(val, list):
+            for item in val:
+                if item not in mval:
+                    return False
+        elif val not in mval:
+            return False
+    return True
+
+
+def _compile_template_regexes() -> Tuple[Pattern, Pattern]:
+    """Compile and return regex patterns used for template processing.
+
+    Returns:
+        Tuple containing two compiled regex patterns:
+        - tokens_pattern: For identifying tokens in the template
+        - values_pattern: For identifying placeholder values within tokens
+    """
+    tokens_pattern = re.compile(r"[^\[][A-Za-z0-9\.><}{-]+|\[[/A-Za-z0-9><}{_\.-]+\]")
+    values_pattern = re.compile(r"[{<][A-Za-z0-9\.-_]+[>}]|\[[A-Za-z0-9\.-_]+\]")
+    return tokens_pattern, values_pattern
+
+
+def _extract_value_from_context(path: str, context: Dict[str, Any]) -> Optional[Any]:
+    """Extract a value from the context using dot notation path.
+
+    Args:
+        path: Dot-separated path to the value in the context
+        context: Dictionary containing the hierarchical data
+
+    Returns:
+        The value found at the specified path, or None if not found
+    """
+    keys = path.split(".")
+    result = context
+    for key in keys:
+        if key in result:
+            result = result[key]
+        else:
+            return None
+    return result
+
+
+def _format_bids_value(value: Any) -> str:
+    """Format a value according to BIDS conventions.
+
+    Args:
+        value: The value to format
+
+    Returns:
+        Formatted string value
+    """
+    if not isinstance(value, str):
+        value = str(value)
+    # Check if value is already in BIDS format (sub-X, ses-X)
+    if re.match("(sub|ses)-[a-zA-Z0-9]+", value):
+        # Extract just the label part after the hyphen
+        label, value = value.split("-")
+    else:
+        # Remove underscores and dashes, keep only alphanumeric characters
+        value = "".join(
+            x for x in value.replace("_", " ").replace("-", " ") if x.isalnum()
+        )
+    return value
+
+
+def _replace_tokens_in_template(
+    template: str, token: str, replace_token: str, result: Any
+) -> str:
+    """Replace a token in the template with its value.
+        Args:
+            template: The template string being processed
+            token: The full token containing the placeholder
+            replace_token: The placeholder to replace (like <path> or {path})
+            result: The value to substitute
+
+    Returns
+            Updated template string with the replacement made
+    """
+    # Handle optional tokens (enclosed in square brackets)
+    is_optional = token.startswith("[") and token.endswith("]")
+    if is_optional and (result is None or replace_token in token and result is None):
+        # For optional tokens, remove them entirely if the value is None
+        return template.replace(token, "")
+
+    # If we have a result, format it and replace the token
+    if result:
+        if replace_token[0] == "<":
+            # Format according to BIDS conventions for <> tokens
+            result = _format_bids_value(result)
+        # Replace the placeholder with the string result
+        return template.replace(replace_token, str(result))
+    # No changes if we can't handle the token
+    return template
+
+
+def process_string_template(template: str, context: Dict[str, Any]) -> str:
+    """Process a string template by substituting values from a context dictionary.
+
+    This function finds placeholder tokens in the template string and replaces them
+    with values from the context object. It supports two types of placeholders:
+    - <path>: Values are converted to lowerCamelCase (removes underscores and dashes)
+    - {path}: Values are used as-is
+    The path uses dot notation to navigate the context dictionary for desired values.
+
+    Args:
+        template: Template string with replacement tokens (<path> or {path})
+        context: Dictionary containing values to substitute
+
+    Returns:
+        str: Processed template with values substituted
+
+    Examples:
+        >>> context = {"subject": {"code": "01"}, "file": {"info": {"BIDS": {"Modality": "T1w"}}}}
+        >>> process_string_template("sub-<subject.code>_{file.info.BIDS.Modality}.nii.gz", context)
+        'sub-01_T1w.nii.gz'
+
+    Note:
+        Optional tokens can be enclosed in square brackets and will be removed if
+        the corresponding value is not found in the context.
+    """
+    # Compile regex patterns for template processing
+    tokens_pattern, values_pattern = _compile_template_regexes()
+    # Process each token in the template
+    for token in tokens_pattern.findall(template):
+        if values_pattern.search(token):
+            replace_tokens = values_pattern.findall(token)
+            for replace_token in replace_tokens:
+                # Extract the path from the placeholder
+                path = replace_token[1:-1]
+                # Get the value from the context
+                result = _extract_value_from_context(path, context)
+                # Replace the token in the template
+                template = _replace_tokens_in_template(
+                    template, token, replace_token, result
+                )
+    # Remove any remaining square brackets from optional tokens
+    processed_template = re.sub(r"\[|\]", "", template)
+    return processed_template
+
+
+def get_pattern(format_params: Dict[str, Any]) -> Optional[Union[str, List[str]]]:
+    """Get pattern from format parameters.
+        This helper function extracts the $pattern value from formatting parameters.
+        Args:
+            format_params: Dictionary with formatting parameters that may contain a $pattern key
+
+    Returns
+            str or List[str]: The pattern value if found
+            None: If no pattern is found
+    """
+    return format_params.get("$pattern")
+
+
+def format_value(params: List[Dict[str, Any]], value: str) -> str:  # noqa: PLR0912
+    """Format a string value based on a list of transformation parameters.
+
+    This function applies a series of string transformations based on the provided
+    parameters. Supported transformations include:
+    - $replace: Replace pattern with replacement text
+    - $lower: Convert to lowercase
+    - $upper: Convert to uppercase
+    - $camelCase: Convert to camelCase
+
+    Args:
+        params: List of formatting parameter dictionaries
+        value: String value to format
+
+    Returns:
+        str: Formatted string after applying all transformations
+
+    Examples:
+        >>> format_value([{"$replace": {"$pattern": "ab", "$replacement": "c"}}], "dabf")
+        'dcf'
+        >>> format_value([{"$lower": True}], "TEXT")
+        'text'
+        >>> format_value([{"$camelCase": True}], "some_text-here")
+        'someTextHere'
+    """
+    for param in params:
+        if "$replace" in param:
+            value = re.sub(
+                get_pattern(param["$replace"]),
+                param["$replace"].get("$replacement"),
+                value,
+            )
+        elif "$lower" in param:
+            if isinstance(param["$lower"], dict) and get_pattern(param["$lower"]):
+                value = re.sub(
+                    get_pattern(param["$lower"]), lambda m: m.group(0).lower(), value
+                )
+            else:
+                value = value.lower()
+        elif "$upper" in param:
+            if isinstance(param["$upper"], dict) and get_pattern(param["$upper"]):
+                value = re.sub(
+                    get_pattern(param["$upper"]), lambda m: m.group(0).upper(), value
+                )
+            else:
+                value = value.upper()
+        elif "$camelCase" in param:
+            if isinstance(param["$camelCase"], dict) and get_pattern(
+                param["$camelCase"]
+            ):
+                patterns = get_pattern(param["$camelCase"])
+                if not isinstance(patterns, list):
+                    patterns = [patterns]
+                for pattern in patterns:
+                    value = value.replace(pattern, " ")
+                value = "".join(x for x in value.title() if x.isalnum())
+                value = value[0].lower() + value[1:]
+            else:
+                # Best to not process string with <...> with $camelCase : true
+                value = "".join(
+                    x
+                    for x in value.replace("_", " ").replace("-", " ").title()
+                    if x.isalnum()
+                )
+                value = value[0].lower() + value[1:]
+    return value
+
+
+def normalize_strings(obj: Any) -> Any:
+    """Recursively convert all string-like objects in a data structure to Python str type.
+
+    This function traverses through dictionaries, lists, and other iterables,
+    converting any string-like objects to the standard Python str type.
+
+    Args:
+        obj: The object to normalize, can be a string, dictionary, list, or other iterable
+
+    Returns:
+        The normalized object with all strings converted to Python str type
+
+    Examples:
+        >>> normalize_strings("text")
+        'text'
+        >>> normalize_strings({"key": b"value"})
+        {'key': 'value'}
+        >>> normalize_strings([1, "two", b"three"])
+        [1, 'two', 'three']
+    """
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8")
+    if isinstance(obj, str):
+        return str(obj)
+    elif isinstance(obj, dict):
+        return {normalize_strings(k): normalize_strings(v) for k, v in obj.items()}
+    elif isinstance(obj, collections.abc.Iterable) and not isinstance(
+        obj, (str, bytes)
+    ):
+        # Use type(obj) to preserve the original collection type (including custom classes)
+        return type(obj)(normalize_strings(item) for item in obj)
+    return obj

fw_bids_utils/validate.py

@@ -0,0 +1,89 @@
+"""Validation utilities for BIDS datasets."""
+
+from .dependencies import Any, Optional, log, subprocess
+from .errors import BIDSException
+
+
+def validate_bids(bids_dir: str) -> bool:
+    """Validate a BIDS dataset using the bids-validator.
+    This function runs the external bids-validator tool to check if a BIDS dataset
+    conforms to the Brain Imaging Data Structure specification. It captures and logs
+    any validation errors or warnings.
+
+    Args:
+        bids_dir: Path to BIDS dataset directory to validate
+
+    Returns:
+        bool: True if validation passed without errors (warnings are acceptable),
+              False if validation failed with errors
+
+    Raises:
+        BIDSException: If the bids-validator command fails to execute or
+                      if the bids-validator executable is not found
+
+    Note:
+        This function requires the bids-validator to be installed.
+        You can install it via npm: `npm install -g bids-validator`
+    """
+    try:
+        result = subprocess.run(
+            ["bids-validator", bids_dir], check=True, capture_output=True, text=True
+        )
+        # Check for validation errors in output
+        if "validator.error" in result.stdout:
+            log.error("BIDS validation failed with errors")
+            return False
+        # Warnings are ok, but we should log them
+        if "validator.warn" in result.stdout:
+            log.warning("BIDS validation produced warnings")
+        return True
+    except subprocess.CalledProcessError as e:
+        raise BIDSException("BIDS validation failed: %s" % str(e))
+    except FileNotFoundError:
+        raise BIDSException(
+            "bids-validator not found. Please install NodeJS and run: npm install -g bids-validator"
+        )
+
+
+def validate_project_label(
+    fw: Any, project_label: str, group_id: Optional[str] = None
+) -> str:
+    """Validate that a project label exists and is unique within Flywheel.
+    This function searches for projects with the given label and ensures there is exactly
+    one matching project. It can optionally filter by group to narrow the search scope.
+
+    Args:
+        fw: Flywheel client instance with appropriate authentication
+        project_label: Project label (name) to validate
+        group_id: Optional group ID to restrict the search to a specific group
+
+    Returns:
+        str: Project ID of the validated project
+
+    Raises:
+        ValueError: If no projects are found with the given label, or
+                   if multiple projects are found with the same label
+
+    Note:
+        When multiple projects with the same label exist, use the group_id
+        parameter to disambiguate which project is intended.
+    """
+    # Find project id
+    # exhaustive=True is needed because site-admin users won't
+    # find projects they have not been explicitly added to
+    if group_id:
+        projects = fw.projects.find(
+            f"group={group_id},label={project_label}", exhaustive=True
+        )
+    else:
+        projects = fw.projects.find(f"label={project_label}", exhaustive=True)
+    num_projects = len(projects)
+    if num_projects > 1:
+        raise ValueError(
+            "Found %d projects with label %s. Use the --group-id option to specify a group id"
+            % (num_projects, project_label)
+        )
+    elif num_projects < 1:
+        raise ValueError("Could not find project with label %s" % project_label)
+    project = projects[0]
+    return project.id

fw_bids_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: fw-bids-utils
+Version: 0.1.0
+Summary: Utilities for the Flywheel BIDS suite.
+Keywords: Flywheel,flywheel,BIDS,SDK
+Author: Flywheel
+Author-email: Flywheel <support@flywheel.io>
+License-Expression: MIT
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: fw-gear>=0.3,<0.4
+Requires-Python: >=3.11, <4
+Project-URL: Repository, https://gitlab.com/flywheel-io/scientific-solutions/lib/bids-suite/fw-bids-utils
+Description-Content-Type: text/markdown
+
+# fw-bids-utils
+
+[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Overview
+
+fw-bids-utils is a Python package that holds helper methods used across the
+fw-bids suite. This library provides common functionality for working with BIDS
+(Brain Imaging Data Structure) datasets in the Flywheel ecosystem. While care
+should be taken to add methods to the appropriate fw-bids subsuite as needs
+arise, this module contains methods that should be maintained in a common repo.
+An example of a common method is the classifications class. Changes to
+classifications will impact `import_bids` as well as `curate_bids`.
+
+## Installation
+
+### Using pip
+
+```bash
+pip install fw-bids-utils
+```
+
+### From source
+
+```bash
+git clone https://github.com/flywheel-io/fw-bids-utils.git
+cd fw-bids-utils
+pip install -e .
+```
+
+## Dependencies
+
+This package requires Python 3.11+ and includes the following dependencies:
+
+- flywheel-gear-toolkit
+- jsonschema
+- rtstatlib
+- fw-meta For development, additional dependencies are available in
+  requirements-dev.txt:
+- pytest
+- pytest-cov
+- pytest-mock
+
+## Modules
+
+### classifications
+
+Contains utilities for BIDS classification mapping:
+
+- `determine_modality`: Determine which modality a file belongs to based on the
+  parent directory's name
+- `search_classifications`: Robust search on a filename to determine
+  classifications
+
+### validate
+
+Provides validation utilities for BIDS datasets:
+
+- `validate_bids`: Validate a BIDS dataset using the bids-validator
+- `validate_project_label`: Validate that a project label exists and is unique
+
+### helpers
+
+General helper functions:
+
+- String processing with `process_string_template` and `format_value`
+- Dictionary utilities like `dict_lookup`, `dict_set`, and `dict_match`
+- Project and session ID helpers
+
+## Usage Examples
+
+### Working with BIDS Classifications
+
+```python
+from fw_bids_utils.classifications import determine_modality, search_classifications
+# Determine the modality from a filename
+modality = determine_modality("sub-01_T1w")
+# Result: "anat"
+# Get classification information
+classification = search_classifications("anat", "T1w")
+# Result: {"Measurement": "T1", "Intent": "Structural"}
+```
+
+### Validating BIDS Datasets
+
+```python
+from fw_bids_utils.validate import validate_bids
+# Validate a BIDS dataset
+is_valid = validate_bids("/path/to/bids/dataset")
+```
+
+### Using Helpers
+
+```python
+from fw_bids_utils.helpers import process_string_template
+context = {
+    "subject": {"code": "01"},
+    "session": {"label": "session1"},
+    "file": {"info": {"BIDS": {"Modality": "T1w"}}}
+}
+# Process a template string
+filename = process_string_template(
+    "sub-<subject.code>_ses-<session.label>_{file.info.BIDS.Modality}.nii.gz",
+    context
+)
+# Result: "sub-01_ses-session1_T1w.nii.gz"
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) This project
+is licensed under the MIT License - see the LICENSE file for details.

fw_bids_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fw_bids_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fw_bids_utils/classifications.py,sha256=eaozle9T_UN_EB32A6xWnnPwL8WDKTP4V4_7ASsqg-I,5800
+fw_bids_utils/dependencies.py,sha256=1Uv2Pl9vpnitC4aD-A5IMShqJjTyTynXfYbWeS-LDVc,490
+fw_bids_utils/errors.py,sha256=xWoyKgxozu-jeRrIsa5muCN5QI7m_Pm051qqo1NrZBc,1847
+fw_bids_utils/helpers.py,sha256=6r9XuAgsy5g3gs9tgxCpuMVyEfBIGu14OEX64ESkdMM,15928
+fw_bids_utils/validate.py,sha256=uqh2QppY3j6fOZJrU0hSfF20vlOYfuBV7Tk3vOwPkvI,3453
+fw_bids_utils-0.1.0.dist-info/WHEEL,sha256=mru_b36sH6joUMnwf7IlFCun3RoDjrNg9RcfBmEcqsE,81
+fw_bids_utils-0.1.0.dist-info/METADATA,sha256=P5PEG4qY0ShVAbd7-r3OXN17LwaQ-eyHKdCTJNvXY6s,3786
+fw_bids_utils-0.1.0.dist-info/RECORD,,

fw_bids_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.11
+Root-Is-Purelib: true
+Tag: py3-none-any