You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Each REDCap method accepts a number of parameters that follow a shared naming convention.
26
-
REDCap.jl is designed to closely follow the design and syntax patterns of REDCap.
27
-
Every REDCap API method is available as a function that supplies certain required parameters and checks user inputs for validity.
28
-
29
-
Return values and REDCap messages are returned as Strings directly, but the documentation shows how these can be parsed in useful ways.
30
-
31
-
Function arguments are named after REDCap method parameters.
32
-
These are passed as named arguments and take values with intuitive types.
33
-
34
-
### `token` and `url`
35
-
Nearly all REDCap methods accept a token that is unique to the project and user.
36
-
37
-
The URL must exactly match this example:
38
-
```https://example.example/redcap/api/```
39
-
40
-
Your REDCap token and your institution's REDCap API URL can be read by default from Julia's environment variables.
41
-
You can make them avaiable to REDCap.jl by putting the following lines in [your local Julia startup file](https://docs.julialang.org/en/v1/manual/command-line-interface/#Startup-file) (probably `~/.julia/config/startup.jl`):
String values are accepted. If the string is a file name, the contents of the file are sent; otherwise, the value is sent directly as part of the API request.
out =open("data_file.json","w"); write(out, data_string); close(out)
85
-
86
-
import_DAGs(token=t,data=data_string, format=:json) # string is passed to the API
87
-
88
-
import_DAGs(token=t, data="data_file.json", format=:json) # string is pattern-matched as a filename
89
-
90
-
```
91
-
As for collections, only collections of scalar entries are currently supported.
92
-
So, a list of attributes and values is accepted, but a Dict containing multiple rows per column can only be read in from a file.
93
-
94
-
In the REDCap API, the presence of a `data` parameter often changes the behavior of a method.
95
-
For instance, most import methods are implemented as an export method with an added data parameter.
96
-
In REDCap.jl, it would be considered a bug for `import_project_data` to ever act as `export_project_data`, so the data paramater is almost always required where it is present.
97
-
98
-
### `format` and `returnFormat`
99
-
Supported options are `:csv`, `:json`, `:xml` (the default value), and sometimes `:odm`.
100
-
These values can be passed as Strings or Symbols.
101
-
102
-
Generally, the `format` parameter designates user input and the `returnFormat` parameter applies to REDCap messages and return values.
103
-
However, this is not consistent within REDCap.
104
-
REDCap.jl functions are designed to not accept any parameters that have no effect on the result.
105
-
106
-
### `content` and `action`
107
-
The `content` and `action` parameters are what define each REDCap method, for the most part.
108
-
In REDCap.jl, these are passed internally and don't need to be supplied by the user.
109
-
Instead, they're fixed for each function.
110
-
111
-
## Troubleshooting
112
-
If a function call doesn't produce the expected results, try making debug messages visible for this package by running `ENV["JULIA_DEBUG"] = REDCap`.
113
-
The data parameter is converted to a formatted string, so you might try different format parameters (`:csv`, `:json`, or `:xml`).
114
-
Feel free to create an issue for any unexpected errors, or for feature requests.
25
+
For more details, see the internal documentation (`help?> REDCap`).
115
26
116
27
## Acknowledgments
117
28
The contributors are grateful for the support of Mary McGrath, Paul Stey, Fernando Gelin, the Brown Data Science Institute, the Brown Center for Biomedical Informatics, and the Tufts CTSI Informatics team.
#TODO: some import methods can be used to delete entries
2
+
# Should this behavior be migrated to delete_* functions?
3
+
4
+
"""
5
+
REDCap API methods are defined as named Julia functions.
6
+
The `content` and `action` parameters are managed internally.
7
+
8
+
Function docstrings indicate how to use the Julia functions.
9
+
Refer to the official documentation for detailed specifications on the corresponding REDCap methods.
10
+
11
+
## Syntax
12
+
Each REDCap method accepts a number of parameters that follow a shared naming convention.
13
+
REDCap.jl is designed to closely follow the design and syntax patterns of REDCap.
14
+
Every REDCap API method is available as a function that supplies certain required parameters and checks user inputs for validity.
15
+
16
+
Return values and REDCap messages are returned as Strings directly, but the documentation shows how these can be parsed in useful ways.
17
+
18
+
Function arguments are named after REDCap method parameters.
19
+
These are passed as named arguments and take values with intuitive types.
20
+
21
+
### `token` and `url`
22
+
Nearly all REDCap methods accept a token that is unique to the project and user.
23
+
24
+
The URL must exactly match this example:
25
+
```https://example.example/redcap/api/```
26
+
27
+
Your REDCap token and your institution's REDCap API URL can be read by default from Julia's environment variables.
28
+
You can make them avaiable to REDCap.jl by putting the following lines in [your local Julia startup file](https://docs.julialang.org/en/v1/manual/command-line-interface/#Startup-file) (probably `~/.julia/config/startup.jl`):
String values are accepted. If the string is a file name, the contents of the file are sent; otherwise, the value is sent directly as part of the API request.
out = open("data_file.json","w"); write(out, data_string); close(out)
73
+
74
+
import_DAGs(token=t,data=data_string, format=:json) # string is passed to the API
75
+
76
+
import_DAGs(token=t, data="data_file.json", format=:json) # string is pattern-matched as a filename
77
+
78
+
```
79
+
As for collections, only collections of scalar entries are currently supported.
80
+
So, a list of attributes and values is accepted, but a Dict containing multiple rows per column can only be read in from a file.
81
+
82
+
In the REDCap API, the presence of a `data` parameter often changes the behavior of a method.
83
+
For instance, most import methods are implemented as an export method with an added data parameter.
84
+
In REDCap.jl, it would be considered a bug for `import_project_data` to ever act as `export_project_data`, so the data paramater is almost always required where it is present.
85
+
86
+
### `format` and `returnFormat`
87
+
Supported options are `:csv`, `:json`, `:xml` (the default value), and sometimes `:odm`.
88
+
These values can be passed as Strings or Symbols.
89
+
90
+
For import methods, the `format` parameter designates user input and the `returnFormat` parameter applies to REDCap messages and return values.
91
+
Otherwise, there is generally only a single `format` parameter that applies to REDCap messages and return values.
92
+
93
+
### `content` and `action`
94
+
The `content` and `action` parameters are what define each REDCap method, for the most part.
95
+
In REDCap.jl, these are passed internally and don't need to be supplied by the user.
96
+
Instead, they're fixed for each function.
97
+
98
+
## Troubleshooting
99
+
- If a function call doesn't produce the expected results, try making debug messages visible for this package by running `ENV["JULIA_DEBUG"] = REDCap`.
100
+
- The `data` parameter is converted to a formatted string, so you might try different format parameters (`:csv`, `:json`, or `:xml`).
101
+
If you're uncertain about the format for an input data parameter, try setting up an example in the browser and exporting the data.
102
+
You may have to remove the values for certain generated columns before importing.
103
+
- Feel free to create an issue for any unexpected errors, or for feature requests.
function import_arms(; url=get_url(), token=get_token(), format=nothing, data, returnFormat=nothing, override=nothing,)
47
+
48
+
Import new study arms to a REDCap project, or rename existing arms
49
+
50
+
# Notes
51
+
Deleting a study arm deletes any included records and data.
52
+
53
+
# Named arguments
54
+
- `url`: (read from `ENV["REDCAP_API_URL"]` by default)
55
+
- `token`: an API token specific to the REDCap project and username (read from `ENV["REDCAP_API_TOKEN"]` by default)
56
+
- `arms`: names of study arms (can be scalar or vector)
57
+
- `override`: if true, all existing arms are erased; if false (default), existing arms can only be renamed
58
+
- `data`: May be a String, a file name, or a data type such as NamedTuple or Dict
59
+
- `format`: the format of the `data` input parameter: `:csv`, `:json`, or `:xml` (default). If `data` is a String or a file name, this value must indicate the correct format. If `data` is a NamedTuple, Dict, or similar type, this value will determine what format will be used internally to pass on the data.
60
+
- `returnFormat`: the desired output format: `:csv`, `:json`, or `:xml` (default)
0 commit comments