esa-philab/phidown

Phidown

Overview

Use this skill to run reliable search and download workflows with the phidown repository. Prefer deterministic commands, validate inputs early, and return reproducible download/search steps.

Workflow

1. Confirm execution context

• Work from the phidown repo root.
• Check tooling before running downloads:

python --version
which s5cmd
python -m pip show phidown

• If s5cmd is missing, stop and report the blocker.

2. Choose operation mode

• Use CLI download by product name when the exact product name is known.
• Use CLI download by S3 path when catalog lookup is unnecessary.
• Use CLI list subcommand (phidown list ...) when the user needs quick AOI/date product discovery.
• Use CLI burst coverage mode for Sentinel-1 burst optimization over AOI/date.
• Use Python CopernicusDataSearcher for advanced filtering, custom analysis, or notebook workflows.

3. Handle credentials safely

• Use .s5cfg for S3 downloads (CLI path).
• If missing, explain that phidown prompts for access key and secret key on first download or --reset.
• Never print secrets in output.

4. Execute with minimal, reproducible commands

• Download by name:

phidown --name "<PRODUCT_NAME>" -o "<OUTPUT_DIR>"

• Download by S3 path:

phidown --s3path "/eodata/..." -o "<OUTPUT_DIR>"

• List products over AOI/date:

phidown list --collection "SENTINEL-1" --product-type "GRD" --bbox -5 40 5 45 --start-date "2024-01-01T00:00:00" --end-date "2024-01-31T23:59:59" --format "table"

• Burst coverage analysis over AOI/date:

phidown --burst-coverage --bbox -5 40 5 45 --start-date "2024-08-02T00:00:00" --end-date "2024-08-15T23:59:59" --polarisation "VV" --format "json" --save "<OUTPUT_FILE>"

• Search first, then inspect top rows:

from phidown.search import CopernicusDataSearcher

searcher = CopernicusDataSearcher()
searcher.query_by_filter(
    collection_name="SENTINEL-1",
    product_type="SLC",
    aoi_wkt="POLYGON((...))",
    start_date="2025-01-01T00:00:00",
    end_date="2025-01-31T23:59:59",
    top=100,
)
df = searcher.execute_query()
print(len(df))
print(df[["Name", "S3Path"]].head(5))

5. Verify outcome

• Confirm command exit status.
• For downloads, confirm expected files exist under output directory.
• For list/analysis with --save, confirm output file exists and is non-empty.
• Report what was downloaded/listed/analyzed (or why no product matched).

Guardrails

• Keep paths absolute when scripting automation.
• Validate S3 path starts with /eodata/ before invoking download.
• Validate AOI WKT is polygon and date strings are ISO 8601 when building search queries.
• Prefer phidown list ... over phidown --list ... in new examples and user guidance.
• For --burst-coverage, require both --start-date and --end-date.
• Remember burst availability starts on 2024-08-02; earlier windows will return no bursts.
• Prefer targeted tests over full suite when network-heavy tests are present.

Troubleshooting

• For empty search results, relax filters one at a time: AOI -> date range -> product type -> attributes.
• For empty burst results, validate date window is on/after 2024-08-02 and relax orbit/subswath filters.
• For auth failures, refresh .s5cfg using --reset.
• For download instability, retry with reduced scope (--no-download-all for S3 path mode).

References

• For ready-to-run command patterns, read references/commands.md.