Add deprecated command-line arguments, and switched over UG to output to

-o/--out instead of -varout.  Let's watch as our intrepid support engineer
gracefully responds to all the incoming questions of the form: "the GATK told
me to use -o instead of -varout.  What do I do?"


git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@4078 348d0f76-0448-11de-a6fe-93d51630548a

java/src/org/broadinstitute/sting/commandline/ArgumentDefinition.java

@@ -110,8 +110,8 @@ public class ArgumentDefinition {
      * @param required Whether or not this argument is required.
      * @param isFlag Whether or not this argument should be treated as a flag.
      * @param isMultiValued Whether or not this argument supports multiple values.
-     * @param componentType For multivalued arguments the type of the components.
      * @param isHidden Whether or not this argument should be hidden from the command-line argument system.
+     * @param componentType For multivalued arguments the type of the components.
      * @param exclusiveOf Whether this command line argument is mutually exclusive of other arguments.
      * @param validation A regular expression for command-line argument validation.
      * @param validOptions is there a particular list of options that's valid for this argument definition?  List them if so, otherwise set this to null. 
@@ -124,8 +124,8 @@ public class ArgumentDefinition {
                                boolean required,
                                boolean isFlag,
                                boolean isMultiValued,
-                               Class componentType,
                                boolean isHidden,
+                               Class componentType,
                                String exclusiveOf,
                                String validation,
                                List<String> validOptions) {
@@ -162,8 +162,8 @@ public class ArgumentDefinition {
                                String defaultShortName,
                                boolean isFlag,
                                boolean isMultiValued,
-                               Class componentType,
                                boolean isHidden,
+                               Class componentType,
                                List<String> validOptions) {
 
         String fullName = (String)getValue(annotation, "fullName");
@@ -190,8 +190,8 @@ public class ArgumentDefinition {
         this.required = isRequired(annotation, isFlag);
         this.isFlag = isFlag;
         this.isMultiValued = isMultiValued;
-        this.componentType = componentType;
         this.isHidden = isHidden;
+        this.componentType = componentType;
         this.exclusiveOf = getExclusiveOf(annotation);
         this.validation = getValidationRegex(annotation);
         this.validOptions = validOptions;
@@ -213,8 +213,8 @@ public class ArgumentDefinition {
                                String fieldName,
                                boolean isFlag,
                                boolean isMultiValued,
-                               Class componentType,
                                boolean isHidden,
+                               Class componentType,
                                List<String> validOptions) {
         this.ioType = ArgumentIOType.getIOType(annotation);
         this.argumentType = argumentType;
@@ -224,8 +224,8 @@ public class ArgumentDefinition {
         this.required = isRequired(annotation, isFlag);
         this.isFlag = isFlag;
         this.isMultiValued = isMultiValued;
-        this.componentType = componentType;
         this.isHidden = isHidden;
+        this.componentType = componentType;
         this.exclusiveOf = getExclusiveOf(annotation);
         this.validation = getValidationRegex(annotation);
         this.validOptions = validOptions;

java/src/org/broadinstitute/sting/commandline/ArgumentSource.java

@@ -173,7 +173,7 @@ public class ArgumentSource {
      * @return True if so.  False otherwise.
      */
     public boolean isHidden() {
-        return field.isAnnotationPresent(Hidden.class);
+        return field.isAnnotationPresent(Hidden.class) || field.isAnnotationPresent(Deprecated.class);
     }
 
     /**
@@ -184,6 +184,14 @@ public class ArgumentSource {
         return typeDescriptor instanceof MultiplexArgumentTypeDescriptor;
     }
 
+    /**
+     * Returns whether the field has been deprecated and should no longer be used.
+     * @return True if field has been deprecated.
+     */
+    public boolean isDeprecated() {
+        return field.isAnnotationPresent(Deprecated.class);
+    }
+
     /**
      * Builds out a new type descriptor for the given dependent argument as a function
      * of the containing object.

java/src/org/broadinstitute/sting/commandline/ArgumentTypeDescriptor.java

@@ -147,8 +147,8 @@ public abstract class ArgumentTypeDescriptor {
                                        source.field.getName(),
                                        source.isFlag(),
                                        source.isMultiValued(),
-                                       getCollectionComponentType(source.field),
                                        source.isHidden(),
+                                       getCollectionComponentType(source.field),
                                        getValidOptions(source) );
     }
 

java/src/org/broadinstitute/sting/commandline/ParsingEngine.java

@@ -256,7 +256,11 @@ public class ParsingEngine {
         List<ArgumentSource> argumentSources = extractArgumentSources(object.getClass());
 
         List<ArgumentSource> dependentArguments = new ArrayList<ArgumentSource>();
+
         for( ArgumentSource argumentSource: argumentSources ) {
+            if(argumentSource.isDeprecated() && argumentMatches.findMatches(argumentSource).size() > 0)
+                notifyDeprecatedCommandLineArgument(argumentSource);
+
             // If this argument source depends on other command-line arguments, skip it and make a note to process it later.
             if(argumentSource.isDependent()) {
                 dependentArguments.add(argumentSource);
@@ -272,6 +276,19 @@ public class ParsingEngine {
         }
     }
 
+    /**
+     * Notify the user that a deprecated command-line argument has been used.
+     * @param argumentSource Deprecated argument source specified by user.
+     */
+    private void notifyDeprecatedCommandLineArgument(ArgumentSource argumentSource) {
+        // Grab the first argument definition and report that one as the failure.  Theoretically, we should notify of all failures.
+        List<ArgumentDefinition> definitions = argumentSource.createArgumentDefinitions();
+        if(definitions.size() < 1)
+            throw new StingException("Internal error.  Argument source creates no definitions.");
+        ArgumentDefinition definition = definitions.get(0);
+        throw new StingException(String.format("The parameter %s is deprecated.  %s",definition.fullName,definition.doc));
+    }
+
     /**
      * Loads a single argument into the object and that objects children.
      * @param argumentMatches Argument matches to load into the object.

java/src/org/broadinstitute/sting/gatk/examples/HelloWalker.java

@@ -25,11 +25,17 @@ import org.broadinstitute.sting.gatk.walkers.LocusWalker;
 import org.broadinstitute.sting.gatk.contexts.AlignmentContext;
 import org.broadinstitute.sting.gatk.contexts.ReferenceContext;
 import org.broadinstitute.sting.gatk.refdata.RefMetaDataTracker;
+import org.broadinstitute.sting.commandline.Output;
+
+import java.io.PrintStream;
 
 /**
  * An example walker for illustrative purposes.
  */
 public class HelloWalker extends LocusWalker<Integer,Long> {
+    @Output
+    PrintStream out;
+
     /**
      * The map function runs once per single-base locus, and accepts a 'context', a
      * data structure consisting of the reads which overlap the locus, the sites over

java/src/org/broadinstitute/sting/gatk/io/stubs/SAMFileWriterArgumentTypeDescriptor.java

@@ -121,8 +121,8 @@ public class SAMFileWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        DEFAULT_ARGUMENT_SHORTNAME,
                                        false,
                                        source.isMultiValued(),
-                                       getCollectionComponentType(source.field),
                                        source.isHidden(),
+                                       getCollectionComponentType(source.field),
                                        null );
     }
 
@@ -141,10 +141,10 @@ public class SAMFileWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        false,
                                        false,
                                        false,
-                                       null,
                                        source.isHidden(),
                                        null,
                                        null,
+                                       null,
                                        null );
     }
 }

java/src/org/broadinstitute/sting/gatk/io/stubs/VCFWriterArgumentTypeDescriptor.java

@@ -74,7 +74,7 @@ public class VCFWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor {
 
     @Override
     public List<ArgumentDefinition> createArgumentDefinitions( ArgumentSource source ) {
-        return Arrays.asList( createGenotypeFileArgumentDefinition(source) );
+        return Arrays.asList( createDefaultArgumentDefinition(source) );
     }
 
     /**
@@ -103,7 +103,7 @@ public class VCFWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor {
     @Override
     public Object parse( ArgumentSource source, Class type, ArgumentMatches matches )  {
         // Get the filename for the genotype file, if it exists.  If not, we'll need to send output to out.
-        String writerFileName = getArgumentValue(createGenotypeFileArgumentDefinition(source),matches);
+        String writerFileName = getArgumentValue(createDefaultArgumentDefinition(source),matches);
         File writerFile = writerFileName != null ? new File(writerFileName) : null;
 
         // Create a stub for the given object.
@@ -113,23 +113,4 @@ public class VCFWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor {
 
         return stub;
     }
-
-    /**
-     * Gets the definition of the argument representing the BAM file itself.
-     * @param source Argument source for the BAM file.  Must not be null.
-     * @return Argument definition for the BAM file itself.  Will not be null.
-     */
-    private ArgumentDefinition createGenotypeFileArgumentDefinition(ArgumentSource source) {
-        Annotation annotation = this.getArgumentAnnotation(source);
-
-        return new ArgumentDefinition( annotation,
-                                       source.field.getType(),
-                                       "variants_out",
-                                       "varout",
-                                       false,
-                                       source.isMultiValued(),
-                                       getCollectionComponentType(source.field),
-                                       source.isHidden(),
-                                       null );
-    }
 }

java/src/org/broadinstitute/sting/gatk/walkers/genotyper/UnifiedGenotyper.java

@@ -52,9 +52,13 @@ public class UnifiedGenotyper extends LocusWalker<VariantCallContext, UnifiedGen
     @ArgumentCollection private UnifiedArgumentCollection UAC = new UnifiedArgumentCollection();
 
     // control the output
-    @Argument(doc = "File to which variants should be written", required = false)
+    @Output(doc="File to which variants should be written",required=false)
     public VCFWriter writer = null;
 
+    @Argument(fullName="variants_out",shortName="varout",doc="Please use --out instead",required=false)
+    @Deprecated
+    public boolean varout;
+
     @Argument(fullName = "verbose_mode", shortName = "verbose", doc = "File to print all of the annotated and detailed debugging output", required = false)
     protected File verboseFile = null;
 

java/test/org/broadinstitute/sting/gatk/walkers/genotyper/UnifiedGenotyperIntegrationTest.java

@@ -23,7 +23,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
     @Test
     public void testMultiSamplePilot1Joint() {
         WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "low_coverage_CEU.chr1.10k-11k.bam -varout %s -L 1:10,022,000-10,025,000", 1,
+                baseCommand + " -I " + validationDataLocation + "low_coverage_CEU.chr1.10k-11k.bam -o %s -L 1:10,022,000-10,025,000", 1,
                 Arrays.asList("99ff7d7031cc5038ec95f7872311c6b5"));
         executeTest("testMultiSamplePilot1 - Joint Estimate", spec);
     }
@@ -31,7 +31,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
     @Test
     public void testMultiSamplePilot2Joint() {
         WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "pilot2_daughters.chr20.10k-11k.bam -varout %s -L 20:10,000,000-10,050,000", 1,
+                baseCommand + " -I " + validationDataLocation + "pilot2_daughters.chr20.10k-11k.bam -o %s -L 20:10,000,000-10,050,000", 1,
                 Arrays.asList("497ac35ab217d5c0c21ee7733219ef5d"));
         executeTest("testMultiSamplePilot2 - Joint Estimate", spec);
     }
@@ -39,7 +39,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
     @Test
     public void testSingleSamplePilot2Joint() {
         WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,100,000", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,100,000", 1,
                 Arrays.asList("29670c1c6ae4a1e7fc27c4d78c434a72"));
         executeTest("testSingleSamplePilot2 - Joint Estimate", spec);
     }
@@ -55,17 +55,17 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
         String md5 = "c6a4347807f624c2a31fb95080ed68b8";
 
         WalkerTest.WalkerTestSpec spec1 = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,075,000", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,075,000", 1,
                 Arrays.asList(md5));
         executeTest("test parallelization (single thread)", spec1);
 
         WalkerTest.WalkerTestSpec spec2 = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,075,000 -nt 2", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,075,000 -nt 2", 1,
                 Arrays.asList(md5));
         executeTest("test parallelization (2 threads)", spec2);
 
         WalkerTest.WalkerTestSpec spec3 = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,075,000 -nt 4", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,075,000 -nt 4", 1,
                 Arrays.asList(md5));
         executeTest("test parallelization (4 threads)", spec3);
     }
@@ -87,7 +87,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
 
         for ( Map.Entry<String, String> entry : e.entrySet() ) {
             WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,010,000 " + entry.getKey(), 1,
+                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,010,000 " + entry.getKey(), 1,
                     Arrays.asList(entry.getValue()));
             executeTest(String.format("testParameter[%s]", entry.getKey()), spec);
         }
@@ -96,12 +96,12 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
     @Test
     public void testConfidence() {
         WalkerTest.WalkerTestSpec spec1 = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,010,000 -stand_call_conf 10 ", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,010,000 -stand_call_conf 10 ", 1,
                 Arrays.asList("0937f45888cab1aacfa129d45d82384f"));
         executeTest("testConfidence1", spec1);
 
         WalkerTest.WalkerTestSpec spec2 = new WalkerTest.WalkerTestSpec(
-                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,010,000 -stand_emit_conf 10 ", 1,
+                baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,010,000 -stand_emit_conf 10 ", 1,
                 Arrays.asList("99419b1852b744092bc7418747dc78f3"));
         executeTest("testConfidence2", spec2);
     }
@@ -119,7 +119,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
 
         for ( Map.Entry<Double, String> entry : e.entrySet() ) {
             WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,100,000 --heterozygosity " + entry.getKey(), 1,
+                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,100,000 --heterozygosity " + entry.getKey(), 1,
                     Arrays.asList(entry.getValue()));
             executeTest(String.format("testHeterozyosity[%s]", entry.getKey()), spec);
         }
@@ -139,7 +139,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
 
         for ( Map.Entry<String, String> entry : e.entrySet() ) {
             WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
-                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -varout %s -L 1:10,000,000-10,100,000 -bm " + entry.getKey(), 1,
+                    baseCommand + " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.SLX.bam -o %s -L 1:10,000,000-10,100,000 -bm " + entry.getKey(), 1,
                     Arrays.asList(entry.getValue()));
             executeTest(String.format("testOtherBaseCallModel[%s]", entry.getKey()), spec);
         }
@@ -155,7 +155,7 @@ public class UnifiedGenotyperIntegrationTest extends WalkerTest {
         WalkerTest.WalkerTestSpec spec = new WalkerTest.WalkerTestSpec(
                 baseCommand +
                         " -I " + validationDataLocation + "NA12878.1kg.p2.chr1_10mb_11_mb.allTechs.bam" +
-                        " -varout %s" +
+                        " -o %s" +
                         " -L 1:10,000,000-10,100,000",
                 1,
                 Arrays.asList("ce22e33e550ea62d8786deb38a70049a"));