How to config "-param_file" to run GSEA on command line?

[Miguel Ribeiro]

Hi,

I hope this message finds you well!

I'm currently working with GSEA and looking to integrate it as a module within a modular pipeline for streamlined enrichment analysis.

While attempting to run GSEA from the command line, I found that using a parameter file seems much more intuitive than specifying all parameters directly via the command line. The documentation on "Running GSEA from the Command Line" mentions an optional -param_file argument, which I understand is used to provide a configuration file containing the necessary parameters.

However, I couldn’t find any information in the documentation regarding the expected structure or format of this parameter file.

Could you please clarify what format this file should follow, or point me to an example?

Thank you in advance!

Best regards,
Miguel Ribeiro.

[David Eby]

Hi Miguel,

Sorry about the delayed response.  I'm part-time on this project right now and wasn't able to get to your message earlier.

The documentation for running from the command line has this to say about the format:

Optionally, use the –param_file parameter to specify a parameter file, which can contain any parameter except –param_file. If you specify the same parameter on the command line and in the parameter file, the value on the command line takes precedence. A parameter file is a text file that defines one parameter per line. Each line contains a parameter name (without the initial hyphen), a tab (not spaces), and the parameter value.

I've attached an example file for a GSEA run that should serve as a starting point.  Obviously you will need to change the contents to match your own file locations and so on.  This would be run as:

./gsea-cli.sh GSEA /path/to/param.txt     # modify path to suit your own location.

That's the syntax for Linux/Mac.  For Windows:

gsea-cli.bat GSEA D:\path\to\param.txt

Note that you can override parameters specified in the file at the command line, or even omit them from the file altogether and only use the command line:

./gsea-cli.sh GSEA /path/to/param.txt -gmx ftp.broadinstitute.org://pub/gsea/msigdb/human/gene_sets/c1.all.v2024.1.Hs.symbols.gmt

So, you could set up a param file with all the analysis parameters but not specifying the GCT/RES and CLS file, and then supply those yourself at the CLI over multiple datasets with everything else fixed.  Or you could set the dataset to be fixed and vary the gene set collection, and so on.

We use this interface as the basis for our GenePattern modules and internal test suite, so it's well tested.

The documentation mentions that you can use the Command button within the GSEA GUI to find all of the parameter settings to use at the command line.  Another option is to look at the RPT file in the tool output directory.  This gives a file which is very similar to the -param_file format except with a leading 'param' column on the lines with parameters.  By removing all other non-param lines and then removing the leading 'param' you get a valid param file.  Something like the UNIX 'grep param my_analysis.Gsea.1741387096901.rpt | cut -f 2- > param.txt' would do the job in most cases.

I hope that's helpful.

Regards,

David

David Eby
www.gsea-msigdb.org

--
You received this message because you are subscribed to the Google Groups "gsea-help" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gsea-help+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/gsea-help/ca091704-b242-41f0-91b1-ee914bda156fn%40googlegroups.com.

[Miguel Ribeiro]

Hi David,

First of all, thank you so much for your response—it was extremely helpful!

I’ve been working on a Docker-based tool to run GSEA using the configured parameter file we discussed. I’ve also built a preprocessing Docker image that prepares the two required input files (expression_data.gct and phenotype_labels.cls) directly from raw expression data, using a task-specific config file and automatically generating the necessary key-value pairs for the GSEA run.

While setting this up, I ran into a question regarding the use of GSEA_4.4.0-NoJava.zip and the gsea-cli.sh script. Since Docker images need all required files present at build time, I’m currently testing by manually downloading the zip file, adding it to the image, unzipping it, and using the CLI from there.

My question is: what’s the best practice for distributing this Docker image to other users?

• Should I ask users to provide the GSEA_4.4.0-NoJava.zip file themselves when building the image?

• Or is it acceptable (and allowed) to include the zip file inside the image I distribute?

I want to ensure the image is easy to use while respecting licensing or distribution constraints.

Thanks again for your help!

Best,
Miguel Ribeiro