Command-Line Interface (CLI)
MedCo provides a client command-line interface (CLI) to interact with the medco-connector APIs.

Prerequisites

To use the CLI, you must first follow one of the deployment guides. However, the version of the CLI documented here is the one shipped with the Local Development Deployment.

How to use

To show the CLI manual, run:
1
export MEDCO_SETUP_DIR=~/medco
2
cd ${MEDCO_SETUP_DIR}/deployments/dev-local-3nodes/
3
docker-compose -f docker-compose.tools.yml run medco-cli-client --user [USERNAME] --password [PASSWORD] --help
4
5
NAME:
6
medco-cli-client - Command-line query tool for MedCo.
7
8
USAGE:
9
medco-cli-client [global options] command [command options] [arguments...]
10
11
VERSION:
12
dev
13
14
COMMANDS:
15
concept-children, con-c Get the concept children (both concepts and modifiers)
16
modifier-children, mod-c Get the modifier children
17
concept-info, con-i Get the concept info
18
modifier-info, mod-i Get the modifier info
19
query, q Query the MedCo network
20
ga-get-values, ga-val Get the values of the genomic annotations of type *annotation* whose values contain *value*
21
ga-get-variant, ga-var Get the variant ID of the genomic annotation of type *annotation* and value *value*
22
survival-analysis, srva Run a survival analysis
23
get-saved-cohorts, getsc get cohorts
24
add-saved-cohorts, addsc Create a new cohort.
25
update-saved-cohorts, upsc Updates an existing cohort.
26
remove-saved-cohorts, rmsc Remove a cohort.
27
help, h Shows a list of commands or help for one command
28
29
GLOBAL OPTIONS:
30
--user value, -u value OIDC user login
31
--password value, -p value OIDC password login
32
--token value, -t value OIDC token
33
--disableTLSCheck Disable check of TLS certificates
34
--outputFile value, -o value Output file for the result. Printed to stdout if omitted.
35
--help, -h show help
36
--version, -v print the version
Copied!
For a start, you can use the credentials of the default user: username:test password:test

concept-children

You can use this command to browse the MedCo ontology by getting the children of a concept, both concepts and modifiers.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test concept-children --help
2
NAME:
3
medco-cli-client concept-children - Get the concept children (both concepts and modifiers)
4
5
USAGE:
6
medco-cli-client concept-children conceptPath
Copied!
For example:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test concept-children /E2ETEST/e2etest/
2
PATH TYPE
3
/E2ETEST/e2etest/1/ concept
4
/E2ETEST/e2etest/2/ concept
5
/E2ETEST/e2etest/3/ concept
6
/E2ETEST/modifiers/ modifier_folder
Copied!

modifier-children

You can use this command to browse the MedCo ontology by getting the children of a modifier.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test modifier-children --help
2
NAME:
3
medco-cli-client modifier-children - Get the modifier children
4
5
USAGE:
6
medco-cli-client modifier-children modifierPath appliedPath appliedConcept
Copied!
For example:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test modifier-children /E2ETEST/modifiers/ /e2etest/% /E2ETEST/e2etest/1/
2
PATH TYPE
3
/E2ETEST/modifiers/1/ modifier
Copied!

concept-info

You can use this command to get information about a MedCo concept, including the associated metadata.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test concept-info --help
2
NAME:
3
medco-cli-client concept-info - Get the concept info
4
5
USAGE:
6
medco-cli-client concept-info conceptPath
Copied!
For example:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test concept-info /E2ETEST/e2etest/1/
2
<ExploreSearchResultElement>
3
<Code>ENC_ID:1</Code>
4
<DisplayName>E2E Concept 1</DisplayName>
5
<Leaf>true</Leaf>
6
<MedcoEncryption>
7
<Encrypted>true</Encrypted>
8
<ID>1</ID>
9
</MedcoEncryption>
10
<Metadata>
11
<ValueMetadata>
12
<ChildrenEncryptIDs></ChildrenEncryptIDs>
13
<CreationDateTime></CreationDateTime>
14
<DataType></DataType>
15
<EncryptedType></EncryptedType>
16
<EnumValues></EnumValues>
17
<Flagstouse></Flagstouse>
18
<NodeEncryptID></NodeEncryptID>
19
<Oktousevalues></Oktousevalues>
20
<TestID></TestID>
21
<TestName></TestName>
22
<Version></Version>
23
</ValueMetadata>
24
</Metadata>
25
<Name>E2E Concept 1</Name>
26
<Path>/E2ETEST/e2etest/1/</Path>
27
<Type>concept</Type>
28
</ExploreSearchResultElement>
Copied!

modifier-info

You can use this command to get information about a MedCo modifier, including the associated metadata.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test modifier-info --help
2
NAME:
3
medco-cli-client modifier-info - Get the modifier info
4
5
USAGE:
6
medco-cli-client modifier-info modifierPath appliedPath
Copied!
For example:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test modifier-info /E2ETEST/modifiers/1/ /e2etest/1/
2
<ExploreSearchResultElement>
3
<Code>ENC_ID:5</Code>
4
<DisplayName>E2E Modifier 1</DisplayName>
5
<Leaf>true</Leaf>
6
<MedcoEncryption>
7
<Encrypted>true</Encrypted>
8
<ID>5</ID>
9
</MedcoEncryption>
10
<Metadata>
11
<ValueMetadata>
12
<ChildrenEncryptIDs></ChildrenEncryptIDs>
13
<CreationDateTime></CreationDateTime>
14
<DataType></DataType>
15
<EncryptedType></EncryptedType>
16
<EnumValues></EnumValues>
17
<Flagstouse></Flagstouse>
18
<NodeEncryptID></NodeEncryptID>
19
<Oktousevalues></Oktousevalues>
20
<TestID></TestID>
21
<TestName></TestName>
22
<Version></Version>
23
</ValueMetadata>
24
</Metadata>
25
<Name>E2E Modifier 1</Name>
26
<Path>/E2ETEST/modifiers/1/</Path>
27
<Type>modifier</Type>
28
</ExploreSearchResultElement>
Copied!

query

You can use this command to query the MedCo network.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test query --help
2
3
NAME:
4
medco-cli-client query - Query the MedCo network
5
6
USAGE:
7
medco-cli-client query [command options] [-t timing] query_string
8
9
OPTIONS:
10
--timing value, -t value Query timing: any|samevisit|sameinstancenum (default: "any")
Copied!
This is the syntax of an example query using the pre-loaded default test data.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test query enc::1 AND enc::2 OR enc::3
Copied!
You will get something like that:
1
node_name,count,patient_list,patient_set_id,DDTRequestTime,KSRequestTime,KSTimeCommunication,KSTimeExec,TaggingTimeCommunication,TaggingTimeExec,medco-connector-DDT,medco-connector-i2b2-PDO,medco-connector-i2b2-PSM,medco-connector-local-agg,medco-connector-local-patient-list-masking,medco-connector-overall,medco-connector-unlynx-key-switch-count,medco-connector-unlynx-key-switch-patient-list
2
0,1,[2],10,4236,311,307,0,1657,10,4266,3972,25472,1,153,34834,469,491
3
1,1,[2],10,584,89,75,0,474,78,677,4717,61325,16,3,66991,140,104
4
2,1,[2],10,669,55,45,0,576,49,709,3134,63371,0,8,67358,68,63
Copied!
Query terms can be composed using the logical operators NOT, AND and OR.
Note that, in the queries, the OR operator has the highest priority, so1 AND NOT 2 OR 3 AND 2 is factorised as (1) AND (NOT (2 OR 3)) AND (2)
To each group of OR-ed terms you can also add a timing option ("any", "samevisit", "sameinstancenum") that will override the globally set timing option. For example: ``
1 AND NOT 2 OR 3 samevisit AND 2
Each query term is composed is composed of two mandatory fields, the type field and the content field, and an optional field, the constraint field, all separated by ::.
1
`type::content[::constraint]`
Copied!
Possible values of the type field are: enc, clr, file.
  1. 1.
    When the type field is equal to enc, the content field contains the concept ID. The constraint field is not present in this case.
  2. 2.
    When the type field is equal to clr, the content field contains the concept field (containing the concept path) and, possibly, the modifier field, which in turn contains the modifier key and applied path fields, all separated by :. The optional constraint field can be present, containing the operator, type and value fields separated by :. The constraint field applies either to the concept or, if the modifier field is present, to the modifier. The possible types are NUMBER and TEXT. The possible operators for numbers are: EQ (equals), NE (not equal), GT (greater than), LT (less than), GE (greater than or equal), LE (less than or equal), BETWEEN (between, in this case the value field is in the format "x and y"). The possible operators for TEXT are LIKE[exact], LIKE[begin], LIKE[contains] and LIKE[end].
  3. 3.
    When the type field is equal to file, the content field contains the path of the file containing the query terms, one for each row. The query terms contained in the same file are OR-ed together. Besides enc, clr, and file query terms, a file can also contain genomic query terms, each of which is composed by 4 comma separated values.

ga-get-values

You can use this command to get the values of the genomic annotations that MedCo nodes make available for queries.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test ga-get-values --help
2
3
NAME:
4
medco-cli-client ga-get-values - Get the values of the genomic annotations of type *annotation* whose values contain *value*
5
6
USAGE:
7
medco-cli-client ga-get-values [command options] [-l limit] annotation value
8
9
OPTIONS:
10
--limit value, -l value Maximum number of returned values (default: 0)
Copied!
To do some tests, you may want to load some data first.
Then, for example, if you want to know which genomic annotations of type "protein_change" containing the string "g32" are available, you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test ga-get-values protein_change g32
Copied!
You will get:
1
G325R
2
G32E
Copied!
The matching is case-insensitive and it is not possible to use wildcards. At the moment, with the loader v0, only three types of genomic annotations are available: variant_name, protein_change and hugo_gene_symbol.

ga-get-variant

You can use this command to get the variant ID of a certain genomic annotation.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test ga-get-variant --help
2
3
NAME:
4
medco-cli-client ga-get-variant - Get the variant ID of the genomic annotation of type *annotation* and value *value*
5
6
USAGE:
7
medco-cli-client ga-get-variant [command options] [-z zygosity] [-e] annotation value
8
9
DESCRIPTION:
10
zygosity can be either heterozygous, homozygous, unknown or a combination of the three separated by |
11
If omitted, the command will execute as if zygosity was equal to "heterozygous|homozygous|unknown|"
12
13
OPTIONS:
14
--zygosity value, -z value Variant zygosysty
15
--encrypted, -e Return encrypted variant id
Copied!
To do some tests, you may want to load some data first.
Then, for example, if you want to know the variant ID of the genomic annotation "HTR5A" of type "hugo_gene_symbol" with zygosity "heterozygous" or "homozygous", you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test ga-get-variant -z "heterozygous|homozygous" hugo_gene_symbol HTR5A
Copied!
You will get:
1
-7039476204566471680
2
-7039476580443220992
Copied!
The matching is case-insensitive and it is not possible to use wildcards. If you request the ID of an annotation which is not available (e.g, in the previous, example, "HTR5") you will get an error message. At the moment, with the loader v0, only three types of genomic annotations are available: variant_name, protein_change and hugo_gene_symbol.

get-saved-cohorts

You can run this command to get the cohorts that have been previously saved.
1
NAME:
2
medco-cli-client get-saved-cohorts - get cohorts
3
4
USAGE:
5
medco-cli-client get-saved-cohorts [command options] [-l limit]
6
7
DESCRIPTION:
8
Gets the list of cohorts.
9
10
OPTIONS:
11
--limit value, -l value Limits the number of retrieved cohorts. 0 means no limit. (default: 10)
Copied!
You can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test getsc
Copied!
You will get:
1
node_index,cohort_name,cohort_id,query_id,creation_date,update_date,query_timing,panels
2
0,testCohort,-1,-1,2020-08-25T13:57:00Z,2020-08-25T13:57:00Z,any,"{panels:[{items:[{encrypted:false,queryTerm:/E2ETEST/SPHNv2020.1/DeathStatus/}],not:false,panelTiming:any}]}"
3
1,testCohort,-1,-1,2020-08-25T13:57:00Z,2020-08-25T13:57:00Z,any,"{panels:[{items:[{encrypted:false,queryTerm:/E2ETEST/SPHNv2020.1/DeathStatus/}],not:false,panelTiming:any}]}"
4
2,testCohort,-1,-1,2020-08-25T13:57:00Z,2020-08-25T13:57:00Z,any,"{panels:[{items:[{encrypted:false,queryTerm:/E2ETEST/SPHNv2020.1/DeathStatus/}],not:false,panelTiming:any}]}"
Copied!

add-saved-cohorts

You can run this command to save a new cohort. The patient set IDs are given from a previous explore request. More precisely, they are taken from the patient_set_id column of explore results. The list of IDs must be given in a coma-separated format, without space. There must as many IDs as there are nodes.
1
NAME:
2
medco-cli-client add-saved-cohorts - Create a new cohort.
3
4
USAGE:
5
medco-cli-client add-saved-cohorts [command options] -c cohortName -p patientSetIDs
6
7
DESCRIPTION:
8
Creates a new cohort with given name. The patient set IDs correspond to explore query result IDs.
9
10
OPTIONS:
11
--patientSetIDs value, -p value List of patient set IDs, there must be one per node
12
--cohortName value, -c value Name of the new cohort
Copied!
For example, you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test addsc -c testCohort2 -p 10,10,10
Copied!

update-saved-cohorts

You can run this command to update an existing cohort. The patient set IDs are given from a previous explore request, in the same manner as add-saved-cohort command.
1
NAME:
2
medco-cli-client update-saved-cohorts - Updates an existing cohort.
3
4
USAGE:
5
medco-cli-client update-saved-cohorts [command options] -c cohortName -p patientSetIDs
6
7
DESCRIPTION:
8
Updates a new cohort with given name. The patient set IDs correspond to explore query result IDs.
9
10
OPTIONS:
11
--patientSetIDs value, -p value List of patient set IDs, there must be one per node
12
--cohortName value, -c value Name of the existing cohort
Copied!
For example, you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test upsc -c testCohort2 -p 9,9,9
Copied!

remove-saved-cohorts

You can run this command to remove an existing cohort.
1
NAME:
2
medco-cli-client remove-saved-cohorts - Remove a cohort.
3
4
USAGE:
5
medco-cli-client remove-saved-cohorts [command options] -c cohortName
6
7
DESCRIPTION:
8
Removes a cohort for a given name. If the user does not have a cohort with this name in DB, an error is sent.
9
10
OPTIONS:
11
--cohortName value, -c value Name of the cohort to remove
Copied!
For example, you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test rmsc -c testCohort2
Copied!
This command removes the cohort from the node servers and it is not be possible to revert this action.

cohorts-patient-list

You can run this command to get the list of patient belonging to cohort. The cohort is identified by providing its name.
1
NAME:
2
medco-cli-client cohorts-patient-list - Retrieve patient list belonging to the cohort
3
4
USAGE:
5
medco-cli-client cohorts-patient-list [command options] -c cohortName [-d timer dump file]
6
7
DESCRIPTION:
8
Retrieve the encrypted patient list for a given cohort name and locally decrypt it.
9
10
OPTIONS:
11
--cohortName value, -c value Name of the new cohort
12
--dumpFile value, -d value Output file for the timers CSV. Printed to stdout if omitted.
Copied!
For example, you can run:
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test cpl -c testCohort
Copied!
You will get something like:
1
Node idx 0
2
1137,1138,1139,1140
3
Node idx 1
4
1137,1138,1139,1140
5
Node idx 2
6
1137,1138,1139,1140
Copied!

survival-analysis

You can run this command to get information useful to run survival analysis. The relative time points are computed as the difference between absolute dates of start concept and end concept.
1
NAME:
2
medco-cli-client survival-analysis - Run a survival analysis
3
4
USAGE:
5
medco-cli-client survival-analysis [command options] -l limit [-g granularity] [-c cohortID] -s startConcept [-x startModifier] -e endConcept [-y endModifier]
6
7
DESCRIPTION:
8
Returns the points of the survival curve
9
10
OPTIONS:
11
--limit value, -l value Max limit of survival analysis. (default: 0)
12
--granularity value, -g value Time resolution, one of [day, week, month, year] (default: "day")
13
--cohortID value, -c value Cohort identifier (default: -1)
14
--startConcept value, -s value Survival start concept
15
--startModifier value, -x value Survival start modifier (default: "@")
16
--endConcept value, -e value Survival end concept
17
--endModifier value, -y value Survival end modifier (default: "@")
Copied!
Start and concept are determined by the name of the access table concatenated to the full path of the concept.
The default cohort identifier -1 corresponds to test data loaded for end-to-end testing. All future cohort identifiers will be positive integers. Cohorts can be created after a successful MedCo Explore query.
1
docker-compose -f docker-compose.tools.yml run medco-cli-client --user test --password test srva srva -l 2000 -g week -c 1 -s /SPHN/SPHNv2020.1/FophDiagnosis/ -e /SPHN/SPHNv2020.1/DeathStatus/ -y 126:1
Copied!
The matching is case-insensitive and it is not possible to use wildcards. If you request the ID of an annotation which is not available (e.g, in the previous, example, "HTR5") you will get an error message. At the moment only three types of genomic annotations are available: variant_name, protein_change and hugo_gene_symbol.
Last modified 4mo ago