Barclay Transition Notes

Picard now uses the Barclay library for command line parsing. This allows Picard to run either with traditional Picard command line syntax:

java -jar picard.jar ValidateSamFile I=input.bam MODE=SUMMARY

or with the POSIX-like Barclay command line syntax:

java -jar picard.jar ValidateSamFile -I input.bam -MODE SUMMARY

By default, traditional Picard syntax is used; to opt-in for Barclay style either use picardBarclay.jar, or alternatively set the system property (picard.useLegacyParser=false).

Source Code Changes and Migration

The names of some of the Barclay argument annotations are different than the Picard names, and some are the same. This table shows the mapping:

Picard Annotation	Barclay Annotation
picard.cmdline.Option	org.broadinstitute.barclay.argparser.Argument
picard.cmdline.CommandLineProgramProperties	org.broadinstitute.barclay.argparser.CommandLineProgramProperties ("usage" -> "summary", "usageShort" -> "oneLineSummary")
picard.cmdline.ClpEnum	org.broadinstitute.barclay.argparser.ClpEnum
picard.cmdline.PositionalArguments	org.broadinstitute.barclay.argparser.PositionalArguments

@ArgumentCollection

Picard now supports use of the @ArgumentCollection annotation. Instead of using @Argument for an instance variable, you can optionally use @ArgumentCollection when the type of an instance variable in a CommandLineProgram is another class that contains one or more @Argument annotations. CommandLineProgram, for instance, now uses this for the REFERENCE_SEQUENCE argument:

@ArgumentCollection
public ReferenceArgumentCollection referenceSequence = makeReferenceArgumentCollection();

Overridable Command Line Arguments

Some of the Picard tools rely on redefining command line arguments inherited from CommandLineProgram that have the "overridable" attribute (usually REFERENCE_SEQUENCE) to either change the doc string; make the argument required, or for some other reason. Barclay doesn't support use of the "overridable". Instead, it uses the @ArgumentCollection annotation in combination with method overrides to implement this behavior.

For example, to make the REFERENCE_SEQUENCE argument required, simply override the requiresReference() method and return true. To change other properties of the reference argument, override the makeReferenceArgumentCollection() method to return an instance of an object that defines the REFERENCE_SEQUENCE argument with the desired properties; this object will be used in place of the default REFERENCE_SEQUENCE argument:

    @Override
    protected ReferenceArgumentCollection makeReferenceArgumentCollection() {
        return new CollectRrbsMetricsReferenceArgumentCollection();
    }

    public static class CollectRrbsMetricsReferenceArgumentCollection implements ReferenceArgumentCollection {
        @Argument(doc = "The reference sequence fasta file", shortName = StandardOptionDefinitions.REFERENCE_SHORT_NAME)
        public File REFERENCE;

        @Override
        public File getReferenceFile() {
            return REFERENCE;
        };
    }

Running Tests

All Picard tests are currently written using Picard command line syntax. In order to prevent regressions related to the use of the Barclay syntax, the gradle task "test" runs all of the Picard tests twice; once using the Picard syntax, and once using the Barclay CLP and syntax. (In order to do the latter, the test command lines are automatically translated to Barclay syntax). There are also separate tasks to run the tests only with one or the other syntax (barclayTest/legacyTest).

Running one or more tests in IntelliJ only runs the tests with the default Picard syntax. In the event that a tests succeeds in IntelliJ, but fails when the gradle test task is run (i.e., when the PR is pushed), you can run/debug the test using the Barclay parser in IntelliJ by adding the following system properties to the IntelliJ configuration for the test (Run/Edit Configuration/JDK Settings/VM Options...):

-Dpicard.useLegacyParser=false -Dpicard.convertCommandLine=true

This tells Picard to use the Barlcay parser and to automatically convert the command line arguments for Barclay.