Proposal of call for trial stat results (from @j-alberto, June 2017)

[BrapiCoordinatorSelby]

This was originally in pull request #74 started in June 2017. This pull request is now wildly out of date and needs to be closed. However, the idea and comments are still relevant, perhaps more relevant now that BrAPI has reached a new level of maturity.

[BrapiCoordinatorSelby]

File Changes

## Get statistical results by trial [/brapi/v2/trials/{id}/statisticalobservations]
Scope: PHENOTYPING, ANALYSIS.
This call is meant to get statistical results based on raw observations, eg. Meta-R. The proposal is included at trial level for multilocaltion analysis results. CIMMYT's IWIS currently supports this information.

Notes: A similar call at study level may be considered for single-site analysis

### Retrieve statistical results by trial's entrys [GET]

+ Parameters
    + trialDbId (required, integer, `T2233`) ... Identifier of the trial. Usually a number, could be alphanumeric.

+ Response 200 (application/json)

        {
            "metadata": {
                "pagination": {
                    "pageSize": 100,
                    "currentPage": 0,
                    "totalCount": 480,
                    "totalPages": 5
                },
                "status": [],
                "datafiles": []
            },
            "result": {
                "data": [
                    {
                        "germplasmDbId": "1",
                        "entryNumber": "1",
                        "studyDbId",
                        "observations": [
                            {
                                "observationDbId": 153453453,
                                "observationVariableId": 18020,
                                "value": 10.0101
                            },
                            {
                                "observationDbId": 23453454345,
                                "observationVariableId": 51496,
                                "value": 11.2021
                            }
                        ]
                    }
                ]
            }
        }

[BrapiCoordinatorSelby]

@j-alberto commented on Jun 15, 2017 this call should be put into Trial's scope.

[BrapiCoordinatorSelby]

@jeback1 commented on Jun 22, 2017 Hi Jorge, A couple of questions about your proposed call:

1. You have a StudyDbID key in the results with no value. What is this key meant for?

2. The 'value' key; how does one know whether it is an average, median, or some other statisitc?

   Best regards, Jan Erik

[BrapiCoordinatorSelby]

@j-alberto commented on Jun 27, 2017 Hello Jan Erik,

1. StudyDbId with no value: is was a typing error, it should contain the study identifier to associate the results with. Since the results cannot be attached to a single plot, but to all plots with the same germplasm for a given study. This proposal only considers single-site analysis, so for multi-site analysis it may require also trialDbId.

2. To tell between average, std deviation, etc. We propose using observationVariableId, defining new variables with the same property(trait), and scale of the ones used for raw data , but using different methods: "statistical average", "statistical std deviation", etc. This way we can ask for either raw or statistical observations by specifying the variables we want. They will still be attached to the same trait and germplasm.

[BrapiCoordinatorSelby]

@j-alberto commented on Jun 27, 2017 For a better support of single and multi study analysis results some changes need to be considered.

1. To distinguish between single(study) and multi (trial) location analysis, it would be necessary to create a superset of levels in this call: /brapi/v1/observationLevels like : plant, plot, study entry, trial entry and germplasm.
2. Statistical observations need its own observation units with observationLevel=studyEntry|trialEntry. One new problem comes out here: currently there is no way to retrieve a list of germplasm at Trial Level, only at Study Level. Probably a new call for trials is needed, similar to /brapi/v1/studies/{studyDbId}/germplasm
3. The observation object can map to entries with the existing property entryNumber; plotNumber and plantNumber would be empty.

All of this is a preliminary approach which needs to be discussed, of course.