Skip to content

seqex

ipyrad2 seqex is an experimental exporter for complete, delimited loci in an assembly HDF5 file. It applies the same locus and site coverage requirements independently to every locus and can write accepted loci as one multi-locus file, one concatenated matrix, or separate files.

The established lex and wex commands remain available while the behavior and performance of seqex are evaluated.

Filtering order

For every complete locus 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.

Regions and BED intervals select whole overlapping loci. They do not clip sequence at interval boundaries; use wex when exact clipping is required.

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 sample^population. Its short form is -a.

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.

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

See also