Command Line Interface¶
StonPy includes a Command Line Interface (CLI) that allows users to perform all the operations supported by the library directly from the command line. The CLI is called using the stonpy command followed by a subcommand:
stonpy <subcommand>
The subcommand may be any of the following:
Subcommand |
Description |
|---|---|
create |
To create one or more maps in the database |
get |
To retreive a map from the database |
delete |
To remove a map from the database |
query |
To query the database |
delete-all |
To delete all data from the database |
list-repos |
To list all repositories currently supported |
Connection options¶
All of the CLI’s subcommands but the list-repos subcommand require a connection to a Neo4j database. These subcommands may be executed with the following connection options:
Option |
Description |
|---|---|
-a, --uri |
The uri for accessing the database |
-u, --user |
The user name |
-p, --password |
The password |
A subcommand is executed with the connection options as follows:
stonpy <subcommand> -a <uri> -u <user> -p <password>
Create¶
The create subcommand creates one or more maps in the database from a local or distant file, directory or repository:
stonpy create <target>
The target argument may be a local path or an url to:
an SBGN-ML or CellDesigner file;
a ZIP file or a directory containing any of the above;
or a repository name (see List repositories). A repository is a link to a collection of one or more maps hosted by a third party, that are publicly available and have been published. StonPy does not contain any of those maps but only the URLs that point to them.
The ID for the created maps are built automatically from their source (generally their path or url) and displayed to stdout.
Multiple targets may be specified at once:
stonpy create <target1> <target2> <target3>
All data of the database may be deleted before the creation of the maps using the -d, --delete-all option:
stonpy create -d <target>
The create subsubcommand requires a connection to the database (see Connection options):
stonpy create -a <uri> -u <user> -p <password> <target>
Get¶
The get subcommand retreives a map from the database in the SBGN-ML format:
stonpy get <map_id>
By default, the content of the map is printed to stdout. The content of the map can be printed to a file instead using the -o, --output option:
stonpy get -o <path> <map_id>
The get subcommand requires a connection to the database (see Connection options):
stonpy get -a <uri> -u <user> -p <password> <map_id>
Delete¶
The delete subcommand removes a map from the database:
stonpy delete <map_id>
The delete subcommand requires a connection to the database (see Connection options):
stonpy delete -a <uri> -u <user> -p <password> <map_id>
Query¶
The query subcommand executes a Cypher query against the database and retreives its results:
stonpy query <cypher_query>
By default, the results are printed to stdout. The results can be printed to a file instead using the -o, --output option:
stonpy query -o <path> <cypher_query>
The results may be converted to valid SBGN-ML maps using the -c, --convert option (see Completion algorithm for more details on the completion feature):
stonpy query -o <path> -c <cypher_query>
When the conversion option is used, the ouput option (-o) described above becomes mandatory. Additionally, the following options may be used for conversion:
Option |
Description |
|---|---|
-m, --unmerge-records |
Do not merge the results before conversion |
-k, --no-completion |
Do not complete the results before conversion |
-n, --complete-process-modulations |
Complete processes with modulations (only if the no completion option (-k) described above is not set) |
-t, --to-top-left |
Translate maps to the top-left corner after conversion |
The query subcommand requires a connection to the database (see Connection options):
stonpy query -a <uri> -u <user> -p <password> <cypher_query>
Delete all data¶
The delete-all subcommand deletes all data from the database:
stonpy delete-all
The delete-all subcommand requires a connection to the database (see Connection options):
stonpy delete-all -a <uri> -u <user> -p <password>
List repositories¶
The list-repos subcommand lists all available repositories:
stonpy list-repos
Currently, the following repositories are supported:
Example¶
Following is a complete example that demonstrates the use of the different subcommands:
# see available subcommands and options:
stonpy --help
# see available options for subcommand delete-all:
stonpy delete-all --help
# delete all data from the database
stonpy delete-all --uri <uri> --user <user> --password <password>
# list available repositories
stonpy list-repos
# create all maps of repository asthmamap in the database
stonpy create --uri <uri> --user <user> --password <password> asthmamap
# get map https://asthma-map.org/images/af/F012-MastCell-SBGNv02.sbgn,
# and store it in get_output.sbgn
stonpy get --output get_output.sbgn --uri <uri> --user <user> \
--password <password> https://asthma-map.org/images/af/F012-MastCell-SBGNv02.sbgn
# return the 10 first biological activities of the database,
# and store each activity in query_output_n.sbgn
stonpy query --output query_output.sbgn --convert --unmerge-records --to-top-left \
--uri <uri> --user <user> --password <password> \
"MATCH (b:BiologicalActivity) RETURN b LIMIT 10"