dxapp.json. This file should be located in the root directory of the app directory as shown in the structure above.
dxapp.jsonis a DNAnexus application metadata file. Its presence in a directory tells DNAnexus tools that it contains DNAnexus applet source code. We explain selected fields of this file below.
name). Under the
inputSpecfield, we specify that the app will take in 2 inputs:
sorted_bams: an array of BAM files
advanced_options: an optional string of advanced command line options to be passed to the Sambamba merge command.
outputSpecfield, we specify that the app will always return 1 output:
merged_bam: a single merged BAM file
merged_bamoutput should contain filenames that match the pattern
"\*.bam". This specification tells the web UI to filter only files which match this pattern when selecting input files.
runSpecthat this is a bash script (field:
interpreter) and that the worker running the applet should execute the executable located in the applet directory at
resources/usr/bin/directory of your app directory.
script.shand located in the applet directory at the path
src/script.sh. This location is important as this is the location specified in the
-eflag causes bash to exit at any point if there is any error, the
-o pipefailflag tells bash to throw an error if it encounters an error within a pipeline, while the
-xflag causes bash to output each line as it is executed -- useful for debugging.
-eset by default. If you wish to keep the script running to the end regardless of any errors that may occur during the execution, use
set +eat the beginning of the script.
dx-download-all-inputscommand-line utility. Add this line to your
$HOME/in/. Each file input parameter specified under
dxapp.jsonwill have its own folder under the
$HOME/in/directory. In the case of this applet, there will be one folder for the
sorted_bamsinput on the path
sorted_bamsis an array of files, these files will be placed into numbered subdirectories under a parent directory
$HOME/in/sorted_bams/. For example, if the user supplied the following 3 files to the applet,
SRR100022_chrom22_mapped_to_b37.bam, in that order, the files would be downloaded into the following paths respectively:
$HOME/out/merged_bam, which corresponds to the merged_bam output parameter in the
dxapp.json. Later, we will place the output of Sambamba merge, a merged BAM file, into this subdirectory.
dx-upload-all-outputs. This utility will automatically upload all files found on the path
$HOME/out/and link the files to the appropriate output parameter (the outputs specified under
$HOME/out/merged_bam/will be uploaded as the merged_bam output parameter of the job.
NOTE: The execution of an applet on a worker starts inside $HOME, so in this tutorial $HOME/in, ~/out, and out/ are all the same since we have not changed directories.
$sorted_bams_prefixvariable to help us name our output file. This variable is provided for every
array:fileinput parameter specified in the applet's
array:file. The variable
$sorted_bams_prefixis a bash array of filenames of every file in the file array with the extension stripped off, as well as any
.gzextension (if applicable).
NA12878.chr1, the second item
$advanced_optionsduring app initialization.
$output namebash variable set in the section above.
$sorted_bams_pathvariable to help us pass the input files to the executable.
dxapp.json. This bash variable stores the full path of each input file, assuming that the file was downloaded using
$sorted_bams_pathvariable is a bash array containing the file paths of the files given as input to sorted_bams, in the order they were given to the app.
"$sorted_bams_path[@]"represents the array as a string, properly tokenized for any whitespace.
NA12878.chr3.bam, the interpreted sambamba merge command will look like this:
out/merged_bam/folder to be uploaded using
dx-upload-all-outputs. This utility will upload the contents of the subdirectories on the path
dxapp.json, and shell script (
src/script.sh). However, you can automate this step by using the
dx-app-wizardas explained in the Intro to Building Apps tutorial.
dx-app-wizardwill prompt you for inputs, and automatically creates the
dxapp.jsonbased on your answers and a template file for your shell script. However, the app wizard was not intended to be a tool for the advanced developer. Thus, it does not prompt you for more advanced fields in the applet specification such as
instanceType. Additionally, it does not use the
dxapp.json. Afterwards, you can then go back in and add additional fields to the
dxapp.jsonand replace the template bash script with your own.
dx getcommand to reconstruct and download the source directory of open-source apps (e.g.
dx get app-cloud_workstation). You can find open-source apps with the command below