@openclinical/proforma-inspect
v0.7.0
Published
A CLI tool for analysing PROformajs protocols
Readme
proforma-inspect (command: pfi) is a command-line tool for analysing proformajs protocols.
It was previously published as @openclinical/pfanalyse with the command pfanalyse. The pfanalyse command is still installed as an alias for now, but will be removed in a future release.
Getting started
With Nodejs (tested with v22+) and Git installed you can first clone the repository, install the dependencies and then link the package.
you@yourmachine:~$ git clone https://gitlab.com/openclinical/pfanalyse.git
you@yourmachine:~$ cd pfanalyse
you@yourmachine:~/pfanalyse$ npm install
you@yourmachine:~/pfanalyse$ npm link
you@yourmachine:~/pfanalyse$ pfi
Usage: pfi [options] <guideline_url> [decision_path] [data_url]
A command line tool to analyse proformajs decisions
Options:
-d, --debug Show debug information
-u, --user <username> username (for authenticating to labs.openclinical.net)
-s, --show Show decision PROforma (when viewing a decision)
-a, --auto Generate spreadsheet of all data combinations relevant
to decision
-V, --version output the version number
-h, --help display help for commandpfi performs the following steps:
- loads the guideline
- grabs the decision, analyses it to find it's dependent data definitions
- loads the tsv file
- checks the tsv file to make sure that the first columns match the set of data definitions and the subsequent columns match the set of decision candidates
- loads the data from each row of the tsv into the extracted single decision model to see if the recommendation matches the suggested recommendation
- returns a tsv that has the following shape:
loaded matched flu cold other
true false NN YN NY
true true YY NN NNWhere the first "Y" or "N" indicates the value passed in the data file and the second "Y" or "N" indicates whether the candidate is recommended by the decision model. In the example one line matches the recommendation and the other does not. The first case data recorded a flu diagnosis where the model recommended a cold.
Note that if the tsv file is ommitted, the tool performs steps 1 and 2 above and then outputs the headers for the tsv it expects to injest and indicates the accepted values for those columns. Note that an asterix indicates a multi-valued data item which will accept array values.
TSV vs CSV
Tab-separated value (tsv) files are used instead of comma separated value (csv) files to avoid ambiguity when handling array values, e.g. ["Extreme exhaustion","General aches and pains"].
Examples
Parse guideline
If you pass a valid guideline url, the output is a list of decision paths within that guideline:
you@yourmachine:~/pfanalyse$ pfi file://./etc/cold_or_flu.json
pfi - available decision paths:
cold_or_flu:diagnosisShow expected spreadsheet design
If you pass a valid guideline url and decision path then the output is a list of columns for the test spreadsheet:
you@yourmachine:~/pfanalyse$ pfi file://./etc/cold_or_flu.json cold_or_flu:diagnosis
complaints INPUT Text* ["Extreme exhaustion", "Runny stuffy nose", "Sore throat", "General aches and pains", "Headache"]
vaccine INPUT Boolean
temperature INPUT Float
cough INPUT Text ["No cough", "Mild to moderate", "Severe"]
flu OUTPUT Boolean (i.e. isRecommended)
cold OUTPUT Boolean (i.e. isRecommended)
other OUTPUT Boolean (i.e. isRecommended)Successful analysis
In the following example a data file with two cases is analysed.
you@yourmachine:~/pfanalyse$ pfi file://./etc/cold_or_flu.json cold_or_flu:diagnosis file://./etc/cold_or_flu.tsv
loaded matched flu cold other
true false NN YN NY
true true YY NN NNIt shows the model disagrees with the first example (flu was the outcome, but cold was recommended) and agrees in the second example.
Unsuccessful analysis
There is feedback if the spreadsheet does not have the correct shape.
you@yourmachine:~/pfanalyse$ pfi file://./etc/cold_or_flu.json cold_or_flu:diagnosis file://./etc/cold_or_flu-noparse.tsv
pfi - failed to parse csv
Invalid Record Length: columns length is 7, got 1 on line 3Dynamic data definitions
In this example, dob is the data provided but the decision expressions use age, however the model has analysed just the need for dob as an input.
you@yourmachine:~/pfanalyse$ pfi file://./etc/dyndef.json exporttest:decision
dob INPUT Date
yes OUTPUT Boolean (i.e. isRecommended)
no OUTPUT Boolean (i.e. isRecommended)
you@yourmachine:~/pfanalyse$ pfi file://./etc/dyndef.json exporttest:decision file://./etc/dyndef.tsv
loaded matched yes no
true true YY NNAuto parameter - missing range
If you pass a valid guideline url and decision path with the -a or --auto option then pfi will check to see if it can impute a range for each dependent data definition:
you@yourmachine:~/pfanalyse$ pfi -a file://./etc/cold_or_flu.json cold_or_flu:diagnosis
Warning: cannot impute possible values for temperature. Expressions that use this data definition:
* 'temperature>37.8'
* 'temperature<=37.8'
* 'temperature>38.9'In this case the temperature data definition hasnt got a range, so you'll need to provide a range for it via meta.pfi on the root element - see /etc/cold_or_flu_auto.json. The legacy meta.pfanalyse key is still read; if both are present, meta.pfi takes precedence for any data definition listed in both.
Auto parameter analysis
If you pass a valid guideline url and decision path with the -a or --auto option and a range can be found for every dependent data definition then every combination of input data will be tested and the results are output as a spreadsheet.
you@yourmachine:~/pfanalyse$ pfi -a file://./etc/cold_or_flu_auto.json cold_or_flu:diagnosis
temperature complaints cough vaccine [] ["flu"] ["cold"] ["cold","flu"] ["other"] ["other","flu"] ["other","cold"] ["other","cold","flu"]
37 [] "No cough" true 0 0 0 0 1 0 0 0
37 [] "No cough" false 0 0 0 0 1 0 0 0
...In the output the tsv the first four columns are inputs and the following columns represent possible recommendations of the decision (all combinations).
Guideline url
You can analyse a guideline in openclinical labs by passing through the API url of that guideline. If the guideline is private then you can pass your username with the -u username parameter and you will be prompted for a password.
you@yourmachine:~/pfanalyse$ pfi https://labs.openclinical.net/api/v1/demo/cold_or_flu
pfi - available decision paths:
cold_or_flu:diagnosisDependent decisions
The issue1 guideline has an extra decision, diagnosis2 that refers to the result of the diagnosis decision.
you@yourmachine:~/pfanalyse$ pfi file://./etc/issue1.json
pfi - available decision paths:
cold_or_flu:diagnosis
cold_or_flu:diagnosis2So the analysis of diagnosis2 needs an input of the result of the diagnosis decision.
you@yourmachine:~/pfanalyse$ pfi file://./etc/issue1.json cold_or_flu:diagnosis2
diagnosis INPUT Text* ["flu", "cold", "other"]
age INPUT Integer
candidate1 OUTPUT Boolean (i.e. isRecommended)