what does -w do in bctools isec?

[complexgenome]

Hi there,
I'd like to take intersection of 3 VCF files with variants in at least two. I use below command:

bcftools isec -c none -n +2 MM-0574.mutect2out.vcf.gz lancet.vcf.gz somatic_merged.vcf.gz -w 1 -Ov -o hh.vcf

that is, Output format in uncompressed VCF, at least two VCFs.
I'm unable to understand how does -w 1 help. It works with -w 2 as well.

It is confusing for me to understand:
list of input files to output given as 1-based indices. With -p and no -w, all files are written
What it is trying to do?

[pd3]

Mmm, I'd hope the description was clear, but apparently it is not.

If you look inside the output files generated with -w 1 or -w 2, you should notice that the first contains records from the first file, the second contains records from the second file. This should become obvious when the two input files are very different, for example contain different samples or different annotations.

The program will never mix together lines from different input files, as that would break things when samples are present.

Any suggestions how to improve the language of the documentation are welcome.

[complexgenome]

@pd3 Thank you for your reply.

If I use the following:
bcftools isec -n +2 MM-0574.mutect2out.vcf.gz somatic_merged.vcf.gz lancet_dict.vcf.gz -Ov -c none -w 1 -w 2 -w 3 -o file.vcf
I get a file.vcf with high number of SNPs/lines:

grep -vc "#" file.vcf
2410

What is the above command doing?

If I run the isec with -p I get 3078 lines in dir/sites.txt file:

bcftools isec -n +2 MM-0574.mutect2out.vcf.gz somatic_merged.vcf.gz lancet_dict.vcf.gz -p dir -c none

grep -vc "#" dir/*.vcf dir/sites.txt

dir/0000.vcf:1696
dir/0001.vcf:2611
dir/0002.vcf:2410
dir/sites.txt:3078

What is the correct way to use isec with to generate a vcf.

For suggestions, including examples would be great with an intersection of 3 files and put -w 1 and then -w 1 -w 2 .

[pd3]

The option -w should be given only once, as it accepts a list of indices, for example -w 1,2,3. In your first command the program silently uses the last occurrence -w 3. I just pushed a commit that will complain if the user attempts to use it multiple times.

Apart from that I do not understand what else is unclear and the usage page comes with examples. I hope this clarifies it, please shout if not