Skip to content

seqex

ipyrad2 seqex exports sequence alignments from an assembly HDF5 file. It applies locus and site coverage filters independently to every selected locus and can write accepted loci as one multi-locus file, one concatenated matrix, or separate files for each locus.

Window selection and clipping

The form of -w/--windows determines whether loci remain complete or are clipped automatically:

  • Omitting -w selects complete loci from every scaffold.
  • Scaffold names and regular expressions select complete overlapping loci.
  • scaffold:start-end regions clip loci to the exact 1-based, inclusive interval boundaries.
  • BED files clip loci to each 0-based, half-open BED interval after coordinate conversion.

When one coordinate interval crosses several loci, each locus intersection is an independent unit. Two disjoint intervals within the same source locus also produce two independent clipped fragments. These units can be filtered, sampled with -N, concatenated, or written separately like complete loci.

Filtering order

For every complete locus or clipped fragment selected by -w/--windows, seqex:

  1. Counts a sample as present when it has at least one called base in the raw locus.
  2. Rejects the locus unless sample presence satisfies -m, or each population satisfies --minmap.
  3. Removes sites that fail those same coverage thresholds.
  4. Removes samples whose missing fraction exceeds -r.
  5. Applies -L/--min-length to the retained site count.
  6. Randomly retains at most -N/--max-loci accepted loci, when requested.

Both -L and -N are disabled by default. A random seed supplied with -s makes sampling reproducible. Randomly selected loci are written in their original genomic order.

Output layouts

With neither -C nor -X, one file contains independent locus records:

  • PHYLIP writes consecutive alignment matrices.
  • NEXUS writes one named DATA block per locus.
  • FASTA writes unique identifiers in the form sample|locus.

Use -C/--concatenate to append loci into one matrix. Samples omitted from an individual locus receive an N block, and -r is then applied once more across the complete matrix. Concatenated boundaries are recorded in the stats file.

Use -X/--split to write one file per accepted locus. -C and -X are mutually exclusive, and split output cannot be written to stdout.

With an IMAP, --append-population changes output names to population^sample. Its short form is -a. This ordering is compatible with BPP, which interprets the value after the caret as the individual identifier.

Parallel filtering

Use -c/--cores to filter batches of loci in parallel. The default is one core. Worker processes read and filter bounded HDF5 batches; the parent process restores genomic order, applies seeded locus sampling, and writes output. Consequently, the same -s seed selects the same loci regardless of the core count.

Statistics

The stats report includes the total sites and sequence characters written, the number of non-missing bases, and full-matrix non-missing occupancy. Full-matrix occupancy treats a sample omitted from a retained locus as missing. A per-sample table reports population, final output status, loci written, loci removed by -r, non-missing bases, and occupancy. The summary records the clipping mode and the original values passed to -w/--windows, without expanding regexes or BED files. Each written-locus row records the source locus, resolved selected window, output coordinates, and whether the sequence was clipped. The same structured fields are available in the JSON report.

Completion messages describe whether loci were written as independent records, concatenated into one alignment, or split among separate files. The stats-report path is logged separately. Samples removed by -r are also reported.

Examples

Write all accepted loci to one multi-locus PHYLIP file:

ipyrad2 seqex -d assembly.hdf5 -o output-seqex -m 4

Select a reproducible sample of 500 loci at least 150 retained sites long:

ipyrad2 seqex -d assembly.hdf5 -o output-seqex -N 500 -s 123 -L 150 -c 4 -O nex

Write a concatenated FASTA matrix with population-appended names:

ipyrad2 seqex -d assembly.hdf5 -i imap.tsv -g minmap.tsv -a -C -O fa

Write one PHYLIP file per locus overlapping two scaffolds:

ipyrad2 seqex -d assembly.hdf5 -w Chr01 Chr02 -X

Write one concatenated alignment clipped to exact BED intervals:

ipyrad2 seqex -d assembly.hdf5 -w windows.bed -C -O phy

See also