Merge pull request #180 from MIT-LCP/tp/download

Add simple dataset download support

Author: tompollard

README.md

@@ -15,6 +15,61 @@ Requires Python 3.9 or later.
 The package provides a `physionet` command-line tool. You can also run it as a
 module with `python -m physionet`.
 
+### `physionet download`
+
+Download datasets from PhysioNet:
+
+```bash
+# Download the latest version of a dataset
+physionet download mimic-iv-demo
+
+# Download a specific version
+physionet download mimic-iv-demo --version 2.2
+
+# Download to a specific directory
+physionet download mimic-iv-demo --output /data
+
+# Preview what would be downloaded
+physionet download mimic-iv-demo --dry-run
+
+# Download only specific files
+physionet download mimic-iv-demo --include "*.csv" --exclude "*/notes/*"
+```
+
+**Download sources:**
+
+The `--source` flag controls where files are downloaded from:
+
+- `auto` (default) — tries S3 first, falls back to PhysioNet direct if the dataset is not available on S3
+- `physionet` — always downloads from PhysioNet directly
+- `aws` — downloads from S3 using boto3 and the standard AWS credential chain
+
+```bash
+# Download from PhysioNet directly
+physionet download mimic-iv-demo --source physionet
+
+# Download from S3 using boto3
+physionet download mimic-iv-demo --source aws
+```
+
+When using `--source aws`, boto3 discovers credentials automatically via the [standard AWS credential chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) (environment variables, `~/.aws/credentials`, IAM roles, etc.). This allows downloading credentialed datasets from S3 without passing PhysioNet credentials.
+
+**Authentication:**
+
+For credentialed datasets, provide PhysioNet credentials via flags or environment variables:
+
+```bash
+# Via flags
+physionet download mimic-iv --username user --password pass
+
+# Via environment variables
+export PHYSIONET_USERNAME=user
+export PHYSIONET_PASSWORD=pass
+physionet download mimic-iv
+```
+
+Downloads support automatic resume, SHA256 checksum verification, and retry on transient errors.
+
 ### `physionet validate`
 
 Validate a dataset before submission to PhysioNet. The validator checks for
@@ -72,9 +127,21 @@ physionet validate /path/to/dataset --max-rows 5000
 - `0` - Validation passed (no errors).
 - `1` - Validation failed with errors.
 
-### Validation from Python
+## Python API
+
+### Download
+
+```python
+from physionet.download import download
+
+# Download a dataset
+download("mimic-iv-demo", version="2.2", output_dir="/data")
+
+# Download from S3 using boto3
+download("mimic-iv-demo", source="aws")
+```
 
-The validator can also be used as a Python library:
+### Validation
 
 ```python
 from physionet import validate_dataset, ValidationConfig
@@ -101,7 +168,7 @@ print(result.summary())
 data = result.to_dict()
 ```
 
-## API Client
+### API Client
 
 Interact with the PhysioNet REST API to explore and search published projects:
 

physionet/__init__.py

@@ -1,5 +1,6 @@
 from physionet.api import PhysioNetClient
 from physionet.validate import validate_dataset, ValidationConfig, ValidationResult
+from physionet.download import download
 
 try:
     from importlib.metadata import version
@@ -12,4 +13,5 @@
     "validate_dataset",
     "ValidationConfig",
     "ValidationResult",
+    "download",
 ]

physionet/cli.py

@@ -17,6 +17,54 @@ def main():
 
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
+    # Download subcommand
+    download_parser = subparsers.add_parser(
+        "download",
+        help="Download a dataset from PhysioNet",
+    )
+    download_parser.add_argument(
+        "slug",
+        help="Project identifier (e.g., mimic-iv-demo)",
+    )
+    download_parser.add_argument(
+        "--version",
+        help="Project version to download (default: latest)",
+    )
+    download_parser.add_argument(
+        "--output",
+        default=".",
+        help="Output directory (default: current directory)",
+    )
+    download_parser.add_argument(
+        "--include",
+        action="append",
+        help="Glob pattern for files to include (can be repeated)",
+    )
+    download_parser.add_argument(
+        "--exclude",
+        action="append",
+        help="Glob pattern for files to exclude (can be repeated)",
+    )
+    download_parser.add_argument(
+        "--source",
+        choices=["auto", "physionet", "aws"],
+        default="auto",
+        help="Download source (default: auto)",
+    )
+    download_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be downloaded without downloading",
+    )
+    download_parser.add_argument(
+        "--username",
+        help="PhysioNet username (or set PHYSIONET_USERNAME env var)",
+    )
+    download_parser.add_argument(
+        "--password",
+        help="PhysioNet password (or set PHYSIONET_PASSWORD env var)",
+    )
+
     # Validate subcommand
     validate_parser = subparsers.add_parser(
         "validate",
@@ -56,7 +104,9 @@ def main():
 
     args = parser.parse_args()
 
-    if args.command == "validate":
+    if args.command == "download":
+        return _handle_download(args)
+    elif args.command == "validate":
         return _handle_validate(args)
     elif args.command is None:
         parser.print_help()
@@ -66,6 +116,39 @@ def main():
         return 1
 
 
+def _handle_download(args):
+    """Handle the download subcommand."""
+    from physionet.download import download
+    from physionet.api.exceptions import ForbiddenError, NotFoundError
+
+    try:
+        download(
+            slug=args.slug,
+            version=args.version,
+            output_dir=args.output,
+            include=args.include,
+            exclude=args.exclude,
+            source=args.source,
+            dry_run=args.dry_run,
+            username=args.username,
+            password=args.password,
+        )
+        return 0
+    except NotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except ForbiddenError as e:
+        print(f"Access denied: {e}", file=sys.stderr)
+        print(
+            f"Visit https://physionet.org/content/{args.slug}/ to request access.",
+            file=sys.stderr,
+        )
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
 def _handle_validate(args):
     """Handle the validate subcommand."""
     # Validate path