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. Each observation 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": {
"pixel_area": {
"trait": "area",
"method": "plantcv.plantcv.analyze_object",
"scale": "pixels",
"datatype": "<class 'int'>",
"value": 10000,
"label": "pixels"
},
"hull_area": {
"trait": "convex hull area",
"method": "plantcv.plantcv.analyze_object",
"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.py 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 |
Summary of Output Observations¶
Variable | Trait | Method | Scale | Data Type | Description |
---|---|---|---|---|---|
tip_coordinates | tip coordinates | acute_vertex | none | list | list of positions (PATO:0000140) of tip points |
red_frequencies | red frequencies | analyze_color | frequency | list | red (PATO:0000322) intensity frequency distribution (values of 0-255 in RGB colorspace) |
green_frequencies | green frequencies | analyze_color | frequency | list | green (PATO:0000320) intensity frequency distribution (values of 0-255 in RGB colorspace) |
blue_frequencies | blue frequencies | analyze_color | frequency | list | blue (PATO:0000318) intensity frequency distribution (values of 0-255 in RGB colorspace) |
lightness_frequencies | lightness frequencies | analyze_color | frequency | list | lightness (PATO:0000016) frequency distribution (values of 0-100% in LAB colorspace) |
green-magenta_frequencies | green-magenta frequencies | analyze_color | frequency | list | green-magenta component frequency distribution (values of -127 to 128 in LAB colorspace) |
blue-yellow_frequencies | blue-yellow frequencies | analyze_color | frequency | list | blue-yellow component frequency distribution (values of -127 to 128 in LAB colorspace) |
hue_frequencies | hue frequencies | analyze_color | frequency | list | hue (PATO:0000015) frequency distribution (values of 0-359 degrees in HSV colorspace) |
saturation_frequencies | saturation frequencies | analyze_color | frequency | list | saturation (PATO:0000017) frequency distribution (values of 0-100% in HSV colorspace) |
value_frequencies | value frequencies | analyze_color | frequency | list | value (PATO:0000016) frequency distribution (values of 0-100% in HSV colorspace) |
hue_circular_mean | hue circular mean | analyze_color | degrees | float | circular mean of hue values |
hue_circular_std | hue circular standard deviation | analyze_color | degrees | float | circular standard deviation of hue values |
hue_median | hue median | analyze_color | degrees | float | median (NCIT:C28007) of hue values |
horizontal_reference_position | horizontal reference position | analyze_bound_horizontal | none | int | position (PATO:0000140) of horizontal reference point |
height_above_reference | height above reference | analyze_bound_horizontal | pixels | int | height (PATO:0000119) of object above reference position |
height_below_reference | height below reference | analyze_bound_horizontal | pixels | int | height (PATO:0000119) of object below reference position |
area_above_reference | area above reference | analyze_bound_horizontal | pixels | int | area (PATO:0001323) of object above reference position |
area_below_reference | area below reference | analyze_bound_horizontal | pixels | int | area (PATO:0001323) of object below reference position |
percent_area_above_reference | percent area above reference | analyze_bound_horizontal | percent | float | proportion (PATO:0001470) of object area above reference position |
percent_area_below_reference | percent area below reference | analyze_bound_horizontal | percent | float | proportion (PATO:0001470) of object area below reference position |
vertical_reference_position | vertical reference position | analyze_bound_vertical | none | int | position (PATO:0000140) of vertical reference point |
width_left_reference | width left of reference | analyze_bound_vertical | pixels | int | width (PATO:0000921) of object left of reference position |
width_right_reference | height below of reference | analyze_bound_vertical | pixels | int | width (PATO:0000921) of object right of reference position |
area_left_reference | area left of reference | analyze_bound_vertical | pixels | int | area (PATO:0001323) of object left of reference position |
area_right_reference | area right of reference | analyze_bound_vertical | pixels | int | area (PATO:0001323) of object right of reference position |
percent_area_left_reference | percent area left of reference | analyze_bound_vertical | percent | float | proportion (PATO:0001470) of object area left of reference position |
percent_area_right_reference | percent area right of reference | analyze_bound_vertical | percent | float | proportion (PATO:0001470) of object area right of reference position |
nir_frequencies | near-infrared frequencies | analyze_nir_intensity | frequency | list | near-infrared intensity frequency distribution (values in 8- or 16-bit sensor detection range) |
area | area | analyze_object | pixels | int | area (PATO:0001323) of object |
convex_hull_area | convex hull area | analyze_object | pixels | int | area (PATO:0001323) of convex hull |
solidity | solidity | analyze_object | none | float | ratio (PATO:0001470): area / convex hull area |
perimeter | perimeter | analyze_object | pixels | int | perimeter (PATO:0001711) around object |
width | width | analyze_object | pixels | int | width (PATO:0000921) of object |
height | height | analyze_object | pixels | int | height (PATO:0000119) of object |
longest_path | longest path | analyze_object | pixels | int | length (PATO:0000122) of longest path between convex hull vertices through the center of mass |
center_of_mass | center of mass | analyze_object | none | tuple | position (PATO:0000140) of center of mass |
convex_hull_vertices | convex hull vertices | analyze_object | none | int | number (PATO:0001555) of convex hull vertices |
object_in_frame | object in frame | analyze_object | none | bool | true of false (false if the object is touching the border of the image) |
ellipse_center | ellipse center | analyze_object | none | tuple | position (PATO:0000140) of the center of the minimum bounding ellipse |
ellipse_major_axis | ellipse major axis length | analyze_object | pixels | int | length (PATO:0000122) of the major axis of the minimum bounding ellipse |
ellipse_minor_axis | ellipse minor axis length | analyze_object | pixels | int | length (PATO:0000122) of the minor axis of the minimum bounding ellipse |
ellipse_angle | ellipse major axis angle | analyze_object | degrees | float | angle (PATO:0002326) of rotation of the bounding ellipse major axis |
ellipse_eccentricity | ellipse eccentricity | analyze_object | none | float | eccentricity of the bounding ellipse |
fvfm_hist | Fv/Fm frequencies | fluor_fvfm | none | list | Fv/Fm frequency distribution |
fvfm_hist_peak | peak Fv/Fm value | fluor_fvfm | none | float | peak Fv/Fm value |
fvfm_median | Fv/Fm median | fluor_fvfm | none | float | median (NCIT:C28007) Fv/Fm value |
fdark_passed_qc | Fdark passed QC | fluor_fvfm | none | bool | true of false (false if the Fdark image has values > 2000) |
vert_ave_c | average vertical distance from centroid | landmark_reference_pt_dist | pixels | float | average vertical distance from centroid |
hori_ave_c | average horizontal distance from centeroid | landmark_reference_pt_dist | pixels | float | average horizontal distance from centeroid |
euc_ave_c | average euclidean distance from centroid | landmark_reference_pt_dist | pixels | float | average euclidean distance from centroid |
ang_ave_c | average angle between landmark point and centroid | landmark_reference_pt_dist | degrees | float | average angle between landmark point and centroid |
vert_ave_b | average vertical distance from baseline | landmark_reference_pt_dist | pixels | float | average vertical distance from baseline |
hori_ave_b | average horizontal distance from baseline | landmark_reference_pt_dist | pixels | float | average horizontal distance from baseline |
euc_ave_b | average euclidean distance from baseline | landmark_reference_pt_dist | pixels | float | average euclidean distance from baseline |
ang_ave_b | average angle between landmark point and baseline | landmark_reference_pt_dist | degrees | float | average angle between landmark point and baseline |
num_cycles | number of cycles | morphology.check_cycles | none | int | number (PATO:0001555) of closed loops (cycles) in a skeletonized object |
segment_angle | segment angle | morphology.segment_angle | degrees | list | list of angles (PATO:0002326) of segment paths found by fitting a linear regression line to each segment |
segment_curvature | segment curvature | morphology.segment_curvature | none | list | list of curvatures (the ratio between geodesic and euclidean distance) of segment paths |
segment_eu_length | segment euclidean length | morphology.segment_euclidean_length | pixels | list | list of Euclidean Distance Measurements (NCIT:C65170) between segment endpoints |
segment_insertion_angle | segment insertion angle | morphology.segment_insertion_angle | degrees | list | list of angles (PATO:0002326) between "leaf" and "stem" segments |
segment_path_length | segment path length | morphology.segment_path_length | pixels | list | list of lengths (PATO:0000122) along each segment path |
segment_tangent_angle | segment tangent angle | morphology.segment_tangent_angle | degrees | list | list of angles (PATO:0002326) between the tangents to the ends of each segment |
marker_area | marker area | report_size_marker_area | pixels | int | area (PATO:0001323) of a size marker object |
marker_ellipse_major_axis | marker ellipse major axis length | report_size_marker_area | pixels | int | length (PATO:0000122) of the major axis of the minimum bounding ellipse of a size marker |
marker_ellipse_minor_axis | marker ellipse minor axis length | report_size_marker_area | pixels | int | length (PATO:0000122) of the minor axis of the minimum bounding ellipse of a size marker |
marker_ellipse_eccentricity | marker ellipse eccentricity | report_size_marker_area | none | float | eccentricity of the bounding ellipse of a size marker |
estimated_object_count | estimated object count | watershed_segmentation | none | int | number (PATO:0001555) of segmented objects (e.g. leaves) |
top_lmk | top landmark coordinates | x_axis_pseudolandmarks | none | list | list of landmark points within 'top' portion |
bottom_lmk | bottom landmark coordinates | x_axis_pseudolandmarks | none | list | list of landmark points within 'bottom' portion |
center_v_lmk | center vertical landmark coordinates | x_axis_pseudolandmarks | none | list | list of landmark points within 'center-vertical' portion |
left_lmk | left landmark coordinates | y_axis_pseudolandmarks | none | list | list of landmark points within 'left' portion |
right_lmk | right landmark coordinates | y_axis_pseudolandmarks | none | list | list of landmark points within 'right' portion |
center_h_lmk | center horizontal landmark coordinates | y_axis_pseudolandmarks | none | list | list of landmark points within 'center-horizontal' portion |