A Python library for FLUXNET shuttle to discover and download global FLUXNET data from multiple data hubs, including AmeriFlux, ICOS, and TERN.

• Data Download: Download FLUXNET data from data hubs
• Metadata Snapshot: List metadata for FLUXNET data available via the data hubs
• Command Line Interface: Easy-to-use CLI tool fluxnet-shuttle for common operations
• Comprehensive Logging: Configurable logging with multiple outputs
• Error Handling: Custom exception handling for FLUXNET operations
• Documentation and Examples: Documentation for CLI and API (direct python usage) and example Jupyter Notebook

The FLUXNET data are shared under a CC-BY-4.0 data use license which requires attribution for each data use. See the data use license document contained within the FLUXNET data product (archive zip file) for details.

This library supports Python 3.11, 3.12, and 3.13. Python 3.9 and 3.10 should work but are not officially supported. Python versions before 3.9 are not allowed.

pip install git+https://github.com/fluxnet/shuttle.git

The library includes a command-line tool fluxnet-shuttle that provides easy access to core functionality:

Discover all available FLUXNET data products and their metadata:

fluxnet-shuttle --verbose listall

• Queries all connected data hubs
• Creates a timestamped CSV file with metadata and download information

Download data for specific sites:

# Download specific sites
fluxnet-shuttle download -f fluxnet_shuttle_snapshot_YYYYMMDDTHHMMSS.csv -s IT-Niv NZ-ADd

# Download ALL sites from snapshot (prompts for confirmation)
fluxnet-shuttle download -f fluxnet_shuttle_snapshot_YYYYMMDDTHHMMSS.csv

# Download ALL sites without confirmation prompt and skip prompts to enter optional user information
fluxnet-shuttle download -f fluxnet_shuttle_snapshot_YYYYMMDDTHHMMSS.csv --quiet

• Requires a CSV snapshot file from the listall command (-f/--snapshot-file)
• Specify site IDs with -s/--sites to download specific sites only
• Omit -s/--sites to download all sites in the snapshot (will prompt for confirmation unless -q/--quiet is used)
• The -q/--quiet flag skips prompts to enter optional user information and confirmation prompt when downloading all sites from a snapshot file.
• Downloads are saved to the output directory (default: current directory, use -o to specify)

• -v/--verbose: Enable detailed logging output
• -l/--logfile: Specify log file path (default: fluxnet-shuttle-run.log)
• --no-logfile: Disable file logging, output only to console
• --version: Show version information
• --help/-h: Get help and see all options

# Step 1: Discover available data
fluxnet-shuttle --verbose listall

# Step 2: Download specific sites
fluxnet-shuttle --verbose download \
  -f fluxnet_shuttle_snapshot__20251006T155754.csv \
  -s NZ-ADd IT-Niv \

An example Jupyter notebook is available at examples/fluxnet_shuttle_example.ipynb. It demonstrates how to discover, download, and visualize FLUXNET data from multiple data hubs.

To run the notebook, first clone the repository and install with example dependencies:

git clone https://github.com/fluxnet/shuttle.git
cd shuttle
pip install -e '.[examples]'

Then launch the notebook:

jupyter notebook examples/fluxnet_shuttle_example.ipynb

The examples extras (defined in pyproject.toml) install pandas, matplotlib, jupyter, and notebook.

git clone https://github.com/fluxnet/shuttle.git
cd shuttle
pip install -e '.[dev,docs]'

pytest -m examples

### Test Coverage Report
Generate detailed test coverage report:
```bash
pytest --cov=fluxnet_shuttle --cov-report=html

Documentation is built with Sphinx and includes API documentation generated from docstrings.

To build the documentation locally:

cd docs
make html

See LICENSE for details.

This library was developed by (listed in alphabetical order):

• You-Wei Cheah - LBL
• Danielle S. Christianson - LBL
• Valerie Hendrix - LBL
• Sy-Toan Ngo - LBL
• Dario Papale - University of Tuscia
• Gilberto Pastorello - LBL
• Simone Sabbatini - Division Impacts on Agriculture, Forests and Ecosystem Services (IAFES), Fondazione Centro Euro-Mediterraneo sui Cambiamenti Climatici

For support and questions, please contact: [email protected]