Add example acquisition config file.

Author: hyletic

.gitignore

@@ -217,3 +217,7 @@ __marimo__/
 
 # Project-specific files
 output/
+
+# Miscellaneous exclusions
+*.bak
+acquisition.yaml

acquisition.example.yaml

@@ -0,0 +1,66 @@
+---
+# acquisition.yaml
+#
+# Optionally explain why you've identified these specific gene symbols as suitable
+# candidates for further analysis.
+#
+# Target Gene Symbols
+# -------------------
+#
+# The `target_gene_symbols` field must comprise an array of valid gene symbols,
+# as in the below provided example, which targets a subset of genes associated with
+# heritable connective tissue diseases.
+#
+target_gene_symbols:
+  - COL5A1
+  - COL5A2
+  - COL1A1
+  - COL3A1
+  - PLOD1
+  - FKBP14
+  - COL1A1
+  - COL1A2
+  - ADAMTS2
+  - ZNF469
+  - PRDM5
+  - TNXB
+  - COL1A2
+  - CHST14
+  - DSE
+  - COL12A1
+  - C1R
+  - C1S
+  - B4GALT7
+  - B3GALT6
+  - SLC39A13
+  - COL1A3
+  - AEBP1
+  - COL6A1
+  - COL6A2
+  - COL6A3
+  - PLOD2
+  - PLOD3
+  - P4HB
+  - LEPRE1
+  - CRTAP
+  - PPIB
+  - SERPINH1
+  - P3H1
+  - P3H2
+  - P3H3
+  - P3H4
+  - KLK15
+  - MTHFR
+
+
+# Parameters for API Request Headers
+# ----------------------------------
+#
+# LOVDTools includes this information in every API request to the Global
+# Variome–shared LOVD instance. This helps the instance's web administrators to better
+# understand how researchers actually use the API in practice and, more importantly,
+# to secure the database's server(s) against malicious requests.
+#
+email: "contact@example.com"                              # REQUIRED, as per LOVD docs
+user_agent: "My-Organization/1.0 (my research purpose)"   # Optional
+...

acquisition.yaml

@@ -3,11 +3,12 @@
 ===========
 
 This module defines and implements an interface for querying the Global
-Variome shared Leiden Open Variants Database (LOVD) instance.
+Variome–shared Leiden Open Variants Database (LOVD) instance.
 
 """
 from __future__ import annotations
 
+import json
 import logging
 import os
 import time
@@ -21,27 +22,29 @@
 
 from lovd.constants import EMAIL, TARGET_GENE_SYMBOLS, USER_AGENT_STRING
 
+
+# ─── type aliases ───────────────────────────────────────────────────────────────── ✦ ─
+#
+JSONDecodeError: TypeAlias = json.JSONDecodeError
+Logger: TypeAlias = logging.Logger
+PathLike: TypeAlias = os.PathLike
+YAMLError: TypeAlias = yaml.YAMLError
+
 # ─── logger setup ───────────────────────────────────────────────────────────────── ✦ ─
 #
 # This `logging.Logger` instance is not used for logging responses to the
 # LOVD client's API requests. That logger is defined on `LOVDClient` as
 # its `.logger` attribute.
 #
-logging.basicConfig(
-    level="INFO",
-    format="%(name)s – %(message)s"
-)
+logging.basicConfig(level="INFO", format="%(name)s – %(message)s")
 logger = logging.getLogger(__name__)
 logger.info("Logger setup complete.")
 
 
-# ─── type aliases ───────────────────────────────────────────────────────────────── ✦ ─
-#
-PathLike: TypeAlias = os.PathLike
-
-
 # ─── get environment variables from `.env` ──────────────────────────────────────── ✦ ─
 #
+# TODO: Assess whether loading configurations from both `acquisition.yaml` and `.env`.
+#
 try:
     load_dotenv()
 except FileNotFoundError as e:
@@ -52,15 +55,15 @@
 
 # ─── rate limiting ──────────────────────────────────────────────────────────────── ✦ ─
 #
-# The [LOVD 3.0 user manual](https://databases.lovd.nl/shared/docs/manual.html)
-# stipulates that users ought to limit their API request rates "to a maximum of
-# 5 per second per server/domain," which translates to a fixed rate of one
-# API request per 0.2 seconds.
+#: The [LOVD 3.0 user manual](https://databases.lovd.nl/shared/docs/manual.html)
+#: stipulates that users ought to limit their API request rates "to a maximum of
+#: 5 per second per server/domain," which translates to a fixed rate of one
+#: API request per 0.2 seconds.
 #
 LOVD_RATE_LIMIT: int = 5
 
 
-# ─── configuration loading ──────────────────────────────────────────────────────── ✦ ─
+# | loaders
 #
 def load_acquisition_config(config_path: PathLike | None = None) -> dict[str, Any]:
     """
@@ -117,18 +120,89 @@ def load_acquisition_config(config_path: PathLike | None = None) -> dict[str, An
             try:
                 with open(config_file, "r", encoding="utf-8") as f:
                     user_config = yaml.safe_load(f) or {}
-                
+
                 # Merge the user's config specifications with defaults.
                 config.update(user_config)
                 logger.info(f"Loaded configuration from {config_file}")
                 break
             except (yaml.YAMLError, OSError) as e:
                 logger.warning(f"Failed to load config from {config_file}: {e}")
                 continue
-    
+
     return config
 
 
+def load_variants(
+    filepath: str | PathLike | None = None
+) -> dict[str, Any]:
+    """
+    Load variants from a given filepath.
+
+    Parameters
+    ----------
+    filepath : str | PathLike, optional
+        A a string or path-like object representing the file or directory
+        from which to load a corpus of JSON-serialized variant records.
+
+    Returns
+    -------
+    A dictionary containing the variant records loaded from ``filepath``.
+
+    """
+    if isinstance(filepath, str) and filepath.startswith("~"):
+        filepath: PathLike = Path(filepath).expanduser()
+    elif isinstance(filepath, str):
+        filepath = Path(filepath)
+    else:
+        pass
+
+    if not filepath.exists():
+        logger.error(f"Failed to load variant records from `{filepath}`.")
+        raise FileNotFoundError("Unable to locate the provided filepath.")
+
+    variants: dict[str, Any] = {}
+
+    if filepath.is_dir():
+        logger.info(f"Iterating over directory `{filepath}`...")
+        for fp in filepath.iterdir():
+            if fp.suffix == ".json":
+                logger.info(f"Found JSON file `{fp}`; extracting data...")
+                with open(fp, "r") as f:
+                    try:
+                        data: dict[str, Any] = json.load(f)
+                        for sym, dat in data.items():
+                            variants[sym] = dat
+                        logger.info(f"Successfully decoded JSON data at {fp}.")
+                    except JSONDecodeError as e:
+                        logger.error("Failed to decode JSON.")
+                        raise e
+        else:
+            logger.info(f"Successfully iterated over directory `{filepath}.")
+    else:
+        if not filepath.suffix == ".json":
+            logger.error("Received a non-JSON file reference as input.")
+            raise ValueError("The `filepath` argument must point either to a non-empty "
+                             "directory or a JSON file.")
+        else:
+            logger.info(f"Extracting data from `{filepath}...")
+            with open(filepath, "r") as f:
+                try:
+                    data: dict[str, Any] = json.load(f)
+                    for sym, dat in data.items():
+                        variants[sym] = dat
+                    logger.info(f"Successfully decoded JSON data at {filepath}.")
+                except JSONDecodeError as e:
+                    logger.error("Failed to decode JSON.")
+                    raise e
+                except IOError as e:
+                    logger.error("Encountered an unhandled I/O exception.")
+                    raise e
+
+    # If we've made it this far, `variants` should be a dictionary that contains
+    # gene symbols mapped to their variant records.
+    return variants
+
+
 # ─── interface ──────────────────────────────────────────────────────────────────── ✦ ─
 #
 class LOVDClient:
@@ -138,7 +212,7 @@ class LOVDClient:
 
     def __init__(
         self,
-        config_path: PathLike | None = None,
+        config: dict | PathLike | None = None,
         email: str | None = None,
         target_gene_symbols: list[str] | None = None,
         user_agent: str | None = None,
@@ -154,7 +228,7 @@ def __init__(
 
         Parameters
         ----------
-        config_path : PathLike, optional
+        config_path : dict | PathLike, optional
             A path-like object representing the acquisition configuration
             filepath. If left unspecified, this constructor searches for
             ``acquisition.yaml`` first in the current working directory
@@ -180,7 +254,10 @@ def __init__(
             progress indicator during execution. Defaults to ``None``.
 
         """
-        self.config = load_acquisition_config(config_path)
+        if isinstance(config, dict):
+            self.config = config
+        else:
+            self.config = load_acquisition_config(config)
 
         # ─── configuration ────────────────────────────────────────────────────────────
         #
@@ -500,7 +577,7 @@ def get_variants_for_genes(
                     suffix_parts = []
                     if search_terms:
                         suffix_parts.append("filtered")
-                    
+
                     suffix = (
                         f"_{'_'.join(suffix_parts)}_variants.json"
                         if suffix_parts
@@ -673,7 +750,7 @@ def get_lovd_variants(
     >>> variants = get_lovd_variants(config_path="my_project.yaml")
 
     """
-    client = LOVDClient(config_path=config_path)
+    client = LOVDClient(config=config_path)
 
     # Use config values as defaults, overriding with any specified parameters.
     target_gene_symbols = genes or client.config.get("target_gene_symbols")
@@ -761,7 +838,7 @@ def variants_to_dataframe(
         try:
             from tqdm import tqdm
             items = tqdm(variants_data.items())
-        except ImportError as e:
+        except ImportError:
             logger.warning(
                 "`tqdm` does not appear to be installed, so `.with_progress()`\n"
                 "has no effect. To suppress this warning, run the following\n"