pymaude 0.2.0__tar.gz

pymaude-0.2.0/.github/workflows/pypi.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      url: https://pypi.org/project/PyMAUDE/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

pymaude-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+venv/
+maude_data/
+maude_archive/
+*.tmp
+*.yaml
+*.DS_Store 
+*.duckdb
+*.wal
+*.pyc
+*/__pycache__
+*/*.egg-info/
+*.zip
+dev_local/

pymaude-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Schwartz
+
+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.

pymaude-0.2.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: pymaude
+Version: 0.2.0
+Summary: PyMAUDE: FDA MAUDE adverse event database interface
+Author-email: Jacob Schwartz <jaschwa@umich.edu>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=0.10.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file

pymaude-0.2.0/example.ipynb

@@ -0,0 +1,546 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "fac46bca",
+   "metadata": {},
+   "source": "# PyMAUDE — Example Notebook\n\n**PyMAUDE** is a Python library for accessing and analyzing FDA MAUDE (Manufacturer and User Facility Device Experience) adverse event data via a fast [DuckDB](https://duckdb.org/) backend.\n\nThis notebook downloads real FDA MAUDE data and demonstrates all major library capabilities using venous stent and rotational thrombectomy devices as worked examples.\n\n> **First run:** `add_years(..., download=True)` downloads zip files from the FDA FTP server (~few hundred MB for 3 years of device/master/text). Subsequent runs use the local cache and skip unchanged files via SHA-256 checksum.\n\n---\n## Contents\n1. [Setup](#1-setup)\n2. [Download & load data](#2-load)\n3. [Inspect the database](#3-inspect)\n4. [Exact-field queries](#4-exact)\n5. [Substring search](#5-search)\n6. [Grouped search across device classes](#6-grouped)\n7. [Event narratives](#7-narratives)\n8. [Enrich with patient outcomes](#8-patient)\n9. [Enrich with device problem codes](#9-problems)\n10. [Trend analysis by year](#10-trends)\n11. [Raw SQL](#11-sql)\n12. [Archive a snapshot for publication](#12-archive)"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c51af603",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 1. Setup <a id=\"1-setup\"></a>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "2cb7914b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymaude import MaudeDatabase\n",
+    "\n",
+    "DB_PATH  = './maude.duckdb'   # persistent DuckDB file\n",
+    "DATA_DIR = './maude_data'     # downloaded zip/txt files live here\n",
+    "YEARS    = '2024-2026'        # adjust to taste; more years = more data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7b7d402f",
+   "metadata": {},
+   "source": "---\n## 2. Download & load data <a id=\"2-load\"></a>\n\nPass `download=True` to fetch from the FDA FTP area. Files are cached locally — re-running this cell only downloads files whose SHA-256 checksum has changed since the last run."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "033387c3",
+   "metadata": {},
+   "outputs": [],
+   "source": "db = MaudeDatabase(DB_PATH, data_dir=DATA_DIR, verbose=True, memory_limit='2GB')\n\ndb.add_years(\n    YEARS,\n    # tables=['master', 'device', 'text', 'patient', 'problem'],\n    # tables=['master', 'device', 'text', 'problem'],\n    tables=['master', 'problem'],\n    download=True\n)"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "31bc09f7",
+   "metadata": {},
+   "source": "To pull in the latest monthly FDA updates at any point — this is also the safest way to refresh cumulative tables (`master`, `patient`, `problem`), since it automatically re-requests every year they already have loaded:\n```python\ndb.update(download=True)\n```"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e2ab5aa5",
+   "metadata": {},
+   "source": "Call `add_years()` again at any time to extend coverage or add more tables — here we add `device`, `text`, and `patient` outcomes alongside the same year range.\n\nNote: `master` and `problem` are cumulative tables — they're fully replaced on every reload rather than updated year-by-year, so `add_years()` rejects a request that doesn't cover every year they already have loaded (it would otherwise silently drop the missing years). That's why this passes the full `YEARS` range again rather than just `'2026'` — pass `force_partial=True` if you really do want to narrow an existing cumulative table's coverage."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fb16afa6",
+   "metadata": {},
+   "outputs": [],
+   "source": "db.add_years(YEARS, download=True)"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2cac8f0a",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 3. Inspect the database <a id=\"3-inspect\"></a>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ceb0edfe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "db.info()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "03522383",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 4. Exact-field queries <a id=\"4-exact\"></a>\n",
+    "\n",
+    "`query_device()` does **exact, case-insensitive** matching. Combine any of `brand_name`, `generic_name`, `manufacturer_name`, `product_code`, `start_date`, `end_date`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d36aad1d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# All events for a specific product code (NIQ = venous stents)\n",
+    "niq = db.query_device(product_code='NIQ')\n",
+    "print(f'NIQ (venous stent) events loaded: {len(niq):,}')\n",
+    "niq[['MDR_REPORT_KEY', 'BRAND_NAME', 'GENERIC_NAME', 'MANUFACTURER_D_NAME', 'DATE_RECEIVED']].head(10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "27d566c9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Narrow to a specific brand + date window\n",
+    "bsci_jan_thru_aug_2021 = db.query_device(\n",
+    "    brand_name='Boston Scientific',\n",
+    "    start_date='2021-01-01',\n",
+    "    end_date='2021-08-31'\n",
+    ")\n",
+    "\n",
+    "print(f'Boston Scientific events in 2021 Jan-Aug: {len(bsci_jan_thru_aug_2021):,}')\n",
+    "bsci_jan_thru_aug_2021[['MDR_REPORT_KEY', 'BRAND_NAME', 'EVENT_TYPE', 'MANUFACTURER_G1_NAME', 'DATE_RECEIVED']]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dc8abaa4",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 5. Substring search <a id=\"5-search\"></a>\n",
+    "\n",
+    "`search_by_device_names()` does **case-insensitive substring matching** across a synthesized `DEVICE_NAME_CONCAT` column (BRAND_NAME | GENERIC_NAME | MANUFACTURER_D_NAME concatenated). This is useful because MAUDE entries are often inconsistent, with names of medical devices often appearing in one of these three columns. \n",
+    "\n",
+    "| Criteria format | Logic |\n",
+    "|---|---|\n",
+    "| `'term'` | single substring |\n",
+    "| `['a', 'b']` | a **OR** b |\n",
+    "| `[['a', 'b'], 'c']` | (a **AND** b) **OR** c |\n",
+    "| `{'group1': ..., 'group2': ...}` | grouped (see [section 6](#6-grouped)) |"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "29942997",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Simple substring — anything with \"venous stent\" in any name field\n",
+    "venous_stents = db.search_by_device_names('venous stent')\n",
+    "print(f'Events matching \"venous stent\": {len(venous_stents):,}')\n",
+    "venous_stents[['MDR_REPORT_KEY', 'BRAND_NAME', 'GENERIC_NAME', 'DATE_RECEIVED']]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "abc1713f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# OR logic — venous stent OR iliac stent\n",
+    "venous_iliac = db.search_by_device_names(['venous stent', 'iliac stent'])\n",
+    "print(f'Venous OR iliac stents: {len(venous_iliac):,}')\n",
+    "venous_iliac['GENERIC_NAME'].value_counts().head(10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bfcfe120",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# AND logic — must contain both \"argon\" AND \"cleaner\" (avoids false positives)\n",
+    "argon_cleaner = db.search_by_device_names([['argon','cleaner']])\n",
+    "print(f'Argon AND Cleaner events: {len(argon_cleaner):,}')\n",
+    "argon_cleaner[['MDR_REPORT_KEY', 'BRAND_NAME', 'GENERIC_NAME', 'MANUFACTURER_D_NAME', 'DATE_RECEIVED']]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d894b316",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Combined: (argon AND cleaner) OR (angiojet) OR (thrombectomy)\n",
+    "thrombectomy_broad = db.search_by_device_names(\n",
+    "    [['argon', 'cleaner'], 'angiojet', 'rotational thrombectomy']\n",
+    ")\n",
+    "print(f'Broad rotational thrombectomy search: {len(thrombectomy_broad):,}')\n",
+    "thrombectomy_broad[['MDR_REPORT_KEY', 'BRAND_NAME', 'GENERIC_NAME']].head(10)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "11fa003a",
+   "metadata": {},
+   "source": [
+    "Results are pandas DataFrames — export anytime:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ad725c72",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "thrombectomy_broad.to_csv('thrombectomy_broad.csv', index=False)\n",
+    "thrombectomy_broad.to_excel('thrombectomy_broad.xlsx', index=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "defb6b57",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 6. Grouped search across device classes <a id=\"6-grouped\"></a>\n",
+    "\n",
+    "A **dict** of criteria runs multiple searches at once and labels each result with a `search_group` column. Useful for comparative studies."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ba497816",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grouped = db.search_by_device_names({\n",
+    "    'venous_stents':  ['venous stent', 'venous stenting'],\n",
+    "    'thrombectomy':   [['argon', 'cleaner'], 'angiojet', 'rotational thrombectomy'],\n",
+    "})\n",
+    "\n",
+    "print(f'Total events: {len(grouped):,}')\n",
+    "print('\\nEvents by group:')\n",
+    "print(grouped['search_group'].value_counts().to_string())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4f737489",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "grouped[['MDR_REPORT_KEY', 'BRAND_NAME', 'GENERIC_NAME', 'search_group']].head(15)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8f8b4418",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 7. Event narratives <a id=\"7-narratives\"></a>\n",
+    "\n",
+    "`get_narratives()` fetches the free-text FOI_TEXT descriptions for a set of MDR_REPORT_KEYs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "505d9360",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "narratives = db.get_narratives(thrombectomy_broad['MDR_REPORT_KEY'])\n",
+    "print(f'Narratives retrieved: {len(narratives):,}')\n",
+    "narratives.head(5)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cb10a454",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Read a few narratives in full\n",
+    "for _, row in narratives.head(3).iterrows():\n",
+    "    print(f\"=== MDR {row['MDR_REPORT_KEY']} ===\")\n",
+    "    print(row['FOI_TEXT'][:500])\n",
+    "    print()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2f8d0518",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 8. Enrich with patient outcomes <a id=\"8-patient\"></a>\n",
+    "\n",
+    "`enrich_with_patient_data()` left-joins the patient outcomes table. `SEQUENCE_NUMBER_OUTCOME` codes:\n",
+    "- `D` Death · `IN` Injury · `H` Hospitalization · `LT` Life Threatening · `OT` Other · `R` Required Intervention"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dc713f30",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "enriched = db.enrich_with_patient_data(thrombectomy_broad)\n",
+    "\n",
+    "with_outcome = enriched.dropna(subset=['SEQUENCE_NUMBER_OUTCOME'])\n",
+    "print(f'Events with patient outcome data: {len(with_outcome):,} / {len(enriched):,}')\n",
+    "with_outcome[['MDR_REPORT_KEY', 'BRAND_NAME', 'SEQUENCE_NUMBER_OUTCOME']].head(10)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8e86fb47",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "OUTCOME_LABELS = {\n",
+    "    'D': 'Death', 'IN': 'Injury', 'H': 'Hospitalization',\n",
+    "    'LT': 'Life Threatening', 'OT': 'Other', 'R': 'Required Intervention'\n",
+    "}\n",
+    "\n",
+    "outcome_counts = (\n",
+    "    with_outcome['SEQUENCE_NUMBER_OUTCOME']\n",
+    "    .str.split(';')\n",
+    "    .explode()\n",
+    "    .map(lambda c: OUTCOME_LABELS.get(c, c))\n",
+    "    .value_counts()\n",
+    ")\n",
+    "outcome_counts"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "074fc0f5",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 9. Enrich with device problem codes <a id=\"9-problems\"></a>\n",
+    "\n",
+    "`enrich_with_problems()` left-joins the device problem code table (available from 2019 onwards)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "55390046",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with_problems = db.enrich_with_problems(thrombectomy_broad)\n",
+    "\n",
+    "problem_counts = (\n",
+    "    with_problems\n",
+    "    .dropna(subset=['DEVICE_PROBLEM_CODE'])\n",
+    "    ['DEVICE_PROBLEM_CODE']\n",
+    "    .value_counts()\n",
+    ")\n",
+    "print(f'Events with a problem code: {problem_counts.sum():,}')\n",
+    "print('\\nTop problem codes:')\n",
+    "problem_counts.head(10)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b176b2ed",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## 10. Trend analysis by year <a id=\"10-trends\"></a>\n",
+    "\n",
+    "`get_trends_by_year()` counts events per calendar year. When results include a `search_group` column it breaks down by group automatically."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "268e04d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Overall year-over-year trend\n",
+    "trends = db.get_trends_by_year(thrombectomy_broad)\n",
+    "print('Rotational thrombectomy — events by year:')\n",
+    "print(trends.to_string(index=False))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8fcf1083",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Per-group trends\n",
+    "group_trends = db.get_trends_by_year(grouped)\n",
+    "print('Events by year and device group:')\n",
+    "print(group_trends.to_string(index=False))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8a27263f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Pivot for side-by-side comparison\n",
+    "if 'search_group' in group_trends.columns:\n",
+    "    pivot = (\n",
+    "        group_trends\n",
+    "        .pivot(index='year', columns='search_group', values='event_count')\n",
+    "        .fillna(0).astype(int)\n",
+    "    )\n",
+    "    print(pivot.to_string())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ba90769d",
+   "metadata": {},
+   "source": "---\n## 11. Raw SQL <a id=\"11-sql\"></a>\n\n`db.query()` exposes DuckDB directly. Tables available: `master`, `device`, `text`, `patient`, `problem`."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6d0a3dd3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Event type breakdown across all loaded data\n",
+    "db.query(\"\"\"\n",
+    "    SELECT\n",
+    "        EVENT_TYPE,\n",
+    "        CASE EVENT_TYPE\n",
+    "            WHEN 'D'  THEN 'Death'\n",
+    "            WHEN 'IN' THEN 'Injury'\n",
+    "            WHEN 'M'  THEN 'Malfunction'\n",
+    "            WHEN 'O'  THEN 'Other'\n",
+    "            ELSE EVENT_TYPE\n",
+    "        END AS label,\n",
+    "        COUNT(*) AS n\n",
+    "    FROM master\n",
+    "    GROUP BY EVENT_TYPE\n",
+    "    ORDER BY n DESC\n",
+    "\"\"\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c380f28d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Top 10 manufacturers by adverse event volume (master joined to device)\n",
+    "db.query(\"\"\"\n",
+    "    SELECT\n",
+    "        d.MANUFACTURER_D_NAME,\n",
+    "        COUNT(DISTINCT m.MDR_REPORT_KEY) AS events\n",
+    "    FROM master m\n",
+    "    JOIN device d USING (MDR_REPORT_KEY)\n",
+    "    GROUP BY d.MANUFACTURER_D_NAME\n",
+    "    ORDER BY events DESC\n",
+    "    LIMIT 10\n",
+    "\"\"\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "40bc7adc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Parameterized query — safe for user-supplied input\n",
+    "db.query(\n",
+    "    \"SELECT MDR_REPORT_KEY, BRAND_NAME, DATE_RECEIVED FROM device WHERE DEVICE_REPORT_PRODUCT_CODE = ? LIMIT 10\",\n",
+    "    params=['NIQ']\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "afaade88",
+   "source": "---\n## 12. Archive a snapshot for publication <a id=\"12-archive\"></a>\n\nMAUDE is updated continuously and isn't versioned, so a query run today may return different results in a year. `db.archive()` freezes the exact database backing an analysis so it can be cited or uploaded alongside a paper (e.g. to Zenodo):\n\n- Checkpoints and copies the DuckDB file itself.\n- Writes a `manifest.json` recording, per loaded table/year: source file, SHA-256 checksum, row count, and load timestamp — plus the DuckDB and pymaude versions used to build it.\n- With `include_raw=True`, also copies the raw MAUDE source files referenced in the manifest into `output_dir/raw/`, so reviewers can re-derive the database from scratch.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "3eb5e80e",
+   "source": "manifest_path = db.archive('./maude_archive', include_raw=False)\nprint(f'Archive written, manifest at: {manifest_path}')",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "id": "26bdab3c",
+   "source": "# Inspect the generated manifest — this is what accompanies the archived .duckdb file\nimport json\n\nwith open(manifest_path) as f:\n    manifest = json.load(f)\n\nprint(f\"pymaude {manifest['pymaude_version']}  ·  duckdb {manifest['duckdb_version']}  ·  {manifest['checksum_algorithm']}\")\nprint(f\"Database: {manifest['database']['filename']} ({manifest['database']['size_bytes']:,} bytes)\")\nprint(f\"Tables tracked: {len(manifest['tables'])}\")\nmanifest['tables'][:5]",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2a116968",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "db.close()\n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv (3.12.3)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}