CHANGES IN VERSION 1.40.0
-------------------------

NEW FEATURES

  o Add builtin_annotations_table(), which shows which groups of annotations
    are available for which genome builds, one row per genome.
  o Update the vignette: a table of available annotations, the new
    annotations (MANE, Ensembl canonical, cCREs, any TxDb), current data
    sources and installation, and session information.
  o Add ENCODE candidate cis-regulatory element (cCRE) annotations from the
    SCREEN registry (version 4) for hg38 and mm10: '[genome]_ccre_[class]' for
    the 8 classes (PLS, pELS, dELS, CA-H3K4me3, CA-CTCF, CA-TF, CA, TF), and the
    '[genome]_ccres' shortcut. The id is the cCRE accession.
  o Add Ensembl canonical transcript annotations, '[genome]_canonical_*' and
    the '[genome]_basiccanonical' shortcut, for hg38, mm39, rn7, danRer11, dm6,
    and oviariramb2: one transcript per gene, of every biotype, including
    intergenic. They are built from the Ensembl 113 EnsDbs in AnnotationHub,
    with sequences renamed to UCSC names. Genes on alternate haplotypes and fix
    patches are left out.
  o All annotations have entrez_id and ensembl_id columns, next to gene_id
    and symbol. For gene annotations of every genome, symbol, entrez_id, and
    ensembl_id (without version) are filled in from the org.*.eg.db package,
    the EnsDb, or the MANE summary, whatever kind of gene ID the source uses.
    When a gene ID maps to more than one, the first is used. gene_id is
    unchanged. summarize_genes() includes the new columns.
  o Add build_txdb_annotations(), which builds the gene annotation types
    (promoters, exons, introns, intergenic, etc.) from any TxDb or EnsDb, e.g.
    one made from a GENCODE or RefSeq GTF with txdbmaker::makeTxDbFromGFF().
    Annotations are named [genome]_[group]_[type], e.g.
    'mm39_gencode_promoters', and work with summarize_genes() and the plotting
    functions. Gene symbols come from an EnsDb or an optional OrgDb.
  o Add MANE Select annotations for hg38 (issue #29): 'hg38_mane_*', with the
    same types as 'hg38_genes_*' except intergenic, and the 'hg38_basicmane'
    shortcut. They use one transcript per protein-coding gene (MANE v1.5),
    instead of every isoform. gene_id is the Entrez ID and tx_id is the
    Ensembl transcript ID. Building them needs the txdbmaker package.
    summarize_genes() accepts them, alone or with 'hg38_genes_*'.
  o Add summarize_genes(), which summarizes annotated regions with one row
    per gene: the number of regions in each gene annotation type, category
    counts for a 'by' column, and the mean, median, and standard deviation of
    'over' columns. Use format = 'long' for one row per gene and annotation type.
  o build_annotations() caches the annotations it builds, and the files it
    downloads, on disk, so later calls load them in seconds instead of
    rebuilding them. Use cache = FALSE to build without the cache, and
    list_cached_annotations() and clear_cached_annotations() to manage it. See
    ?`cached-annotations` for troubleshooting.
  o Downloads are retried, and use HTTPS.
  o Add support for sheep (ARS-UI_Ramb_v2.0) as 'oviariramb2'. Gene
    annotations come from the Ensembl 113 EnsDb in AnnotationHub (AH119381), so
    tx_id and gene_id are Ensembl IDs. CpG islands come from the UCSC GenArk
    assembly hub. Sequences use UCSC-style names (chr1, ..., chrUn_*).

BUGFIXES

  o The warning from plots about orders (e.g. fill_order) with elements not in
    the data now names those elements (issue #16).
  o Document that BED files are 0-based, so single bases need start = end - 1,
    in read_regions() and the vignette (issue #27).
  o Fix CpG islands read from UCSC database tables (hg38, mm10, mm39, rn6,
    rn7, danRer10, danRer11, galGal5), and hg19 chromHMM states, which started
    1 bp early because UCSC's 0-based starts were used as 1-based. CpG shores,
    shelves, and inter-CGI regions, built from the islands, are fixed too.
    Reported, with a fix, by Ryan Yancey (issue #54, PR #55).
  o Gene annotations for dm3, dm6, and rn4 had no gene symbols, because their
    gene IDs are FlyBase or Ensembl IDs, but symbols were looked up by Entrez
    ID. They now have symbols, Entrez IDs, and Ensembl IDs.

USER-FACING CHANGES

  o Require R >= 4.6.0, the version Bioconductor 3.24 runs on.

DEPRECATED AND DEFUNCT

  o Deprecate randomize_regions(). Regions placed uniformly at random across the
    genome are a poor null model for most data. Instead, annotate a background
    of the regions the data could have come from (e.g. all tested CpGs) and
    pass it as annotated_random, or use regioneR::permTest() or
    regioneR::resampleRegions(). See ?`annotatr-deprecated` and the vignette.

INTERNAL CHANGES

  o Replace Travis CI with GitHub Actions, which runs R CMD check and
    BiocCheck in the Bioconductor devel container on pushes and pull requests
    to devel, and the full build tests weekly.
  o docker/install_deps.R retries failed package installs from the
    tu-dortmund Bioconductor mirror, since bioconductor.org sometimes closes
    connections partway through large downloads.
  o docker/check.sh exits with an error when BiocCheck finds an error.
  o plot_coannotations() and plot_numerical_coannotations() are 10 to 100
    times faster, without the superseded dplyr::do().
  o Replace the deprecated dplyr::funs() and tidyselect uses of external
    vectors, which warned with recent dplyr. summarize_numerical() output is
    unchanged.
  o Update the CITATION to bibentry() with the DOI.
  o Move the tests to testthat 3rd edition. Tests no longer depend on each
    other or on file order, and plot tests build the plots. Build tests for
    small downloads run whenever online. Full build tests for every genome run
    with ANNOTATR_FULL_TESTS=true, which docker/check.sh sets.

USER-FACING CHANGES

  o Document that read_annotations() returns the custom annotations, which can
    be combined with other annotations using c(), as well as storing them in
    annotatr_cache.
  o summarize_annotations(), plot_annotation(), and plot_categorical() label the
    regions in annotated_random as "Background" instead of "Random Regions".
    The argument name annotated_random is unchanged.

BUGFIXES

  o annotate_regions() gives clear errors when the regions and annotations are
    from different genomes, or have no chromosome names in common (e.g. 2 and
    chr2), instead of findOverlaps() errors or no overlaps. It suggests
    read_regions(genome = ...) once per session for regions without a genome.
  o hg38_enhancers_fantom and mm10_enhancers_fantom have the seqinfo of their
    genome. liftOver() had dropped the genome and chromosome lengths.
  o Intergenic and interCGI annotations are only on chromosomes with genes or
    CpG islands. Unplaced contigs and alternate haplotypes without any were
    each an entire intergenic or interCGI region.
  o plot_numerical_coannotations() scatterplots draw each region once per
    facet. Regions were drawn once per combination of their annotations, so
    with the semi-transparent points, regions with many annotations (e.g. in
    genes with many transcripts) looked darker.
  o Gene annotations are trimmed to the ends of chromosomes. Some promoters
    and intron/exon boundaries extended past them, with warnings, e.g. for
    danRer10, danRer11, mm10, rn4, and rn6.
  o build_annotations() no longer attaches the TxDb.* and org.*.eg.db
    packages, and says which of them to install when they are missing.
  o Fix plot_categorical() with the default fill = NULL, which failed when the
    plot was drawn.
  o Fix hg38_lncrna_gencode and mm10_lncrna_gencode, which failed after
    AnnotationHub removed its GENCODE resources (AH75123, AH49550). All lncRNA
    annotations are now downloaded from GENCODE over HTTPS, using the same
    releases as before (hg19: 19, hg38: 31, mm10: M6).

CHANGES IN VERSION 1.16.0
-------------------------

USER-FACING CHANGES

  o Export expand_annotations(), tidy_annotations(), and subset_order_tbl().

BUGFIXES

  o Fix incorrect shortcut search for HMMs.

CHANGES IN VERSION 1.6.0
------------------------

NEW FEATURES

  o Add support for chicken (galGal5).

USER-FACING CHANGES

  o Add the ability to facet over two variables in plot_numerical().
  o Add the ability to keep duplicate regions in summarize_categorical() and
    plot_categorical(). This is accomplished with the 'by' parameter in the
    former and by the 'x' and 'fill' parameters in the latter, and passing
    their contents into the '.dots' parameter of dplyr::distinct_().
  o Make TxDb and OrgDb packages Suggests instead of Imports. NOTE: This saves
    space, but also requires downloading the appropriate packages as needed.
  o Add list_env() function to the annotatr_cache environment to see what
    custom annotations have been read in and added to the cache.

BUGFIXES

  o Replace dplyr::summarize_each_() with dplyr::summarize_at() in line with
    deprecation in the dplyr package.
  o Prefix builtin_ functions with annotatr:: so that packages that Import
    annotatr don't encounter errors.

CHANGES IN VERSION 1.2.0
------------------------

NEW FEATURES

  o Add support for CpG annotations for hg38, mm10, and rn6 via the UCSC goldenpath URLs.
  o Add a function to build annotations from AnnotationHub resources, build_ah_annots().
  o Add support for chromHMM tracks (chromatin state) from the UCSC Genome Browser.
    o Users may annotate to chromatin states in multiple cell lines, if desired.
  o Use rtracklayer::liftOver to lift hg19 and mm9 enhancers into hg38 and mm10.

USER-FACING CHANGES

  o Add minoverlaps parameter to annotate_regions() that is passed to
    GenomicRanges::findOverlaps().
  o Change supported_annotations() and supported_genomes() into builtin_annotations()
    and builtin_genomes(). This enables more flexibility required for AnnotationHub
    annotations.
  o Added documentation for coercing result of annotate_regions() to data.frame
     and subsetting based on gene symbol to the vignette.

BUGFIXES

  o Fixed a bug in coercion of GRanges to data.frame where row.names could be
    duplicated. Thanks to @kdkorthauer.
  o Require GenomeInfoDb >= 1.10.3 because of changes to NCBI servers.
  o Change scale_fill_brewer() to scale_fill_hue() in plot_categorical() to enable
    more categories and avoid plotting abnormalities.
  o Fixed bug that mistakenly displayed some supported annotations.
  o Fixed a bug in lncRNA annotation building caused by incomplete reference.

CHANGES IN VERSION 0.99.13
--------------------------

PKG FEATURES

  o annotatr is a package to quickly and flexibly annotate genomic regions to
    genomic annotations.

    o Genomic annotations include CpG features (island, shore, shelves, and
	  open sea), genic features (1-5kb upstream of TSS, promoters,
	  5'UTRs, exons, introns, CDS, 3'UTRs, intron/exon boundaries, and exon/
	  intron boundaries), as well as enhancers from the FANTOM5 consortium for
	  hg19 and mm9.

	  o Annotations are built at runtime using the TxDb.*, AnnotationHub, and
	    rtracklayer packages. Users can select annotations a la carte, or via
		shortcuts, such as hg19_basicgenes.

	  o Annotations are currently available for hg19, mm9, mm10, dm3, dm6, rn4,
	    rn5, and rn6. Any species is supported through custom annotations.

  o Genomic regions are read in using the rtracklayer::import() function, and
    the extraCols argument enables users to include an arbitrary number of
	categorical or numerical data with the genomic regions.

  o Annotations are determined via GenomicRanges::findOverlaps(), and all
    annotations are returned, rather than imposing a prioritization.

  o annotatr provides several helpful summarization (using dplyr) and plot
    functions (using ggplot2) to investigate trends in data associated with the
	genomic regions over annotations.
