Organization of PlantCV Outputs

During parallel processing, outputs from PlantCV analysis functions are collected into a hierarchical JSON output file. The JSON file is used to collect image metadata and PlantCV output observations for the entire image set. The hierarchical data structure is more flexible than the previous tabular structure: entities (typically individual images) do not need to have a rigid set of observations, and users can easily record custom observations without the need to update a database schema.

Data Structure

The JSON output file has two top-level sections: variables is a collection of all observation names found in the dataset, and entities is a list of data blocks for each unit of analysis (typically an image, or a sub-region of an image) in the dataset. For each entity there are two data blocks: metadata is a set of key-value pairs of metadata keywords and their values (e.g. image or experimental metadata such as timestamp, treatment, etc.), and observations is a set of data blocks of observational data or measurements. Observations contain samples. Each sample has the same set of information, roughly following the MIAPPE guidelines: trait is the name of the observation, method is generally the PlantCV function name used (but it could be another method), scale is the observation units, datatype is the Python data type the data are stored as, value is the observation output value(s), and label is the data/category label.

Example (abbreviated) JSON data:

{
    "variables": {
        "camera": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "imgtype": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "timestamp": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "plantbarcode": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "treatment": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "image": {
            "category": "metadata",
            "datatype": "<class 'str'>"
        },
        "area": {
            "category": "observations",
            "datatype": "<class 'int'>"
        },
        "convex_hull_area": {
            "category": "observations",
            "datatype": "<class 'list'>"
        }
    },
    "entities": [
        {
            "metadata": {
                "camera": {
                    "label": "camera identifier",
                    "datatype": "<class 'str'>",
                    "value": "SV"
                },
                "imgtype": {
                    "label": "image type",
                    "datatype": "<class 'str'>",
                    "value": "VIS"
                },
                "timestamp": {
                    "label": "datetime of image",
                    "datatype": "<class 'datetime.datetime'>",
                    "value": "2014-10-22 17:59:23.046"
                },
                "plantbarcode": {
                    "label": "plant barcode identifier",
                    "datatype": "<class 'str'>",
                    "value": "Ca002AA010557"
                },
                "treatment": {
                    "label": "treatment identifier",
                    "datatype": "<class 'str'>",
                    "value": "none"
                },
                "image": {
                    "label": "image file",
                    "datatype": "<class 'str'>",
                    "value": "./images/snapshot57393/VIS_SV_0_z1_h1_g0_e65_117881.png"
                }
            },
            "observations": {
                "sample1": {
                    "pixel_area": {
                        "trait": "area",
                        "method": "plantcv.plantcv.analyze.size",
                        "scale": "pixels",
                        "datatype": "<class 'int'>",
                        "value": 10000,
                        "label": "pixels"
                    },
                    "hull_area": {
                        "trait": "convex hull area",
                        "method": "plantcv.plantcv.analyze.size",
                        "scale": "pixels",
                        "datatype": "<class 'int'>",
                        "value": 100000,
                        "label": "pixels"
                    }
                }
            }
        }
    ]
}

Data in this structure can be converted to tables for downstream analysis using the provided script plantcv-utils json2csv, see Accessory Tools for more details.

Summary of Output Metadata

Below is a list of currently tracked metadata types in PlantCV. None of these are strictly required. If you have suggestions for additional metadata we should track that would be useful to you, please submit an issue or contact us. Ideally, we will be able to handle the full MIAPPE specification at some point.

Name Description
plantbarcode plant (specimin) identifier, name, or code
timestamp date and time the image was acquired
treatment treatment name or ID
camera camera name or ID
imgtype type of image (e.g. RGB, VIS, NIR, etc.)
zoom camera optical or digital zoom setting
exposure camera exposure setting
gain camera gain setting
frame frame name or ID in a multi-frame series
lifter position if a variable height lifting system was used
id image ID or other arbitrary ID
cartag carrier or pot ID
measurementlabel experiment name or ID
other other information

Output Observations

Functions that automatically store data to the Outputs class are analyze.bound_horizontal, analyze.bound_vertical, analyze.color, analyze.grayscale, analyze.size, analyze.spectral_index, analyze.spectral_reflectance, analyze.thermal, analyze.yii, analyze.npq, homology.acute, homology.landmark_reference_pt_dist, homology.x_axis_pseudolandmarks, homology.y_axis_pseudolandmarks, morphology.analyze_stem, morphology.check_cycles, morphology.fill_segments, morphology.find_tips, morphology.find_branch_pts, morphology.segment_angle, morphology.segment_curvature, morphology.segment_euclidean_length, morphology.segment_insertion_angle, morphology.segment_path_length, morphology.segment_tangent_angle, report_size_marker_area, transform.find_color_card, transform.detect_color_card watershed_segmentation, and within_frame.

All of these functions include an optional label parameter that allows users to append custom prefixes to the unique variable identifier.

For more detail about the traits measured by each function see the Observation Traits Summary Table.