GIVE-Toolbox usages

• 1. initial_ref.sh
• 2. add_trackGroup.sh
• 3. add_geneAnnot.sh
• 4. add_track_bed.sh
• 5. add_track_bigWig.sh
• 6. add_track_interaction.sh
• 7. config_host.sh
• 8. list_tracks.sh
• 9. remove_data.sh
• 10. update_give.sh

1. initial_ref.sh

Initialize GIVE database structure with a new reference genome.

bash initial_ref.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>] [-s <species_name>] [-c <species_cname>] [-f <file>]

The arguments of initial_ref.sh are:

• -u <mysqlu>：(Required) MySQL account name. All the databases will be created under this account, such as root in GIVE-Docker. Make sure you have access to this account.
• -p <mysqlp>: (Optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password
• -r <ref>: (Required) ref genome database name. The database name of reference genome. It must be a valid name less than 10 characters in MySQL, i.e., it cannot contain space, /, \, ., and characters that are not allowed in a file name. Example: hg19, hg38, b37_decoy.
• -s <species_name>: (Required) species name of the ref genome. The name of the species, such as scientific name, Homo sapiens. If it contains space or other special character, please quote it, such as “Homo sapiens”.
• -c <species_cname>: (Required) common name of the species. Such as human. If it contains spaces or other special characters, please quote it.
• -f <file>: (Required) cytoBandIdeo file path. It must be a system absolute path. The cytoBandIdeo file defines the genome coordinates. You can download it from UCSC Genome Browser. We also supply some cytoBandIdeo of common human/mouse genomes here.
• -w <default_window>: (Optional) Set the default view window of this ref genome. The value must be quoted with single quotation marks, such as ‘[“chrX:100000-200000”]’ , or ‘[“chr1:100000-200000”, “chrX:10000-20000”]’ for dual chromosome view window.

2. add_trackGroup.sh

Add a track group to a reference genome.

bash add_trackGroup.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>] [-g <group_name>] [-l <long_label>] [-o <priority>] [-s <single_choice>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -r <ref>: (required) Ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -g <group_name>: (required) User defined track group name.
• -l <long_label>: (required) The long label of group, which will be shown on the front end of GIVE.
• -o <priority>: (required) Integer start from 0. It will determine the order of groups, 0 is the top.
• -s <single_choice>: (required) 0 or 1. Whether the group will only allow one track to be active at any time. 0 is FALSE, 1 is TRUE.

3. add_geneAnnot.sh

Add UCSC known gene annotations.

bash add_geneAnnot.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>][-t <track_name>] [-g <group_name>] [-l <long_label>] [-s<short_label>]
[-o <priority>] [-v <visibility>] [-f <file>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt - will ask you to input password.
• -r <ref>: (required) Ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -t <track_name>: (required) Track name you want to build from your data.
• -g <group_name>: (required) User defined track group name. Multiple tracks can be grouped based on experimental design or techniques, such as group “geneAnnotation”, “HiC”and “RNAseq”.
• -l <long_label>: (required) The long label of track.
• -s <short_label>: (required) The short label of track.
• -o <priority>: (required) The order of the track in the browser. Smaller value means the the track will be shown in a higher location.
• -v <visibility>: (required) “full”, “pack”, “collapsed”, “notext”, “dense”, “none”. Usually use “pack”.
• -f <file>: (required) Gene annotation file path. It must be a system absolute path.
• -h: show usage help

4. add_track_bed.sh

Add a data track from bed format file to a track group.

bash add_track_bed.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>][-t <track_name>] [-g <group_name>] [-l <long_label>] [-s<short_label>] [-o <priority>] [-v <visibility>] [-f <file>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -r <ref>: (required) Ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -t <track_name>: (required) Track name you want to build from your data.
• -g <group_name>: (required) User defined track group name. Multiple tracks can be grouped based on experimental design or techniques, such as group “HiC”and “RNAseq”.
• -l <long_label>: (required) The long label of track.
• -s <short_label>: (required) The short label of track.
• -o <priority>: (required) The order of the track in the browser. Smaller value means the track will be shown in a higher location.
• -v <visibility>: (required) “full”, “pack”, “collapsed”, “notext”, “dense”, “none”. Usually use “pack”.
• -f <file>: (required) BED format file. It must be a system absolute path.
• -m <meta_info>: (Optional) Check GIVE mannual of data format to know supported metainfo, such as cellType and labName. The value of ‘-m’ paramter must be json name/value pair list quoted in single quotations, such as: -m ‘“cellType”:”H1”, “labName”:”Zhong Lab”’
• -h: Show usage help

5. add_track_bigWig.sh

Use script add_track_bigwig.sh to build track from bigWig data file.

bash add_track_bigwig.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>] [-t <track_name>] [-g <group_name>] [-l <long_label>] [-s <short_label>] [-o <priority>] [-v <visibility>] [-a <autoscale>] [-W <windowMax>] [-w <windowMin>] [-f <file>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -r <ref>: (required) ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -t <track_name>: (required) track name you want to build from your data.
• -g <group_name>: (required) user defined track group name. Multiple tracks can be grouped based on experimental design or techniques, such as group “HiC”and “RNAseq”.
• -l <long_label>: (required) More detailed description of the track. Will be shown in a future update.
• -s <short_label>: (required) The label that will be shown in the label region.
• -o <priority>: (required) The order of the track in the browser. Smaller value means the the track will be shown in a higher location.
• -v <visibility>: (required) “full” or “none”. The display mode of the track. If “full”, signals will be plotted against the genome in a line graph. If “none”, this track is not shown at all.
• -a <autoscale>: (required) “true” or “false”. Whether the display window is scaled automatically. When this is set to true, the maximum and minimum value will be calculated to be the 95th percentile and 5th percentile of all visible data. If zero is not included in the range, the range will automatically be expanded to include zero.
• -W <windowMax>: (optional) The maximum value of data shown in the window, only effective when autoScale is set to false.
• -w <windowMin>: (optional) The minimum value of data shown in the window, only effective when autoScale is set to false.
• -f <file>: (required) bigWig file path. It must be a system absolute path. Make sure MySQL can access this file.
• -m <meta_info>: (Optional) Check GIVE mannual of data format to know supported metainfo, such as cellType and labName. The value of ‘-m’ paramter must be json name/value pair list quoted in single quotations, such as: -m ‘“cellType”:”H1”, “labName”:”Zhong Lab”’
• -h: Show usage help

6. add_track_interaction.sh

bash add_track_interaction.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>] [-t <track_name>] [-g <group_name>] [-l <long_label>] [-s <short_label>] [-o <priority>] [-v <visibility>] [-q <quantile>] [-f <file>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -r <ref>: (required) Ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -t <track_name>: (required) Track name you want to build from your data.
• -g <group_name>: (required) User defined track group name. Multiple tracks can be grouped based on experimental design or techniques, such as group “HiC”and “RNAseq”.
• -l <long_label>: (required) More detailed description of the track. Will be shown in a future update.
• -s <short_label>: (required) The label that will be shown in the label region.
• -o <priority>: (required) The order of the track in the browser. Smaller value means the the track will be shown in a higher location.
• -v <visibility>: (required) “full” or “none”. The display mode of the track. If “full”, signals will be plotted against the genome in a line graph. If “none”, this track is not shown at all.
• -q <quantiles>: (Optional) The quantile values used for scaling. If not supplied, it will be in mono color autoscale mode. If color gradient based on quantile is desired, an array of quantile values should be provided here. Value will be scaled by quantiles before being mapped onto the color gradient. The quantile value used in the GIVE-Toolbox example: -q “0.37,1.32,1.78,2.19,2.60,2.97,3.43,3.85,4.34,4.90,5.48,6.16,6.94,8.01,9.05,10.41,12.37,14.88,19.84,31.77,290.17”
• -f <file>: (required) Interaction file path. It must be a system absolute path. Make sure MySQL can access this file.
• -m <meta_info>: (Optional) Check GIVE mannual of data format to know supported metainfo, such as cellType and labName. The value of ‘-m’ paramter must be json name/value pair list quoted in single quotations, such as: -m ‘“cellType”:”H1”, “labName”:”Zhong Lab”’
• -h: show usage help

7. config_host.sh

This script tool will configure the “/includes/constants.php" and "/html/components/basic-func/constants.js" with user supplied arguments. Please make sure that you have the authority to write these files.

bash config_host.sh [-r <give_root>] [-u <mysqlu>] [-p <mysqlp>] [-d <host_url>]

• -r <give_root>: (required) The root directory of GIVE. The default dir in our tutorial is “/var/www/give”.
• -u <mysqlu>: (optional) MySQL account name. It must be correctly set or you will not get any track data. If supplied, it will change the file “<give_root>/includes/constants.php”
• -p <mysqlp>: (optional) MySQL account password. It must be correctly set or you will not get any track data. If supplied, it will change the file “<give_root>/includes/constants.php”
• -d <host_url>: (optional) If the local machine has web service and you want to access GIVE through web service, you need to set <host_url> in the file “<give_root>/html/components/basic-func/constants.js” to the URL pointing to your GIVE server. The <host_url> value we set in the GIVE Data Hub is “https://www.givengine.org”. Specify the protocol if you are using one other than http (for example, https), and the port if you are using one other than the standard port for the protocol (80 for http and 443 for https), for example: “https://www.givengine.org:40080”.
• -h: show usage help

8. list_tracks.sh

List existing data tracks in a reference genome. It will show tree structure of the relationships of the track groups and tracks.

If -a is set as “true”, it will ignore other arguments and output all the reference genomes and associated track groups and tracks. If -a is not set as “true”, the 3 arguments -r, -g, -t will determine the output structure level. If only set -r, it will output all the track group names and associated track names in the -r specified reference genome database. If set both -r and -g, then it will list all the track names of -r -g specified track group. If set all the -r -g -t arguments, it will output the detail info of -r -g -t specified track.

bash list_tracks.sh [-u <mysqlu>] [-p <mysqlp>] [-a <true>] [-r <ref>] [-g <group_name>] [-t <track_name>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -a <true>: (optional) If set as “true”, it will list all the tracks in all the reference genomes with database tree structure.
• -r <ref>: (optional) Ref genome database name.
• -g <group_name>: (optional) Track group name.
• -t <track_name>: (optional) Track name.
• -h: Show usage help

9. remove_data.sh

Remove specified data track, track group or the whole reference genome.

 bash remove_data.sh [-u <mysqlu>] [-p <mysqlp>] [-r <ref>] [-g <group_name>] [-t <track_name>] [-a <CONFIRM>]

• -u <mysqlu>: (required) MySQL account name
• -p <mysqlp>: (optional) MySQL account password. Without ‘-p’, the prompt will ask you to input password.
• -r <ref>: (required) Ref genome database name. The ref genome database must has been initialized. If not, please use initial_ref.sh to do it.
• -t <track_name>: (required for removing a track) The first priority of removing data. If -t argument was supplied, only the track will be removed. -g and -a arguments will be ignored.
• -g <group_name>: (required for removing a track group) The second priority of removing data. If -t was not used and -g was supplied, then the track group will be removed. -a arguments will be ignored.
• -a <CONFIRM>: (required for removing the whole ref genome database) The third priority of removing data. If -t and -g were not used, and “-a CONFIRM” was set, then the whole ref genome database (the name is provided with -r argument) will be removed, including all the tracks belong to it. It’s dangerous, be careful.
• -h: Show usage help

10. update_give.sh

This script tool will update the GIVE components according to the master branch of GIVE GitHub repo. It will replace the files in directories <give_root>/includes, <give_root>/html, and <toolbox_dir>. Please make sure that you have the authority to write those files.

bash update_give.sh [-r <give_root>] [-b <toolbox_dir>] [-t <tmp_dir>] [-g <git_branch>]

• -r <give_root>: (required) The root directory of GIVE. The default value is /var/www/give, the same as the settings in GIVE-Docker.
• -b <toolbox_dir>: (required) The directory of the bash scripts of GIVE-Toolbox. The default value is /usr/local/bin, the same as the settings in GIVE-Docker.
• -t <tmp_dir>: (required) A directory for storing temporary files during update. The default value is /tmp, the same as the settings in GIVE-Docker.
• -g <git_branch>: (required) The branch of GIVE GitHub repo. The default value is “master”.
• -h: Show usage help