Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Overview
OpenCGA is delivered with implements three different command lines (for different purposes, these are opencga.sh, opencga opencga-admin.sh and and opencga-analysis.sh). All 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)
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
|
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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.
, design and share many usage features:
- structure: they are organised in commands and subcommands, e.g.:
./opencga.sh <command> <subcommand> [options] - authentication: you need to be authenticated to run the command lines, only admin user can run opencga-admin.sh. Anonymous user can run opencga.sh when using public studies.
- output: all of them follow the same usage conventions for parameters and output
Architecture
Here you can find a diagram of the three command lines a brief description below:
Image Added
opencga.sh
This is the main command line for normal users, in fact this is the only command line that everybody should use. It implements all the functionality in more than 100 command and subcommands, for example you can login, list files, search samples or query variants. The vast majority of the subcommands run over RESTful web services so this command line can run remotely (outside of the cluster) or locallly (inside the cluster) as long as you have access to the REST server, this command line uses client-configuration.yml file. You can find more detailed information at Command Lines > opencga.sh
opencga-admin.sh
This command line requires the admin password to be executed, it allows to install catalog database and indexes, create users, query the audit, ... This does not use RESTful web services and it needs direct access to the server, so it only runs in the OpenCGA cluster and it uses configuration.yml. You can find more detailed information at Command Lines > opencga-admin.sh.
opencga-analysis.sh
This command line is used by OpenCGA system itself and nobody is expected to use it unless you are debugging and you really understand how it works. It runs in the cluster and uses configuration.yml. No more detailed information is provided at this moment.
Include Page | ||||
---|---|---|---|---|
|
Table of Contents:
Table of Contents | ||
---|---|---|
|