New -s, --samples option to include the #CHROM header line with samples.

This option works the same way as `-n, --records` but includes the #CHROM header
line with samples. Running with `-s 0` alone outputs the #CHROM header line only

Author: pd3

NEWS

@@ -28,6 +28,10 @@ Changes affecting specific commands:
     - New `-*, --keep-unseen-allele` option to output the unobserved allele <*>,
       intended for gVCF.
 
+* bcftools head
+
+    - New `-s, --samples` option to include the #CHROM header line with samples.
+
 * bcftools gtcheck
 
     - Add output options `-o, --output` and `-O, --output-type`

doc/bcftools.txt

@@ -1795,6 +1795,12 @@ present, but it never adds version or command line information itself.
     Also display the first 'INT' variant records.
     By default, no variant records are displayed.
 
+*-s, --samples* 'INT'::
+    Display the first 'INT' variant records including the last #CHROM header line with samples.
+    Running with *-s 0* alone outputs the #CHROM header line only. Note that
+    the list of samples, with each sample per line, can be obtained with `bcftools query` using
+    the option *-l, --list-samples*.
+
 
 [[index]]
 === bcftools index ['OPTIONS']  'in.bcf'|'in.vcf.gz'

test/head.1.out

@@ -0,0 +1 @@
+#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	sample1	sample2

test/head.2.out

@@ -0,0 +1,2 @@
+#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	sample1	sample2
+chr1	212740	.	A	G,<*>	0	.	DP=73;I16=0,0,39,4,0,0,2743,192525,0,0,2580,154800,0,0,825,18621;QS=0,2,0;VDB=0.520868;SGB=-1.38232;MQSB=1;MQ0F=0	PL:DP:AD	255,72,0,255,72,255:24:0,24,0	255,57,0,255,57,255:19:0,19,0

test/head.3.out

@@ -0,0 +1,5 @@
+##fileformat=VCFv4.2
+##FILTER=<ID=PASS,Description="All filters passed">
+#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	sample1	sample2
+chr1	212740	.	A	G,<*>	0	.	DP=73;I16=0,0,39,4,0,0,2743,192525,0,0,2580,154800,0,0,825,18621;QS=0,2,0;VDB=0.520868;SGB=-1.38232;MQSB=1;MQ0F=0	PL:DP:AD	255,72,0,255,72,255:24:0,24,0	255,57,0,255,57,255:19:0,19,0
+chr1	320055	.	A	<*>	0	.	DP=101;I16=52,9,0,0,4116,300666,0,0,3660,219600,0,0,1281,29849,0,0;QS=2,0;MQSB=1;MQ0F=0	PL:DP:AD	0,87,255:29:29,0	0,96,255:32:32,0

test/test.pl

@@ -361,6 +361,9 @@
 run_test(\&test_vcf_view,$opts,in=>'view.sites',out=>'view.sites.1.out',args=>'',tgts=>'view.sites.txt');
 run_test(\&test_vcf_view,$opts,in=>'view.sites',out=>'view.sites.1.out',args=>'',tgts=>'view.sites.txt.gz');
 run_test(\&test_vcf_head,$opts,in=>'mpileup.2.vcf',in_nheaders=>22);
+run_test(\&test_vcf_head2,$opts,in=>'mpileup.2',out=>'head.1.out',args=>'-s0');
+run_test(\&test_vcf_head2,$opts,in=>'mpileup.2',out=>'head.2.out',args=>'-s1');
+run_test(\&test_vcf_head2,$opts,in=>'mpileup.2',out=>'head.3.out',args=>'-s2 -h2');
 run_test(\&test_vcf_call,$opts,in=>'mpileup',out=>'mpileup.1.out',args=>'-mv');
 run_test(\&test_vcf_call,$opts,in=>'mpileup',out=>'mpileup.2.out',args=>'-mg0');
 run_test(\&test_vcf_call,$opts,in=>'mpileup',out=>'mpileup.3.out',args=>'-mv -S {PATH}/mpileup.3.samples');
@@ -1516,6 +1519,13 @@ sub test_vcf_head
     test_cmd($opts, %args, gen_head_output(5, 5, "fiveboth", $infile),
              cmd => "$$opts{bin}/bcftools head -h 5 -n 5 < $infile");
 }
+sub test_vcf_head2
+{
+    my ($opts,%args) = @_;
+    bgzip_tabix_vcf($opts,$args{in});
+    test_cmd($opts,%args,cmd=>"$$opts{bin}/bcftools head $args{args} $$opts{tmp}/$args{in}.vcf.gz");
+    test_cmd($opts,%args,cmd=>"$$opts{bin}/bcftools view --no-version -Ob $$opts{tmp}/$args{in}.vcf.gz | $$opts{bin}/bcftools head $args{args}");
+}
 sub test_vcf_call
 {
     my ($opts,%args) = @_;

vcfhead.c

@@ -1,6 +1,7 @@
 /*  vcfhead.c -- view VCF/BCF file headers.
 
     Copyright (C) 2021 University of Glasgow.
+    Copyright (C) 2023 Genome Research Ltd.
 
     Author: John Marshall <[email protected]>
 
@@ -41,30 +42,36 @@ int main_vcfhead(int argc, char *argv[])
 "Usage: bcftools head [OPTION]... [FILE]\n"
 "\n"
 "Options:\n"
-"  -h, --headers INT   Display INT header lines [all]\n"
-"  -n, --records INT   Display INT variant record lines [none]\n"
+"  -h, --headers INT    Display INT header lines [all]\n"
+"  -n, --records INT    Display INT variant record lines [none]\n"
+"  -s, --samples INT    Display INT records starting with the #CHROM header line [none]\n"
 "\n";
 
     static const struct option loptions[] = {
         { "headers", required_argument, NULL, 'h' },
         { "records", required_argument, NULL, 'n' },
+        { "samples", required_argument, NULL, 's' },
         { NULL, 0, NULL, 0 }
     };
 
     int all_headers = 1;
+    int samples = 0;
     uint64_t nheaders = 0;
     uint64_t nrecords = 0;
 
     int c, nargs;
-    while ((c = getopt_long(argc, argv, "h:n:", loptions, NULL)) >= 0)
+    while ((c = getopt_long(argc, argv, "h:n:s:", loptions, NULL)) >= 0)
         switch (c) {
         case 'h': all_headers = 0; nheaders = strtoull(optarg, NULL, 0); break;
         case 'n': nrecords = strtoull(optarg, NULL, 0); break;
+        case 's': nrecords = strtoull(optarg, NULL, 0); samples = 1; break;
         default:
             fputs(usage, stderr);
             return EXIT_FAILURE;
         }
 
+    if ( samples && all_headers ) all_headers = 0;
+
     nargs = argc - optind;
     if (nargs == 0 && isatty(STDIN_FILENO)) {
         fputs(usage, stdout);
@@ -99,17 +106,34 @@ int main_vcfhead(int argc, char *argv[])
         bcf_hdr_format(hdr, 0, &str);
         fputs(ks_str(&str), stdout);
     }
-    else if (nheaders > 0) {
+    else if (nheaders > 0 || samples ) {
         bcf_hdr_format(hdr, 0, &str);
         char *lim = str.s;
         uint64_t n;
+        int samples_printed = 0;
         for (n = 0; n < nheaders; n++) {
+            if ( samples && !strncmp(lim,"#CHROM\t",7) ) samples_printed = 1;
             lim = strchr(lim, '\n');
             if (lim) lim++;
             else break;
         }
-        if (lim) *lim = '\0';
-        fputs(ks_str(&str), stdout);
+        if ( nheaders )
+        {
+            char tmp;
+            if (lim) { tmp = *lim; *lim = '\0'; }
+            fputs(ks_str(&str), stdout);
+            if (lim) *lim = tmp;
+        }
+        if ( lim && samples && !samples_printed )
+        {
+            while ( lim && *lim )
+            {
+                if ( !strncmp(lim,"#CHROM\t",7) ) { fputs(lim, stdout); break; }
+                lim = strchr(lim, '\n');
+                if (lim) lim++;
+                else break;
+            }
+        }
     }
 
     if (nrecords > 0) {