Usage — vegindex 0.3.0rc1 documentation

# Usage

## Command Line Scripts

After installing the `vegindex` package, two python command line scripts will be installed:

- `generate_roi_timeseries`
- `generate_summary_timeseries`

The first script generates summary statistics for a Region of Interest (ROI) for each image which passes certain basic selection criteria and writes the results to a CSV file. The second script reads in this file and then calculates either 1-day or 3-day summary statistics for the images in this time period. For each time period a single line in the CSV file is produced.

## Setting up the Data Directory

The vegindex package is designed to work with images downloaded from the PhenoCam network server. To download images you can go to the data tab at the project website.

The images you select come in a zip file with a specific directory structure. For example if we download data from the `harvard` site.

    harvard
    ├── 2009
    │   ├── 01
    │   │   ├── harvard_2009_01_01_110135.jpg
    │   │   ├── harvard_2009_01_01_113135.jpg
    │   │   ├── harvard_2009_01_01_120135.jpg
     .
     .
     .

    │   └── 06
    │       ├── harvard_2009_06_01_110139.jpg
    │       ├── harvard_2009_06_01_113139.jpg
    │       ├── harvard_2009_06_01_120139.jpg
    │       └── harvard_2009_06_01_123139.jpg
    ├── harvard_meta.json
    └── harvard_meta.txt

where the we have a top level directory for `sitename` then subdirectories for four-digit year and two-digit month, with the image files in the month directories.

## ROI Lists and Masks

Once you’ve selected and downloaded the data you would like to process you will need to set up a region of interest (ROI) using an `ROI List` file and the associated `ROI Mask` images.

The `ROI List` file is a simple text file with a list of `ROI mask` images and the dates for which the masks are valid. The `ROI List` format description can be found on this page Here’s a simple example where there is only one mask file:

    #
    # ROI List for harvard
    #
    # Site: harvard
    # Veg Type: DB
    # ROI ID Number: 0001
    # Owner: tmilliman
    # Creation Date: 2012-07-12
    # Creation Time: 11:42:00
    # Update Date: 2014-12-17
    # Update Time: 13:55:25
    # Description: Deciduous trees in foreground
    #
    start_date,start_time,end_date,end_time,maskfile,sample_image
    2008-04-04,00:00:00,9999-01-01,00:00:00,harvard_DB_0001_01.tif,harvard_2008_04_30_133137.jpg

If there are field-of-view shifts you may need additional lines in the list and more mask images. The list file and the mask images need to be placed in a directory named `ROI` under the site name i.e.:

    harvard
    └── ROI
        ├── harvard_DB_0001_01.tif
        └── harvard_DB_0001_roi.csv

This file naming convention must also be followed. So the `ROI List` has the form:

    <sitename>_<ROI-type>_<ROI-sequence-no>_roi.csv

and the associated masks are named according to the convention:

    <sitename>_<ROI-type>_<ROI-sequence-no>_<mask_index>.tif

where the “<mask_index>” in the form `nn` is the number in the list of the mask file starting with 01 (e.g. 01, 02, 03, etc.). For the timeseries displayed on the PhenoCam Network website. The `ROI List` files and the `ROI Mask` images are available for download from one of the `ROI Pages` on our site e.g. ROI page for harvard DB_0001

## Generating the ROI Image Statistics file

The `generate_roi_timeseries` script reads in the `ROI List` file and `ROI Mask` images. Then for each image found within the timeperiods in the `ROI List` it calculates image statistics over the ROI. You can get help for

    $ generate_roi_timeseries -h
    usage: generate_roi_timeseries [-h] [-v] [-n] site roiname

    positional arguments:
    site           PhenoCam site name
    roiname        ROI name, e.g. DB_0001

    optional arguments:
    -h, --help     show this help message and exit
    -v, --verbose  increase output verbosity
    -n, --dry-run  Process data but don't save results

The script needs to know where the site images are located. By default it assumes that the site level image directory is at:

    /data/archive/<sitename>

If the images downloaded are in another location, for example `/mydata/directory/harvard`, you can set an an environment variable to specify the path to the images:

    export PHENOCAM_ARCHIVE_DIR=/mydata/directory/

or

    set PHENOCAM_ARCHIVE_DIR=/mydata/directory/

Here’s an example command line session:

    $ export PHENOCAM_ARCHIVE_DIR=~/Downloads/phenocamdata/
    $ generate_roi_timeseries harvard DB_0001
    Images processed: 594
    Images added to CSV: 594
    Total: 594

The output format for the “All Image” file can be found here

## Generating the 1-day and 3-day Summary Files

The `generate_summary_timeseries` script reads in the “All-Image” file and calculates summary statistics for the 1-day or 3-day period:

    $ generate_summary_timeseries -h
    usage: generate_summary_timeseries [-h] [-v] [-n] [-p [{1,3}]] site roiname

    positional arguments:
    site                  PhenoCam site name
    roiname               ROI name, e.g. canopy_0001

    optional arguments:
    -h, --help            show this help message and exit
    -v, --verbose         increase output verbosity
    -n, --dry-run         Process data but don't save results
    -p [{1,3}], --aggregation-period [{1,3}]
                          Number of Days to Aggregate (default=1)

To generate the 3-day summary file from the “All Image” file generated in the previous section:

    $ generate_summary_timeseries -p 3 harvard DB_0001
    Total: 51

A description of the summary files can be found on the project website.

## API

TBD