[FEATURE] Implement a function to export project information

[skadauke]

Feature Request Description

It would be useful to be able to programmatically pull project-wide information about a REDCap project such as its project name, PID, and whether it's longitudinal and/or has repeated instruments.

Proposed Solution

The REDCap API supports an "Export Project Information" method (content = "project"). A new function redcap_export_project_info() or similar could be implemented to query this. Here is a minimal prototype of that function that I've found works:

redcap_uri <- "https://bbmc.ouhsc.edu/redcap/api/"
token <- "0434F0E9CF53ED0587847AB6E51DE762"

post_body <- 
  list(
    token = token,
    content = "project",
    format = "csv"
  )

kernel <- REDCapR:::kernel_api(redcap_uri, post_body, config_options = NULL)

d <- readr::read_csv(I(kernel$raw_text))

[wibeasley]

@skadauke, I like that API method. I add it. A few questions come to mind. @skadauke or anyone else, please give your opinion.

1. My first instinct is to return this as a vanilla list, instead of a tibble. But I think I'm coming around to your prototype. A tibble would make it easier to combine multiple projects in the same structure, if that's ever useful.
2. I'll need to impose col_types so
   1. (empty) values that should be character aren't returned as logical (eg, project_pi_firstname)
   2. values that should be logical aren't returned as floating point (eg, in_production)
   3. external_modules should be parsed into a list/vector (eg, a two-element character vector in the example below) from its current single string.
3. Is there any reason for REDCapR to combine multiple API calls to provide more info that what's provided by this one API method? For example, include the metadata as a nested tibble and dags as another nested tibble? That's probably a rare need and not worth the time for REDCapR to test & maintain, but thought I'd ask.
4. Is there any reason for REDCapR to return the project info for multiple projects? It accepts a vector of tokens and returns a single tibble with a row for each project?

Here's the structure of d:

> str(d)
spec_tbl_df [1 × 26] (S3: spec_tbl_df/tbl_df/tbl/data.frame)
 $ project_id                         : num 212
 $ project_title                      : chr "REDCapR Target Longitudinal Arm -see https://github.com/OuhscBbmc/REDCapR"
 $ creation_time                      : POSIXct[1:1], format: "2014-08-31 13:07:55"
 $ production_time                    : logi NA
 $ in_production                      : num 0
 $ project_language                   : chr "English"
 $ purpose                            : num 0
 $ purpose_other                      : logi NA
 $ project_notes                      : logi NA
 $ custom_record_label                : logi NA
 $ secondary_unique_field             : logi NA
 $ is_longitudinal                    : num 1
 $ has_repeating_instruments_or_events: num 0
 $ surveys_enabled                    : num 0
 $ scheduling_enabled                 : num 0
 $ record_autonumbering_enabled       : num 0
 $ randomization_enabled              : num 0
 $ ddp_enabled                        : num 0
 $ project_irb_number                 : logi NA
 $ project_grant_number               : logi NA
 $ project_pi_firstname               : logi NA
 $ project_pi_lastname                : logi NA
 $ display_today_now_button           : num 1
 $ missing_data_codes                 : logi NA
 $ external_modules                   : chr "cross_project_piping,date_validation_action_tags"
 $ bypass_branching_erase_field_prompt: num 0

[skadauke]

1. My first instinct is to return this as a vanilla list, instead of a tibble. But I think I'm coming around to your prototype. A tibble would make it easier to combine multiple projects in the same structure, if that's ever useful.

I like tibbles so agree with you.

2. I'll need to impose col_types so

   1. (empty) values that should be character aren't returned as logical (eg, project_pi_firstname)
   2. values that should be logical aren't returned as floating point (eg, in_production)
   3. external_modules should be parsed into a list/vector (eg, a two-element character vector in the example below) from its current single string.

Fully agree.

3. Is there any reason for REDCapR to combine multiple API calls to provide more info that what's provided by this one API method? For example, include the metadata as a nested tibble and dags as another nested tibble? That's probably a rare need and not worth the time for REDCapR to test & maintain, but thought I'd ask.

I think there's a use case for this, and we're planning to build a function that does that into REDCapTidieR.

4. Is there any reason for REDCapR to return the project info for multiple projects? It accepts a vector of tokens and returns a single tibble with a row for each project?

I think there's a rare use case for this where you build a dashboard to manage multiple projects. Not sure it's worth the time needed to test and maintain as REDCapR core functionality.

[wibeasley]

@skadauke, I think the version (about to be pulled to main) satisfies everything discussed above...

External Module

...except for transforming the scalar external_modules into something like a list. I was playing around with ideas & documentation, and didn't find something that I thought would be helpful to all cases. So I'll leave it alone, but add a section in the documentation how the user might transform it. Please add to that documentation if you have improvements.

Future columns

Please review how I handle future columns (that aren't yet returned by REDCap's API, but will be). Will that work for REDCapTidieR?

Stacking multiple projects

I ended up including a snippet that stacks multiple projects in one tibble. I did it anyway for testing (to make it easy to cover as many scenarios as possible), so I included it in the examples.

[skadauke]

Re: future columns - do we have reason to believe the REDCap API will return additional columns in the result?

[skadauke]

I just looked at the code - can you double check the col_types vector defined in redcap-project-info-read.R? I think you picked col_logical() in some places that should be col_character() or col_integer()?

[wibeasley]

Re: future columns - do we have reason to believe the REDCap API will return additional columns in the result?

I bet some of the new features they'll keep releasing will be reflected. For instance, has_repeating_instruments_or_events and external_modules wouldn't have existed until a few years ago. Hopefully this package exists for another 8 years.

I think you picked col_logical() in some places...

ahh, you're right. I missed a few.