neonutilities.by_tile_aop

neonutilities.by_tile_aop(dpid, site, year, easting, northing, buffer=0, include_provisional=False, check_size=True, savepath=None, chunk_size=1024, token=None, verbose=False, skip_if_exists=False, overwrite='prompt')

This function queries the NEON API for AOP data by site, year, product, and UTM coordinates, and downloads all files found, preserving the original folder structure. It downloads files serially to avoid API rate-limit overload, which may take a long time.

Parameters

dpid: str

The identifier of the NEON data product to pull, in the form DPL.PRNUM.REV, e.g. DP3.30001.001.

site: str

The four-letter code of a single NEON site, e.g. ‘CLBJ’.

year: str or int

The four-digit year of data collection.

easting: float/int or list of float/int

A number or list containing the easting UTM coordinate(s) of the locations to download.

northing: float/int or list of float/int

A number or list containing the northing UTM coordinate(s) of the locations to download.

buffer: float/int, optional

Size, in meters, of the buffer to be included around the coordinates when determining which tiles to download. Defaults to 0.

include_provisional: bool, optional

Should provisional data be downloaded? Defaults to False. See https://www.neonscience.org/data-samples/data-management/data-revisions-releases for details on the difference between provisional and released data.

check_size: bool, optional

Should the user approve the total file size before downloading? Defaults to True. If you have sufficient storage space on your local drive, when working in batch mode, or other non-interactive workflow, use check_size=False.

savepath: str, optional

The file path to download to. Defaults to None, in which case the working directory is used. Files are downloaded to subdirectories starting with the dpid under the savepath.

chunk_size: int, optional

Size in bytes of chunk for chunked download. Defaults to 1024.

token: str, optional

User-specific API token from data.neonscience.org user account. Defaults to None. See https://data.neonscience.org/data-api/rate-limiting/ for details about API rate limits and user tokens.

verbose: bool, optional

If set to True, the function will print out a list of the tiles to be downloaded before downloading. Defaults to False.

skip_if_exists: bool, optional

If set to True, the function will skip downloading files that already exist in the savepath and are valid (local checksums match the checksums of the published file). Defaults to False. If any local file checksums don’t match those of files published on the NEON Data Portal, the user will be prompted to skip these files or overwrite the existing files with the new ones (see overwrite input).

overwrite: str, optional

Must be one of:

‘yes’ - overwrite mismatched files without prompting, ‘no’ - don’t overwrite mismatched files (skip them, no prompt), ‘prompt’ - prompt the user (y/n) to overwrite mismatched files after displaying them (default).

If skip_if_exists is False, this parameter is ignored, and any existing files in the savepath will be overwritten according to the function’s default behavior.

Returns

None; data are downloaded to the directory specified (savepath) or the current working directory. If data already exist in the expected path, they will be overwritten by default. To check for existing files before downloading, set skip_if_exists=True along with an overwrite option (y/n/prompt).

Example

>>> by_tile_aop(dpid="DP3.30015.001",
                site="MCRA",
                easting=[566456, 566639],
                northing=[4900783, 4901094],
                year="2021",
                savepath="./test_download",
                skip_if_exists=True)
# This downloads any tiles overlapping the specified UTM coordinates for
# 2021 canopy height model data from McRae Creek to the './test_download' directory.
# If any files already exist in the savepath, they will be checked and skipped if they are valid.
# The user will be prompted to ovewrite or skip downloading any existing files that do not match
# the latest published data on the NEON Data Portal.

Notes

This function creates a folder named by the Data Product ID (DPID; e.g. DP3.30015.001) in the ‘savepath’ directory, containing all AOP files meeting the query criteria. If ‘savepath’ is not provided, data are downloaded to the working directory, in a folder named by the DPID.