Add option to retrieve 'unchecked' data from BETYdb

[dlebauer]

As of BETYdb v 4.4, users are able to access 'unchecked' data.

The ability to query unchecked data from the Web interface and API was implemented in PecanProject/bety#350 and is defined in the section 3.3.1 of the "Data Access" documentation.

This feature will add an new argument include_unchecked to the betydb_* family of functions. When 'true', it should append include_unchecked=true to the API call.

---

notes In practice, these data are actively used in research although they have not gone through the QA/QC step of having a researcher or technician independently compare data to their original source. Unchecked data are routinely exported across the distributed network of BETYdb instances, and are used in analyses within the PEcAn project, and are identified as 'unchecked' by the 'checked' field in the traits table having a value of '0' ('-1' indicated failed and '1' indicates checked). The difference between checked = 0 and checked = 1 is that data are given a value of '0' upon entry and '1' after independent review.

[sckott]

@dlebauer Sounds good

[infotroph]

This now works in betydb_query as of c957ca8, but it should be mentioned in the vignette.

TODO:

• document which tables use it (just search, traits, & yields?).
• Document accepted values (1, "TRUE", "YES", "y", etc).
• Make connection to limit and offset1, the other options that alter result visibility
• (?) Add include_unchecked as a betydb_search parameter (null by default) to aid discoverability

[dlebauer]

• yes just search, traits, yields
• accepted should be 0,1 on traits & yields; unchecked or passing (I'm pretty sure these are the exact strings) on search (values -1 and failed should not be returned)
• sounds reasonable
• yes great idea

[infotroph]

@sckott Sorry, can you reopen this? Apparently include_unchecked works differently or not at all in the beta API. If this isn't a bug in BETY, the traits documentation should be updated to reflect reality and a test should be added for the correct behavior.

[dlebauer]

@infotroph the design specifications for the BETYdb beta API were to map closely to the database schema itself, without putting too much magic in the API itself.

There is a 'bug' that only checked data are available to the public. That will be fixed in the API, then both checked and unchecked data will be returned by default.

For the traits package, I think that the simplest method would be to add the following in the first line of betydb_GET

if(!exists(include_unchecked){ ## if not specified, return only checked
   args <- append(args, checked=1)
} else {
   if(!include_unchecked) { ## if include_unchecked == false return only checked
      args <- append(args, checked=1)
   }
} # else accept default of both checked + unchecked

[maelle]

This repository is about to be archived.