- Created by Nacho Medina, last modified on Dec 31, 2016
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 8 Next »
Overview
OpenCGA is delivered with three different command lines (opencga.sh, opencga-admin.sh and opencga-analysis.sh). All of them follow the same structure that could be divided into three different sections (header, usage, and list of commands).
opencga.sh
opencga-admin.sh
opencga-analysis.sh
General Description
In this section you will learn how to use the command lines, some examples are provided using opencga.sh command line.
Some basic information about command lines
OpenCGA follows the most standard conventions when implementing command lines, the most relevant ones are:
- single-character parameters start with a hyphen symbol while multi-character parameters two hyphens are required, e.g. -h or --help.
- single-character parameters can be lower-case or upper-case while multi-character parameters are written always in lower-case
- in the Usage optional parameters are written between [square brackets]:
./opencga.sh [-h|--help] [--version] <command> [options]
- in the Usage mandatory parameters are written between < and >
Usage
You can execute any of the three different command lines without any argument to get the usage help (you can also provide -h parameter)
imedina@ivory:~/appl/opencga/build/bin$ ./opencga.sh Program: OpenCGA (OpenCB) Version: 1.0.0-rc3 Git commit: f42850ff3ff1acb8d0a1bac710c9ec38e084fee5 Description: Big Data platform for processing and analysing NGS data Usage: opencga.sh [-h|--help] [--version] <command> [options] Catalog commands: users User commands projects Project commands studies Study commands files Files commands jobs Jobs commands individuals Individuals commands samples Samples commands variables Variable set commands cohorts Cohorts commands tools Tools commands panels Panels commands Analysis commands: alignments Implement several tools for the genomic alignment analysis variant Variant commands
where:
- Line 1: executing without arguments any of the three command lines (or with -h or --help) print usage information
- Line 3-6: these lines show some metadata about the executable: program name and version, Git commit (in development versions there can be different commits for the same version) and a description.
- Line 8: shows the Usage for this command lines which the same for the three of them, as you can see there are two some optional parameters (in square brackets) help and version; and one mandatory parameter <command> is required. Parameter --help prints this usage and parameter --version prints the version and Git commit.
- Line 10: the different commands for this command line are printed together with a description
When one command is provided as an argument then a specific help for that command is shown, this specific help shows the different subcommands available together with a description, in the following example you can see
imedina@ivory:~/appl/opencga/build/bin$ ./opencga.sh users Usage: opencga.sh users <subcommand> [options] Subcommands: create Create a new user info Get complete information of the user together with owned and shared projects and studies update Update some user attributes using GET method change-password Update some user attributes using GET method delete Delete an user [NO TESTED] projects List all projects and studies belonging to the selected user login Login as a user logout End user session reset-password Reset password
imedina@ivory:~/appl/opencga/build/bin[release-1.0.0-rc3]$ ./opencga.sh samples update -h Usage: opencga.sh samples update [options] Options: -C, --conf STRING Configuration folder that contains opencga.yml, catalog-configuration.yaml, storage-configuration.yml and client-configuration.yaml files. -d, --description STRING Description -h, --help Print this help [false] --individual STRING Individual id or name --log-file STRING Set the file to write the log -L, --log-level STRING One of the following: 'error', 'warn', 'info', 'debug', 'trace' [info] -M, --metadata Include metadata information [false] -n, --name STRING Cohort set name. --no-header Not include headers in the output (not applicable to json output-format) [false] --of, --output-format STRING Output format. one of {JSON, JSON_PRETTY, TEXT, YAML} [TEXT] * --sample STRING Sample id or name -S, --sid, --session-id STRING Token session id --source STRING Source -s, --study STRING Study [[user@]project:]study where study and project can be either the id or the alias. -v, --verbose Increase the verbosity of logs [false]
Old
Header
The header always contains meta information regarding the program being runned, the current version, the git commit to be able to reproduce again the same results and a general description.
Program: OpenCGA (OpenCB)
Version: 1.0.0-rc3
Git commit: f42850ff3ff1acb8d0a1bac710c9ec38e084fee5
Description: Big Data platform for processing and analysing NGS data
Usage
The command lines always starts with the executable followed by the list of of commands and options.
Usage: opencga.sh [-h|--help] [--version] <command> [options]
Some of the common options for the three command lines are:
-h, --help: This is used to see the help of the command line (header, usage and available commands). This option is also available with any command or subcommand. In those cases, the usage and the available options will be shown.
--version: This parameter is used to show the version and the git commit such as in the header.
Commands
The available commands are shown in this section together with a brief description containing the aim of each one. In order to successfully run an OpenCGA command line, a proper command, subcommand and options have to be supplied.
A list containing the available subcommands will be shown when only a command is provided (./opencga.sh users will show the list of subcommands available such as create, info, update…).
A list containing all the different parameters (options) available for an action is offered when the command and the subcommand are successfully provided. Let’s imagine we run ./opencga.sh users create:
The following options are required: -p, --password -e, --email -n, --name -u, --user
Usage: opencga.sh users create [options]
Options:
-C, --conf STRING Configuration folder that contains opencga.yml, catalog-configuration.yaml, storage-configuration.yml and client-configuration.yaml files.
* -e, --email STRING User email
-h, --help Print this help [false]
--log-file STRING Set the file to write the log
-L, --log-level STRING One of the following: 'error', 'warn', 'info', 'debug', 'trace' [info]
-M, --metadata Include metadata information [false]
* -n, --name STRING User name
--no-header Not include headers in the output (not applicable to json output-format) [false]
-o, --organization STRING User organization
--of, --output-format STRING Output format. one of {JSON, JSON_PRETTY, TEXT, YAML} [TEXT]
* -p, --password STRING User password
--project-alias STRING Project alias: Default: default
--project-description STRING Project description.
--project-name STRING Project name. Default: Default
--project-organization STRING Project organization
-S, --sid, --session-id STRING Token session id
* -u, --user STRING User id, this must be unique in OpenCGA
-v, --verbose Increase the verbosity of logs [false]
The options are shown formatted in three columns:
The first column shows the parameter that has to be written (generally with a short and long form). We have decided to use upper case for short forms that are generic and can be used in any command line. Options preceded by an asterisc (*) are mandatory parameters. This means that the command line will not run unless those parameters are provided. Other parameters are optional.
The second columns shows the type of input expected for that option. Generally, it will be STRING when a string is expected after the parameter or empty when the option is a boolean, meaning that the option will be active if parameter is written.
The third column shows a description of the parameter. In some of them we can find in brackets the default value if not written.
The options that are always available are:
-C, --conf: If not defined, the command line will assume that the configuration folder can be found in the parent folder where the executable is found (../conf). If that is not the case or if the user wants to use other configuration files available in a different path, the path should be provided.
-h, --help: Shows the help with the list of options. Generally this is not necessary because there is almost always a mandatory parameter to be provided, although it is needed in a few cases if user wants to see the options.
--log-file: By default, all the logs generated by the command lines are printed in the screen. However, the user might want to redirect the logs to another file. For those cases, the user will need to provide the file where the logs will be stored.
-L, --log-level: There are 5 different log levels. EXPLAIN THIS BETTER.
-M, --metadata:
Table of Contents:
- No labels