_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Features * augur.io.read_metadata: Added a new parameter `keep_id_as_column` to keep the resolved id column as a column in addition to setting it as the DataFrame index. [#1917][] (@victorlin) * subsample: Filepaths in the config file can now be relative to the config file's parent directory in addition to the current working directory. Custom directories can also be specified using a new command line option `--search-paths` or environment variable `AUGUR_SEARCH_PATHS`. [#1897][] (@victorlin) * A helper function – `augur.subsample.get_referenced_files` – has been added to optimize usage of `augur subsample` in Snakemake workflows. This is experimental and not yet part of the public API. [#1918][] (@victorlin) ### Bug fixes * filter: Previously, `--query`, `--exclude-where`, and `--include-where` did not work for the id column (`strain`, `name`, or other from `--metadata-id-columns`). This has been fixed. [#1915][] (@corneliusroemer, @victorlin) * export v2: Support export of URLs for non-string values. [#1926][] (@joverlee521) [#1897]: https://github.com/nextstrain/augur/issues/1897 [#1915]: https://github.com/nextstrain/augur/issues/1915 [#1917]: https://github.com/nextstrain/augur/pull/1917 [#1918]: https://github.com/nextstrain/augur/pull/1918 [#1926]: https://github.com/nextstrain/augur/pull/1926

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme * A new command, `augur subsample`, supports complex subsampling using file-based configuration. See the updated [Filtering and Subsampling guide][] for a comparison with `augur filter`. [#635][] (@victorlin) [#635]: https://github.com/nextstrain/augur/issues/635 [Filtering and Subsampling guide]: https://docs.nextstrain.org/en/latest/guides/bioinformatics/filtering-and-subsampling.html

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Features * schema: Allow parentheses (`()`) in gene names. [#1819][] (@kimandrews) * geolocation rules: Add rules to define region per country to ensure that regions are labelled for all countries. This is especially useful for data sources that do not include region in the metadata. [#1844][] (@joverlee521) * support numpy v2 in addition to v1. [#1855][] (@corneliusroemer) * support for Python 3.13. [#1857][] (@corneliusroemer) * tree: Prefer `iqtree3` binary over `iqtree2` and `iqtree` when available. [#1875][] (@joverlee521) * export v2: URLs encoded in metadata (both TSV and node-data JSONs) will be associated with the value in the exported JSON. Given a column/key `<X>` then a valid URL in a column/key named `<X>__url` will be automatically used. This allows values to be a clickable link when viewed in Auspice. [#1852][] (@jameshadfield) ### Bug fixes * filter: Improved speed of using `--group-by month` on large datasets. [#1845][] (@victorlin) * merge: Added validation to require at least two sequence inputs for merging, consistent with metadata merging behavior. [#1865][] (@victorlin) * validate: Send all log messages to `stderr`. [#1869][] (@victorlin) * validate: only print the entire merged Auspice config to `stderr` when there's a validation error. [#1878][](@joverlee521) [#1819]: https://github.com/nextstrain/augur/pull/1819 [#1844]: https://github.com/nextstrain/augur/pull/1844 [#1845]: https://github.com/nextstrain/augur/pull/1845 [#1852]: https://github.com/nextstrain/augur/pull/1852 [#1855]: https://github.com/nextstrain/augur/pull/1855 [#1857]: https://github.com/nextstrain/augur/pull/1857 [#1865]: https://github.com/nextstrain/augur/issues/1865 [#1869]: https://github.com/nextstrain/augur/pull/1869 [#1875]: https://github.com/nextstrain/augur/pull/1875 [#1878]: https://github.com/nextstrain/augur/pull/1878

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Features * schema: Allow full stop character (`.`) in gene names. [#955][] (@jameshadfield) ### Bug fixes * filter: Improved speed of using `--group-by`, `--min-date`, and `--max-date` on large datasets. [#1792][], [#1811][] (@victorlin) [#955]: https://github.com/nextstrain/augur/pull/955 [#1792]: https://github.com/nextstrain/augur/pull/1792 [#1811]: https://github.com/nextstrain/augur/pull/1811

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Major Changes * `augur mask --mask`, `augur tree --exclude-sites`: BED files with inconsistent CHROM values (i.e., values in the first column of data lines) will throw an error, as Augur (implicitly) expects to be working on a single piece of DNA (chromosome, segment, etc), and multiple CHROM values in a BED file indicate a violation of this expectation. This is a breaking change. [#945][] (@genehack) * filter: Empty values in the metadata id column will result in an error that can only be resolved by editing the metadata file or by specifying a different id column with `--metadata-id-columns`. [#1807][] (@joverlee521) ### Bug fixes * `augur mask --mask`, `augur tree --exclude-sites`: Providing an empty BED file, or one with only header lines and no data lines, will no longer cause an error to be thrown. [#945][] (@genehack) * `augur.utils.read_bed_file()` was rewritten for increased compliance with the BED file specification. In particular, header line dectection is improved and multiple header lines are now supported. [#945][] (@genehack) * export v2: Improved the error message that is displayed when the metadata index column has duplicated values [#1791][] (@genehack) * tree: Improved help text for `--tree-builder-args` to explain some IQ-TREE options won't work because of defline rewriting [#875][] (@genehack) * export v2: Automatically rename fields within the `filters` and `colorings` configs of the provided auspice config file to match the renamed fields in the exported nodes. [#1804][] (@joverlee521) * export v2: Divergence values are now exported with increased precision, showing up to 6 significant digits instead of 3. [#1801][] (@rneher) [#875]: https://github.com/nextstrain/augur/issues/875 [#945]: https://github.com/nextstrain/augur/issues/945 [#1791]: https://github.com/nextstrain/augur/issues/1791 [#1801]: https://github.com/nextstrain/augur/pull/1801 [#1804]: https://github.com/nextstrain/augur/pull/1804 [#1807]: https://github.com/nextstrain/augur/pull/1807

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Bug fixes * filter: Removed the note that appeared in output when running with `--sequences` and without `--sequence-index`. The help text of both options has been updated to clarify the relationship between the two. [#1797][] (@victorlin) [#1797]: https://github.com/nextstrain/augur/pull/1797

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Major Changes *Note: The following breaking changes were effective as of version 29.1.0.* * filter: Date values in `<year>-<month>` format with more than 4 digits in the year (e.g. `02025-04`) or more than 2 digits in the month (e.g. `2025-004`) are no longer supported. Support for these was unintentional, but it worked in practice. [#1786][] (@victorlin) * filter: Date values in `<year>-<month>-<day>` format that fall outside of valid date boundaries now fail with an error. For example, `2025-00-01` is invalid. Previously, all date parts were treated categorically without date validation so `month=0` was its own category. [#1786][] (@victorlin) * filter: Date values in `<year>-<month>` format that fall outside of valid date boundaries are now auto-converted to the closest date. For example, `2025-00` will be auto-converted to `2025-01`. Previously, all date parts were treated categorically without date validation so `month=0` was its own category. It will now be treated as `month=1`. This is a side-effect of the change in 29.1.0 that switched to the same internal date parsing function that is used by other commands. A future major version may change behavior to fail with an error to better align with handling of `<year>-<month>-<day>`. [#1774][] (@victorlin) ### Bug fixes * filter: version 29.1.0 inadvertently dropped support for date values in `<year>-<month>` or `<year>-<month>-<day>` format that are not in `YYYY-MM` or `YYYY-MM-DD` format. Support for some values has been restored. See the "Major Changes" section for details on which values are explicitly no longer supported. [#1785][] (@victorlin) [#1785]: https://github.com/nextstrain/augur/issues/1785 [#1786]: https://github.com/nextstrain/augur/pull/1786

_These release notes are automatically extracted from the full [changelog][]._ [changelog]: https://github.com/nextstrain/augur/blob/-/CHANGES.md#readme ### Features * export v2: Allow multiple auspice config files (`--auspice-config`) which are merged together. Note that the merging of lists extends the original list, although elements representing the same data are overwritten instead. You can optionally write out this merged config via `--output-auspice-config` for debugging purposes. [#1756][] (@jameshadfield) ### Bug fixes * titers: Improve error messages when titer models do not have enough data. [#1769][] (@huddlej) * align: Remove extra logs for insertions since the coordinates are output the *.insertions.csv. [#1772][] (@joverlee521) * filter: Fixed an error with weighted sampling by `year`. [#1776][] (@victorlin) * filter: Previously, subsampling with `--group-by` `year` or `month` would crash on numeric dates. This has been fixed by switching to the same internal date parsing function that is used by other commands. [#1774][] (@victorlin) * filter: Made a small adjustment to use pandas's `"string"` dtype alias when processing values in metadata. [#1782][] (@victorlin) * filter: Options `--output` and `-o` have been deprecated and will now show a warning message. See [DEPRECATED.md](./DEPRECATED.md) for details. [#1622][] (@victorlin) * Updated outdated documentation on supported date formats in metadata. [#882][] (@victorlin) [#882]: https://github.com/nextstrain/augur/issues/882 [#1622]: https://github.com/nextstrain/augur/pull/1622 [#1756]: https://github.com/nextstrain/augur/pull/1756 [#1769]: https://github.com/nextstrain/augur/pull/1769 [#1772]: https://github.com/nextstrain/augur/pull/1772 [#1774]: https://github.com/nextstrain/augur/issues/1774 [#1776]: https://github.com/nextstrain/augur/issues/1776 [#1782]: https://github.com/nextstrain/augur/pull/1782