Changelog

[0.4.1] - Unreleased¶

Added¶

• seqspec auth in Python and Rust with init, path, list, and resolve subcommands.

• seqspec print -f seqspec-html, a self-contained HTML view that shows the library molecule, reads, and nested region metadata.

• Additional parity tests for Python and Rust command behavior.

• seqspec check now emits warning diagnostics for overlapping read geometry, with guidance to use seqspec index --no-overlap when needed.

• A generated examples site under docs/examples/site, with rendered assay reports, read templates, region templates, and a searchable assay catalog.

Changed¶

• seqspec upgrade now upgrades 0.3.0 specs to 0.4.0 in both implementations.

• Python and Rust now share the same core command surface for auth, check, find, file, format, index, info, init, insert, methods, modify, onlist, print, split, upgrade, and version.

• seqspec build is deprecated in both CLIs and remains as a compatibility stub.

• Older specs are loaded more permissively before upgrade, which makes 0.2.x and 0.3.x specs easier to normalize.

• seqspec onlist -s region-type now errors when matches span multiple reads in a modality. Use -s read or -s region to disambiguate.

• The maintained examples now live under docs/examples/assays, docs/examples/reads, and docs/examples/regions, with one colocated docs/examples/build_examples.py script to normalize YAML, write the manifest, and regenerate the site.

• GitHub Pages now publishes the generated examples site under /examples/ alongside the main MyST documentation site.

Fixed¶

• Rust load_spec now reads gzipped seqspec YAML.

• Python seqspec check and seqspec onlist can use auth profiles for remote resources.

• Python local gzipped onlist validation now detects .gz files correctly.

[0.4.0] - 2025-08-24¶

Added¶

• seqspec build subcommand. Generates a draft spec from a natural-language description using the existing init/insert/modify/check tools. Marked experimental.

• New validation checks for seqspec check

  • check_region_against_subregion_length

  • check_region_against_subregion_sequence

  • check_read_length_against_library

• seqspec index:

  • --no-overlap to de-duplicate regions covered by overlapping reads.

  • Target -t kb-single for single-end kallisto-bus indexing.

  • Primer ID may be any region (not only a leaf).

• seqspec print -f png now layers sequencing reads on top of the library diagram.

• load_spec supports gzipped YAML (.yaml.gz).

• seqspec check can skip specific checks; can ignore onlist when needed.

• “Loose loading” mode for seqspec check and seqspec format with captured validation errors.

• New region type: sgrna_target.

• Added private attribute to Assay, _spec_path (str). Stores the fully resolved path to the loaded spec. Used in seqspec check.

Fixed¶

• Read.get_file_by_id returned the wrong file in some cases.

• seqspec file -f paired lists all files.

• seqspec index:

  • Correct file-name indexing with -s file.

  • Correct behavior when targeting region indices.

  • Deterministic deduplication of FASTQ filenames.

  • Lists file URLs and accepts HTTPS onlists.

• seqspec onlist:

  • Local caching and remote download (handles gzip and HTTP 302).

  • Support for kallisto “multi” file format.

  • Fix for bug tracked in #68.

• Plotting fixes for single-modality figures and read overlays.

• Test suite rewritten and passing on modern Python; mocks added for remote I/O.

Changed¶

• seqspec init now initializes an empty seqspec file.

• seqspec creation simplified:

  • Create with init, then add regions/reads via insert, then modify.

  • insert/modify take lists of *Input objects. Consistent -s selector.

  • -r is deprecated in favor of -i across index, onlist, and find.

• Internal models now derive from Pydantic BaseModel. YAML tags (!Assay, !Read, !Region, !Onlist, !File) are no longer required and are stripped on load.

• Region.regions defaults to [] (not optional). Several repr and printing paths were cleaned up.

• Packaging and dev:

  • Moved to pyproject.toml; works well with uv. Versioning via setuptools_scm.

  • Formatter switched to ruff. Test runner switched to pytest.

• seqspec index internals made consistent; primer mapping works at any level of the library.

Removed¶

• spec_fn parameter from seqspec check.

• seqspec convert CLI (unimplemented).

• Legacy implicit parent_id in specs (was unused).

• tox (replaced by pytest).

Breaking changes¶

• seqspec onlist now uses urltype (not location) to decide local vs remote. Older specs must update onlist metadata.

• init no longer accepts library/read structures. You must insert regions and reads after init.

• Input flag change: prefer -i (ID) over -r across index/onlist/find. -r is deprecated and will be removed in a future release.

• Onlist/schema updates since 0.3.x (Files in Reads, file_id fields, URL checks) may require running seqspec upgrade or manual edits.

[0.3.1] - 2024-10-14¶

Added¶

• Added an option to report the full path of the URL of files if the URL type is local.

Fixed¶

• Fixed a bug in the seqspec file with the flag “-f paired” that was causing it to not list out all of the files correctly.

[0.3.0] - 2024-10-10¶

Added¶

• Added typing hints to many Assay and Region functions

• Added 'k key to seqspec info to display one of meta for metadata, sequence_spec for sequence spec, and library_spec for library spec

• Added -f format to seqspec info to enable multiple formats for displaying info

• Added support for 0 length regions in the specification

• Added ability to modify reads using seqspec modify

• seqspec init now accepts read information

• Added templates and updated documentation to myst, website

• Added new examples (e.g., dogmaseq-dig)

• Added File object to Read

• Added SeqKit, SeqProtocol, LibKit, and LibProtocol attributes

• Added option to specify multiple SeqKit, SeqProtocol, LibKit, LibProtocol for each modality

• Added name validation against known list of SeqKit, SeqProtocol, LibKit, LibProtocol

• Added new attributes to Onlist object (Onlist now contains a File object):

  • filetype

  • filesize

  • url

• Added “file_id” to the File object

• Added seqspec file command to return the list of files in the spec as paired across reads or interleaved

• Added seqspec upgrade hidden feature to upgrade v0.2.x seqspec files to v0.3.0.

Changed¶

• Updated seqspec index to read strands for chromap

• Updated seqspec split to correctly split sequence_spec

• Modified seqspec string to use min_len instead of max_len to accommodate nanopore reads

• Updated documentation on how to propose new vocabulary

• Modified the internals of seqspec onlist to manage saving the joined onlist to the -o location when specified (otherwise saves to path where spec lives).

• Renamed “location” to “urltype” in Onlist object

• Replaced -r with -i id type for all functions (deprecated -r)

• Multiple seqspec commands now require the addition of a -s selector [read, region, file]

• seqspec index can now take in reads, regions, or files and index

• seqspec modify can now add files to the template

• Updated splitseq template

Fixed¶

• Fixed seqspec onlist functionality

• Fixed error enumeration in seqspec check

Removed¶

TODO:

• Remove lib_struct

• Remove parent_id

Breaking Changes¶

• File elements are now required in Read objects and Onlist objects in version 0.3.0

[0.2.0] - 2024-04-17¶

Changed¶

• seqspec index uses primer and max length of of supplied Read

• assay_spec renamed library_spec

• Reorganize specification document

• Move contribution guidelines from SPECIFICATION.md to CONTRIBUTION.md

• Move example Regions from SPECIFCATION.md to docs/examples/regions

• seqspec index defaults to indexing reads, --region indexes regions

• Change descriptors of attributes assay_id, doi

• Assay attribute assay changed to assay_id

• Read attribute read_name changed to name

• Assay attribute publication_date changed to date

• Assay attribute sequencer changed to sequence_protocol

• Assay function get_modality changed to get_libspec

• Region function update_attr uses the max_len to generate random and onlist sequence lengths instead of min_len

• get_region_by_type changed to get_region_by_region_type to disambiguate between region_type and sequence_type

• seqspec onlist (by default) searches for onlists in the Regions intersected by the Read passed to -r.

• Support older versions of matplotlib by handling the spines[["top", "bottom"...]] structure

• Increase the number of Xs in the random region to match max_len for validation

• Update seqspec print command to use the replacement assay_id attribute instead of assay

• Implement downloading onlists via URLs and transparently decompress gzip files

• Change read_list function to take the onlist object for handling local and remote files

• Added onlist argument to specify combined barcode list file format (kallisto’s multi-file format and default cartesian product format)

Added¶

• Added sequence_spec in the Assay object

• Added Read object in the sequence_spec object

• Added sequence_spec to the seqspec json schema

• Added Read object to specification document

• Added Read generator to website GUI

• Added pattern matching to date in Assay (expected date format: DAY MONTH YEAR, where day is one or two numbers, month is the full named month starting with a Capital letter and year is the full year)

• Added library_kit to Assay object (kit that adds seq adapters)

• Added library_protocol to Assay object (library that generates insert)

• Added sequence_kit to Assay object

• Added website to view example seqspec objects

• Added get_seqspec to assay returns sequence structure for a given modality

• Added multiple checks to seqspec check

  • check read modalities exist in assay modalities

  • check primer ids from seqspec are unique and exists as region ids in libspec

  • check that the primer id exists as an atomic region (currently a strong assumption that may be relaxed in the future)

  • check properties of multiple sequence types

    • fixed and regions not null incompatible

    • joined and regions null incompatible

    • random and regions not null incompatible

    • random must have sequence of all X’s

    • onlist and onlist property null incompatible

  • check that the min len is less than or equal to the max len

  • check that the length of the sequence is between min and max len

  • Note a strong assumption in seqspec print is that the sequence have a length equal to the max_len for visualization purposes

• Added RegionCoordinate object that maps Region min/max lengths to 0-indexed positions

• seqspec onlist searches for onlists in a Region based on --region flag

• Added type annotations for join_onlists to clarify it needs a list of Onlist objects

• Added minimal tests for RegionCoordinate, project_regions_to_coordinates, run_onlist_region, run_onlist_read, and seqspec print functions

• Added list of options to CLI for -f FORMAT within seqspec onlist and seqspec print

• Added -s SEQTYPE to seqspec print to disambiguate printing sequence, library, or libseq objects. TODO wrap seqspec info into seqspec print -f info.

• Added -s SPECOBJECT to seqspec onlist. Specify specific object read, region, or region-type for finding the onlist.

• Added fetching ability for seqspec onlist from remote with IGVF credentials (credit to detrout)

Removed¶

TODO:

• Remove lib_struct

• Remove parent_id

Fixed¶

• Sequencing overlapping pairs now supported

• seqspec check correctly handles sequences lengths longer than the stated min/max range

• Fixed test for project_regions_to_coordinates

• Get the test of seqspec check working again by updating the schema for the refactored example specification YAML files and mocking fastq and barcode files

• Only return the onlist filename if it’s a local file, downloading remote lists when needed