The Similarity function allows the comparison of an index (e.g. NDVI) curve for one parcel with a synthetic reference curve generated from neighbouring fields. The reference curve is calculated on-the-fly by averaging all the index curves for all selected neighbouring fields. The parameters that define which parcels to select for the reference curve can be defined by the user. These are e.g. the distance from the analyzed parcel, amount of parcels to select, crop type or the entity. The function delivers similarity metrics for the compared curves, e.g. correlation coefficient and euclidian distance. This function can be used to identify parcels that exhibit an unusal (index) behaviour as compared to neighbouring parcels.
Resource associated to parcels
Resource URL: /parcels/<id>/similarity
Please see full documentation: https://docs.geocledian.com/?page_id=141
List
This function lists the time series of a reference NDVI curve and the selected parcel NDVI values. The data is temporally resampled to a given interval of days. A summary element of the applied request Parameters is given. Also a similarity indication between the two time series
HTTP Request
GET https://geocledian.com/agknow/api/v3/parcels/<parcel-id>/similarity?key=kkk&radius=sss&startdate=ddd&enddate=eee&entity=tttPath Parameters
| parcel-id | id of parcel |
| product_name | valid value: „similarity“ |
Required parameters
| key | registered user key to authorize user default: „“ |
Optional parameters
| radius | radius in meters to search for the reference parcels around the selected parcel. unit: [m]. default: 10000 |
| entity | to filter the reference parcels for a specific identifier text. All parcels will be selected, if this parameter is missing. default: „“ |
| crop | if a different crop type should be used. If parameter is missing or empty, the crop of the selected parcel will be used to search for reference parcels of same crop type. default: „“ |
| startdate | start date in ANSI format: YYYY-MM-DD or YYYMMDD, e.g. 2015-03-20 or 20150320. default = seeding date of the selected parcel |
| enddate | end date in ANSI format: YYYY-MM-DD or YYYMMDD, e.g. 2015-10-20 or 20151020. default = Harvest date of the selected parcel |
| references | Number of references parcels which are used for the reference curve calculation. default = 20, max value: 200 |
| interval | temporal interval in days default: 7 |
| smoothing | Apply smoothing to the temporal interval sampled NDVI time series. Valid values: „mav“ for moving average. default: „mav“. Others are planned. |
| classification | boolean, default: None when classification=true, pre-trained classification is called for crop type verification where the conformity (prediction) is either „False“ or „True“ for the crop type of the queried parcel. |
| season | boolean, default: None when season=true, reference vegetion index time series will be build from the previous year/season (if data is available) for comparison with the current season. |
Response Elements
| content_reference | temporally aggregated time series (according to „interval“) for the reference vegetation index time series (previous year or average time series from parcels with requested crop type through spatial search) |
| content_parcel | temporally aggregated time series for the observed parcel |
| classification | containing „conformity“ with classification decision „True“ or „False“ for crop type verification and „confidence“ with probability values for this particular decision |
| similarity | returning similarity metrics of the time series comparison „correlation“, „cosine_similarity“, „covariance“ and „distance“ as well as „references_used“ and „references_found“ |
Example
GET https://geocledian.com/agknow/api/v3/parcels/4483/similarity?key=39553fb7-7f6f-4945-9b84-a4c8745bdbecResponse
"content_reference":[
{
"date":"2017-09-02",
"product":"similarity",
"statistics":{
"max":0.0231684399768712,
"sum":265.896867340931,
"min":0.237092946190387,
"stddev":0.0452987288419449,
"mean":0.0829323331776662
}
},
{
"date":"2017-09-16",
"product":"similarity",
"statistics":{
"max":-0.0540247946977616,
"sum":-3.7404170210967,
"min":0.0548895029351116,
"stddev":0.0218295247742275,
"mean":-0.0189185017317808
}
},
{
"... next data point ..."
},
"content_parcel":[
{
"date":"2017-09-02",
"product":"similarity",
"statistics":{
"max":0.107472099363804,
"sum":93.0961346832653,
"min":-0.0432338118553162,
"stddev":0.0345041562262898,
"mean":0.0187052711840999
}
},
{
"date":"2017-09-23",
"product":"similarity",
"statistics":{
"max":0.0273207249119878,
"sum":-140.071145914742,
"min":-0.0994903072714808,
"stddev":0.0259374702264314,
"mean":-0.0281436901576736
}
},
{
"... next data point ..."
},
"summary":{
"startdate":"20190401",
"enddate":"20191231",
"crop_parcel":"115",
"interval":7,
"parcel_id":3128,
"smoothing":"mav",
"radius":10000,
"crop_reference":"115",
"references":20,
"entity":""
},
"similarity":{
"distance":0.138050370530155,
"references_found":14,
"covariance":0.0385695458426113,
"correlation":0.691553676621941,
"cosine_similarity":0.824996662567615,
"references_used":14
}
}Crop Type Verification
Performs a classification based on machine learning from pre-trained crop type verification algorithm (based on Gradient Boosting).Output is a „True“ or „False“ decision whether the crop type of the registered parcel is correct or not.
Note: for a operational crop type verification/classification in your region or country, the machine learning algorithm may be re-trained with additional labeled training data or a new model will be build complying with your requirements.Parcel data must comply with a specific semantic model (crop type codes). If your crop type is not included yet, the a new model will be created. Please contact us for more details.
Example
GET https://geocledian.com/agknow/api/v3/parcels/4483/similarity?key=39553fb7-7f6f-4945-9b84-a4c8745bdbec&radius=100000&startdate=20191001&enddate=20200501&interval=3&classification=trueResponse
"content_reference":[
{
"date":"2017-09-02",
"product":"similarity",
"statistics":{
"max":0.0231684399768712,
"sum":265.896867340931,
"min":0.237092946190387,
"stddev":0.0452987288419449,
"mean":0.0829323331776662
}
},
{
"date":"2017-09-16",
"product":"similarity",
"statistics":{
"max":-0.0540247946977616,
"sum":-3.7404170210967,
"min":0.0548895029351116,
"stddev":0.0218295247742275,
"mean":-0.0189185017317808
}
},
{
"... next data point ..."
},
"content_parcel":[
{
"date":"2017-09-02",
"product":"similarity",
"statistics":{
"max":0.107472099363804,
"sum":93.0961346832653,
"min":-0.0432338118553162,
"stddev":0.0345041562262898,
"mean":0.0187052711840999
}
},
{
"date":"2017-09-23",
"product":"similarity",
"statistics":{
"max":0.0273207249119878,
"sum":-140.071145914742,
"min":-0.0994903072714808,
"stddev":0.0259374702264314,
"mean":-0.0281436901576736
}
},
{
"... next data point ..."
},
"summary":{
"startdate":"20190401",
"enddate":"20191231",
"crop_parcel":"115",
"interval":7,
"parcel_id":3128,
"smoothing":"mav",
"radius":10000,
"crop_reference":"115",
"references":20,
"entity":""
},
"classification":{
"confidence":0.9579166038819651,
"conformity":false
},
"similarity":{
"distance":0.138050370530155,
"references_found":14,
"covariance":0.0385695458426113,
"correlation":0.691553676621941,
"cosine_similarity":0.824996662567615,
"references_used":14
}
}
Note: for a operational crop type verification/classification in your region or country, the machine learning algorithm may be re-trained with additional labeled training data or a new model will be build complying with your requirements.Parcel data must comply with a specific semantic model (crop type codes). If your crop type is not included yet, the a new model will be created. Please contact us for more details.
Remarks
- The higher the interval (in days) the higher is the generalization of the values through the temporal aggregation. Thus, the correlation values are usually increasing.
- Correlation values tend to increase with decreasing radius
- Correlation is the Pearson correlation coefficient (r)
- Distance is the averaged Euclidean Spectral Distance over all data points
- If correlation is high and spectral distance is low, the overall similarity is high
- If correlation is low and spectral distance is low, the overall similarity is low
- If correlation is high and spectral distance is high/low, the phenology of the crop is very similar, but the crop vitality is different
- seasonal similarity only works, when there is multiannual time series data for the respective parcel (comparison of current year with previos year)
- crop type verification/classification only works with a pre-trained machine learning model with a respective semantic crop type model