Add options --samples-list and --samples-file

This is to allow renaming samples from a list of samples on command line,
rather than from a file of sample names. Unfortunately, the existing
option `-s, --samples` conflicts with the rest of bcftools, therefore
this is added as

    -n, --samples-list LIST    New sample names given as a comma-separated list
    -N, --samples-file FILE    New sample names in a file, see the man page for details

The old option remains valid but is not advertised in the usage page.

Resolves #2383

Author: pd3

NEWS

@@ -1,5 +1,14 @@
 ## Release a.b
 
+
+Changes affecting specific commands:
+
+* bcftools reheader
+
+    - Add options `--samples-list` and `--samples-file` to allow renaming samples from a list of
+      samples on command line, rather than from a file of sample names (#2383)
+
+
 ## Release 1.22 (30th May 2025)
 
 

doc/bcftools.txt

@@ -3325,17 +3325,21 @@ Modify header of VCF/BCF files, change sample names.
 *-h, --header* 'FILE'::
     new VCF header
 
-*-o, --output* 'FILE'::
-    see *<<common_options,Common Options>>*
+*-n, --samples-list* 'LIST'::
+    comma-separated list of new sample names
 
 *-s, --samples* 'FILE'::
+*-N, --samples-file* 'FILE'::
     new sample names, one name per line, in the same order as they appear
     in the VCF file. Alternatively, only samples which need to be renamed
     can be listed as "old_name new_name\n" pairs separated by whitespaces,
     each on a separate line. If a sample name contains spaces, the
     spaces can be escaped using the backslash character, for example
     "Not\ a\ good\ sample\ name".
 
+*-o, --output* 'FILE'::
+    see *<<common_options,Common Options>>*
+
 *-T, --temp-prefix* 'PATH'::
     this option is ignored, but left for compatibility with earlier versions of bcftools.
 

reheader.c

@@ -49,6 +49,7 @@ THE SOFTWARE.  */
 typedef struct _args_t
 {
     char **argv, *fname, *samples_fname, *header_fname, *output_fname;
+    int samples_is_file;
     char *fai_fname;
     htsFile *fp;
     faidx_t *fai;
@@ -204,6 +205,14 @@ static void update_from_fai(faidx_t *fai, kstring_t *hdr_txt)
     khash_str2int_destroy_free(chr_seen);
 }
 
+static char **read_samples(char *fname, int is_file, int *nsamples)
+{
+    char **samples = hts_readlist(fname, is_file, nsamples);
+    if ( !samples && !*nsamples )
+        error("Error parsing the %s %s \"%s\"\n", is_file?"--samples-file":"--samples-list",is_file?"file":"list",fname);
+    return samples;
+}
+
 static void read_header_file(char *fname, kstring_t *hdr)
 {
     kstring_t tmp = {0,0,0};
@@ -389,10 +398,7 @@ static void reheader_vcf_gz(args_t *args)
     int nsamples = 0;
     char **samples = NULL;
     if ( args->samples_fname )
-    {
-        samples = hts_readlines(args->samples_fname, &nsamples);
-        if ( !samples || !nsamples ) error("Error reading the --samples file \"%s\"\n", args->samples_fname);
-    }
+        samples = read_samples(args->samples_fname, args->samples_is_file, &nsamples);
     if ( args->header_fname )
     {
         free(hdr.s); hdr.s = NULL; hdr.l = hdr.m = 0;
@@ -452,10 +458,7 @@ static void reheader_vcf(args_t *args)
     int nsamples = 0;
     char **samples = NULL;
     if ( args->samples_fname )
-    {
-        samples = hts_readlines(args->samples_fname, &nsamples);
-        if ( !samples || !nsamples ) error("Error reading the --samples file \"%s\"\n", args->samples_fname);
-    }
+        samples = read_samples(args->samples_fname, args->samples_is_file, &nsamples);
     if ( args->header_fname )
     {
         free(hdr.s); hdr.s = NULL; hdr.l = hdr.m = 0;
@@ -563,10 +566,7 @@ static void reheader_bcf(args_t *args, int is_compressed)
     int i, nsamples = 0;
     char **samples = NULL;
     if ( args->samples_fname )
-    {
-        samples = hts_readlines(args->samples_fname, &nsamples);
-        if ( !samples || !nsamples ) error("Error reading the --samples file \"%s\"\n", args->samples_fname);
-    }
+        samples = read_samples(args->samples_fname, args->samples_is_file, &nsamples);
     if ( args->header_fname )
     {
         free(htxt.s); htxt.s = NULL; htxt.l = htxt.m = 0;
@@ -664,9 +664,10 @@ static void usage(args_t *args)
     fprintf(stderr, "    -f, --fai FILE             Update sequences and their lengths from the .fai file\n");
     fprintf(stderr, "    -h, --header FILE          New header\n");
     fprintf(stderr, "    -o, --output FILE          Write output to a file [standard output]\n");
-    fprintf(stderr, "    -s, --samples FILE         New sample names\n");
+    fprintf(stderr, "    -n, --samples-list LIST    New sample names given as a comma-separated list\n");
+    fprintf(stderr, "    -N, --samples-file FILE    New sample names in a file, see the man page for details\n");
     fprintf(stderr, "    -T, --temp-prefix PATH     Ignored; was template for temporary file name\n");
-    fprintf(stderr, "        --threads INT          Use multithreading with <int> worker threads (BCF only) [0]\n");
+    fprintf(stderr, "        --threads INT          Use multithreading with INT worker threads (BCF only) [0]\n");
     fprintf(stderr, "    -v, --verbosity INT        Verbosity level\n");
     fprintf(stderr, "\n");
     fprintf(stderr, "Example:\n");
@@ -695,11 +696,13 @@ int main_reheader(int argc, char *argv[])
         {"output",1,0,'o'},
         {"header",1,0,'h'},
         {"samples",1,0,'s'},
+        {"samples-file",1,0,'N'},
+        {"samples-list",1,0,'n'},
         {"threads",1,NULL,1},
         {"verbosity",required_argument,NULL,'v'},
         {0,0,0,0}
     };
-    while ((c = getopt_long(argc, argv, "s:h:o:f:T:v:",loptions,NULL)) >= 0)
+    while ((c = getopt_long(argc, argv, "s:h:o:f:T:v:N:n:",loptions,NULL)) >= 0)
     {
         switch (c)
         {
@@ -710,7 +713,9 @@ int main_reheader(int argc, char *argv[])
             case 'T': break; // unused - was temp file prefix
             case 'f': args->fai_fname = optarg; break;
             case 'o': args->output_fname = optarg; break;
-            case 's': args->samples_fname = optarg; break;
+            case 's': args->samples_fname = optarg; args->samples_is_file = 1; break;
+            case 'N': args->samples_fname = optarg; args->samples_is_file = 1; break;
+            case 'n': args->samples_fname = optarg; args->samples_is_file = 0; break;
             case 'h': args->header_fname = optarg; break;
             case '?': usage(args); break;
             default: error("Unknown argument: %s\n", optarg);

test/test.pl

@@ -889,6 +889,8 @@
 run_test(\&test_vcf_concat,$opts,in=>['concat.5.a','concat.5.b','concat.5.c'],out=>'concat.5.3.out',do_bcf=>1,args=>'-G -a -D');
 run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.1.out',header=>'reheader.hdr');
 run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.2.out',samples=>'reheader.samples');
+run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.2.out',args=>'-N {PATH}/reheader.samples');
+run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.2.out',args=>'-n AAA,BBB');
 run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.2.out',samples=>'reheader.samples2');
 run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.3.out',samples=>'reheader.samples3');
 run_test(\&test_vcf_reheader,$opts,in=>'reheader',out=>'reheader.4.out',samples=>'reheader.samples4');