FLUXNET Shuttle Library Documentation

Welcome to FLUXNET Shuttle Library’s documentation!

FLUXNET Shuttle Library is a Python library for discovering and downloading global FLUXNET data from data hubs including AmeriFlux, ICOS, and TERN.

The data hubs provide FLUXNET data organized and coordinated by many regional networks, including AmeriFlux, AsiaFlux, ChinaFlux, JapanFlux, KoFlux, ICOS, European Flux database, OzFlux, TERN, and SAEON.

Features

  • Data Download: Download FLUXNET data from AmeriFlux, ICOS, and TERN 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

Data Use Requirements

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

Installation

From PyPI:

Coming soon!

From GitHub using pip:

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

For Development:

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

Supported python versions: 3.11, 3.12, 3.13 (3.9, 3.10 may work but are not officially supported; <3.9 not allowed.)

Quick Start

Programmatic Usage:

from fluxnet_shuttle import download, listall

# Discover available data
csv_filename = listall()
print(f"Available data saved to: {csv_filename}")

# Download specific sites
sites = ['NZ-ADd', 'IT-Niv']
downloaded_files = download(site_ids=sites, snapshot_file=csv_filename)

# Download specific sites with optional user information
# Intended Use options: 1. Synthesis, 2. Model, 3. Remote sensing, 4. Other research, 5. Education, 6. Other
sites = ['NZ-ADd', 'IT-Niv']
user_info={'ameriflux': {'user_name': 'O2. Carbon', 'user_email': 'o2.carbon@flux.flux', 'intended_use': 1, 'description': 'Analysis of water flux'}}
downloaded_files = download(site_ids=sites, snapshot_file=csv_filename, user_info=user_info)

For advanced usage with error handling and the developer API, see Core API Usage.

Command Line Usage:

# List all available datasets (creates snapshot file)
fluxnet-shuttle listall

# Download data for specific sites using snapshot file
fluxnet-shuttle download -f fluxnet_shuttle_snapshot_YYYYMMDDTHHMMSS.csv -s KE-Kpt KR-TwB AU-Lox

# Create output directory
mkdir /data/fluxnet
fluxnet-shuttle download -f fluxnet_shuttle_snapshot_YYYYMMDDTHHMMSS.csv -s NZ-ADd IT-Niv -o /data/fluxnet

For complete CLI documentation, see Command Line Interface.

Documentation

Contents:

Indices and tables