ARC-SCOPE

Bridge ARC crop-parameter retrieval with SCOPE radiative-transfer simulations.

ARC-SCOPE is an integration package that connects the ARC (Automated Retrieval of Crop biophysical parameters) system with the SCOPE (Soil-Canopy Observation of Photosynthesis and Energy fluxes) radiative-transfer model. It converts Sentinel-2-derived biophysical parameters into SCOPE-ready inputs, fetches meteorological forcing data, orchestrates the full simulation pipeline, and supports parameter optimisation against observed SIF, thermal, or flux data.

• PyPI: pip install arcope · pypi.org/project/arcope (imports as arc_scope)
• Documentation: marcyin.github.io/ARCOPE
• Python: 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 — CI-verified across the full range
• Source: github.com/MarcYin/ARCOPE

The repo has two example tracks:

• a real ARC retrieval -> SCOPE reflectance/SIF/thermal example for the heavy runtime
• a core-dependency showcase for fast onboarding without ARC or SCOPE

Architecture

                         ARC-SCOPE Data Flow
 ================================================================

  GeoJSON + Dates ──> ARC Retrieval
                         |
                         v
                    post_bio_tensor ──> Bridge ──> post_bio_da
                    scale_data              |      post_bio_scale_da
                                            |
                    ERA5 / Local ───> Weather Provider ──> weather_ds
                                            |
                    Field centroid ──> Observation Geometry ──> obs_ds
                                            |
                                            v
                                   prepare_scope_dataset()
                                            |
                                            v
                                     SCOPE Simulation
                                     (PyTorch runner)
                                            |
                                            v
                                  Reflectance / SIF / LST
                                  Energy-balance fluxes
                                            |
                                            v
                                   [Optional] Optimisation
                                   Tune fqe, rss, rbs, ...
                                   against observations

Installation

Requires Python 3.9 – 3.14.

The core package only needs numpy, xarray, scipy, and pandas — the heavy ARC, SCOPE, and ERA5 dependencies are opt-in via extras. This means you can run the bridge and the core-dependency showcase with a minimal install.

See docs/installation.md for detailed instructions including GDAL setup and ERA5 credential configuration.

Quick Start

1. Full run example (ARC + SCOPE)

Run the real end-to-end example from the bundled Belgium test field in 2021:

pip install "arcope[all]"
scope fetch-upstream --dest ./upstream/SCOPE
python3 -m arc_scope.experiments.dual_workflow \
  --start-date 2021-05-15 \
  --end-date 2021-10-01 \
  --growth-season-length 60 \
  --weather-provider local \
  --weather-file ./src/arc_scope/data/showcase_weather.csv \
  --scope-root-path ./upstream/SCOPE \
  --workflow reflectance \
  --workflow fluorescence \
  --workflow thermal \
  --simulation-subset-size 8 \
  --scope-chunk-size 512 \
  --dtype float32 \
  --output-dir ./full-run-output

This run performs one real ARC retrieval, prepares SCOPE inputs from weather and observation geometry, runs the validated reflectance, fluorescence, and thermal workflows, and writes a markdown report plus an extensive figure suite and browser explorer.

See docs/full-run-example.md for the artifact bundle and figure inventory.

2. Core showcase (core dependencies only)

Run the primary in-repo showcase to assemble SCOPE-shaped inputs, inspect forcing diagnostics, and fit a proxy fluorescence response without requiring ARC, SCOPE, or ERA5 credentials:

pip install arcope
python3 -m arc_scope.experiments.showcase --output-dir ./showcase-output

If you are working from a repo checkout, examples/05_showcase_experiment.py wraps the same packaged entry point.

See docs/showcase-experiment.md for the full walkthrough and generated artifacts.

3. Bridge conversion (standalone, from NPZ)

Convert saved ARC outputs to SCOPE-ready xarray DataArrays without needing ARC or SCOPE installed:

from arc_scope.bridge import arc_npz_to_scope_inputs

post_bio_da, post_bio_scale_da = arc_npz_to_scope_inputs(
    "arc_output.npz", year=2021
)
print(post_bio_da.dims)   # ('y', 'x', 'band', 'time')
print(post_bio_da.coords["band"].values)  # ['N', 'cab', 'cm', ...]

4. Full pipeline (requires ARC + SCOPE)

Run the complete workflow from a GeoJSON field boundary to SCOPE outputs:

from arc_scope.pipeline import ArcScopePipeline, PipelineConfig

config = PipelineConfig(
    geojson_path="field.geojson",
    start_date="2021-05-15",
    end_date="2021-10-01",
    crop_type="wheat",
    start_of_season=170,
    year=2021,
    scope_workflow="reflectance",
)
pipeline = ArcScopePipeline(config)
result = pipeline.run()

5. Parameter optimisation

Optimise SCOPE parameters (e.g., fluorescence quantum efficiency) against observations. The high-level pipeline can run the optimisation branch directly when optim_config provides observations and target variables:

from arc_scope.pipeline import ArcScopePipeline, PipelineConfig

config = PipelineConfig(
    geojson_path="field.geojson",
    start_date="2021-05-15",
    end_date="2021-10-01",
    crop_type="wheat",
    start_of_season=170,
    year=2021,
    scope_workflow="fluorescence",
    scope_root_path="./upstream/SCOPE",
    scope_chunk_size=512,
    optim_config={
        "enabled": True,
        "batch_size": 256,
        "observations_path": "observed_f740.nc",
        "target_variables": ["F740"],
        "parameters": [
            {"name": "fqe", "initial": 0.01, "lower": 0.001, "upper": 0.1, "transform": "log"}
        ],
        "optimizer": {"type": "scipy", "method": "L-BFGS-B", "use_autograd_jac": "required"},
    },
)

result = ArcScopePipeline(config).run()
print(result.optimization_result.parameters_optimized)

The Optimization Guide includes proxy examples for SIF, thermal, and energy-balance fitting plus a real ARC -> upstream SCOPE fluorescence run where fqe recovers a known F740 twin-observation target.

Module Overview

Configuration Reference

PipelineConfig is a dataclass that controls the entire pipeline:

SCOPE Workflows

Examples

Working examples are in the examples/ directory:

• 01_bridge_conversion.py -- Convert synthetic ARC arrays to SCOPE format (no external dependencies)
• 02_reflectance_simulation.py -- Prepare and inspect a SCOPE-ready dataset
• 03_full_pipeline.py -- Complete pipeline configuration and step-by-step execution
• 04_optimization_demo.py -- Parameter optimisation workflow with transforms and injection
• 05_showcase_experiment.py -- Core-only showcase experiment with local weather, geometry, radiation partitioning, and proxy calibration
• 06_dual_workflow_full_run.py -- Real ARC retrieval plus a documented SCOPE reflectance run with artifact generation
• 07_optimization_examples.py -- Generate reproducible optimisation output tables and SVG fit plots for the optimisation guide

Development

git clone https://github.com/MarcYin/ARCOPE.git
cd ARCOPE
pip install -e ".[dev]"
python -m pytest --tb=short -q

CI runs the full test suite against Python 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14 on every push.

Releases

• Current: see the PyPI page and the GitHub releases.
• Changelog: CHANGELOG.md.
• Maintainers: release steps are documented in RELEASING.md. Publishes via GitHub Actions with PyPI OIDC trusted publishing — no long-lived tokens.

License

MIT -- see LICENSE for details.