Passing App Panel's Parameters to the Script

When running a Capsule in Code Ocean, the system looks and executes the Run file. The Run file is a bash script that can be auto-generated by the system and modified manually afterward.

For example, the screenshot below shows the Run script of a sample file provided by Code Ocean.

The Run script is auto-generated and it calls the main.R on line 8. with this parameter "$@". This means passing all the parameters to the script that it calls.

The way to access the parameters as command-line arguments in the main script can vary, depending on the programming language and the method of the parameter.

Order Parameters

Ordered Parameters are selected by default. In this method, the arguments will be passed in order. All the sample scripts accommodate this method and can be easily modified to fit your script.

From the above example, the command in R for accessing the command line arguments is in line 5. It reads all the arguments and saves it in the args variables to access later in line 9 to line 11.

In the App Builder section, the number of the order of the parameter is indicated within the [brackets].

Try out sample files with different programming languages or examine Capsules in the Code Ocean Apps Library to learn how to use the command line arguments.

For example, in Python, you need can import sys and access the argument with sys.argv.

Named Parameters

Alternatively, arguments can be accessed by name if the Named Parameters is selected. The way to access Named Parameters is different from the Order Parameters and varies between languages.

Similar to the order parameters, the name of the parameter is indicated in the [brackets].

Below is the Named Parameter version of the sample script for Python with comments for the purpose of each step. See Python's Argparse Tutorial for more details.

```python
    import argparse

    # create a parser object
    parser = argparse.ArgumentParser()
    
    # add the corresponding parameters
    parser.add_argument('--plot_title', dest='plot_title')
    parser.add_argument('--cycles', dest='cycles')
    parser.add_argument('--input_data', dest='input_data')
    
    # return the data in the object and save in args
    args = parser.parse_args()
    
    # retrive the arguments
    plot_title = args.title
    cycles = int(args.cycles)
    input_data = args.input_data
```

Using a config file to handle input

Instead of calling and handling the input in the main script as in both coding examples above, you can use a config file for a Capsule to handle the input. Since the run script is a bash language, the config file is often a bash script for a Capsule, but it can also be another programming language.

The config file doesn't come with the sample file that is auto-generated by the system. However, most of the Capsule in the Code Ocean Apps are structured this way. Once the config file is set up, don't forget to call the file before the main process.

Let's take Code Ocean Apps Dose response as an example Capsule. It uses an R config file to manage the input. Here is the App Panel for this Capsule. The Order Parameter method was selected and it takes one input file.

This is the config.R script

#!/usr/bin/env Rscript
system("set -ex")

## Passing Args
args <- commandArgs(trailingOnly=TRUE)


if (length(args) == 0 | nchar(args[1])==0) {
    response_data <- list.files(path = "../data", pattern = ".*response.*csv", full.names = TRUE, recursive=TRUE)
} else {
    response_data <- args[1]
}
print(paste("Dose response data file:", response_data))

# Load expression data
gene_expression_file <- read.csv(response_data)

To explain the script, line 5 takes all the inputs as we saw in the earlier example. Then it checks for the input in line 8 with a if statement. It checks if there is no input from the App panel, then the system will execute line 9, using default data in the /data folder. If there is an input provided, then it will access the input with arg[1]. Finally, it prints out the file that will be used in line 13 and loads the file in line 16.

Here is a code snip of the main script (/code/plot_dose_response.R).

#!/usr/bin/env Rscript

library(drda)
library(png)
library(grid)
library(gridExtra)
library(ggplot2)

source("config.R", local=TRUE)

#Remove unexpressed genes.
expressed_genes <- gene_expression_file[, colSums(gene_expression_file != 0) > 0]
expressed_gene_names <- colnames(expressed_genes)[3:dim(expressed_genes)[2]]
...

Line 3-7 loads all the packages, and line 9 calls config.R file to access the parameters from the App Panel.