Merge branch 'release/v0.4.0'

BioJulia · Jan 27, 2024 · beefc45 · beefc45 · CiaranOMara · Jan 27, 2024
2 parents 22f939f + 456d820
commit beefc45
Show file tree

Hide file tree

Showing 23 changed files with 478 additions and 324 deletions.
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -12,12 +12,13 @@ jobs:
   Documenter:
     permissions:
       contents: write
-    name: Documentation    
+      statuses: write
+    name: Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/julia-buildpkg@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/julia-buildpkg@v1  # if package requires Pkg.build()
       - uses: julia-actions/julia-docdeploy@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml
@@ -9,7 +9,18 @@ on:
       lookback:
         default: 3
 permissions:
+  actions: read
+  checks: read
   contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
 
 jobs:
   TagBot:

diff --git a/.github/workflows/UnitTests.yml b/.github/workflows/UnitTests.yml
@@ -29,17 +29,19 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Setup Julia
         uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.julia-version }}
       - name: Run Tests
         uses: julia-actions/julia-runtest@v1
+        with:
+          annotate: true
       - name: Create CodeCov
         uses: julia-actions/julia-processcoverage@v1
       - name: Upload CodeCov
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v2
         with:
           file: ./lcov.info
           flags: unittests

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,34 +1,73 @@
 # Changelog
 
-All notable changes to HapLink.jl will be documented in this file.
+All notable changes to XAM.jl will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+
+## [0.4.0]
+
+### Added
+- Added BAM.Reader index support for BAI object ([#56](https://github.com/BioJulia/XAM.jl/pull/56)).
+- Added doi badge.
+- Added test to ensure EOF_BLOCK gets written.
+- Added `isreversestrand`.
+- Added `isfirstsegment`.
+- Added `islastsegment`.
+
+### Changed
+
+- Subtype from XAMReader and XAMWriter from common abstract types.
+- Subtype from XAMRecord.
+- Unified flag queries.
+- Improved Slack link.
+- Updated to use [Automa](https://github.com/BioJulia/Automa.jl) v1 ([#65](https://github.com/BioJulia/XAM.jl/pull/65)).
+- Pointed the Unit Tests badge at the develop branch.
+- Pluralised flag.
+- Renamed `ismateunmapped` to `isnextunmapped`.
+- Renamed `isreverse` to `isreversecomplemented`.
+- Renamed `isforward` to `isforwardstrand`.
+- `ispositivestrand` aliases `isforwardstrand`.
+- `isnegativestrand` aliases `isreversestrand`.
+- Renamed `ismatereverse` to `isnextreversecomplemented`.
+- `isread1` aliases `isfirstsegment`.
+- `isread2` aliases `islastsegment`.
+
+### Fixed
+- Updated hts-files.md ([#62](https://github.com/BioJulia/XAM.jl/pull/62)).
+- Corrected the behaviour of `isprimaryalignment` with `isprimary`.
+
+### Removed
+- Moved the functionality of `isprimary` into `isprimaryalignment`.
+
+
 ## [0.3.1]
 
 ### Changed
 
-- Upgraded to BioAlignments v3 ([#55](https://github.com/BioJulia/XAM.jl/pull/55))
+- Upgraded to BioAlignments v3 ([#55](https://github.com/BioJulia/XAM.jl/pull/55)).
+
 
 ## [0.3.0] - 2022-10-10
 
 ## Added
 
-- Crosschecks for SAM and BAM ([#29](https://github.com/BioJulia/XAM.jl/pull/29))
-- Improved documentation for flags ([#43](https://github.com/BioJulia/XAM.jl/pull/43))
+- Crosschecks for SAM and BAM ([#29](https://github.com/BioJulia/XAM.jl/pull/29)).
+- Improved documentation for flags ([#43](https://github.com/BioJulia/XAM.jl/pull/43)).
 
 ### Changed
 
-- `BAM.quality` performance improved ([#21](https://github.com/BioJulia/XAM.jl/issues/21))
-- Updated BioAlignments to v2.2 and BioSequences to v3 ([#48](https://github.com/BioJulia/XAM.jl/pull/48))
+- `BAM.quality` performance improved ([#21](https://github.com/BioJulia/XAM.jl/issues/21)).
+- Updated BioAlignments to v2.2 and BioSequences to v3 ([#48](https://github.com/BioJulia/XAM.jl/pull/48)).
 
 ### Fixed
 
-- `BAM.Record` layout now matches the BAM specs ([#26](https://github.com/BioJulia/XAM.jl/pull/26))
+- `BAM.Record` layout now matches the BAM specs ([#26](https://github.com/BioJulia/XAM.jl/pull/26)).
 
-[Unreleased]: https://github.com/BioJulia/XAM.jl/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/BioJulia/XAM.jl/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/BioJulia/XAM.jl/compare/v0.3.1...0.4.0
 [0.3.1]: https://github.com/BioJulia/XAM.jl/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/BioJulia/XAM.jl/compare/v0.2.8...v0.3.0
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "XAM"
 uuid = "d759349c-bcba-11e9-07c2-5b90f8f05f7c"
 authors = ["Kenta Sato <[email protected]>", "Ben J. Ward <[email protected]>", "Ciarán O'Mara <[email protected]>"]
-version = "0.3.1"
+version = "0.4.0"
 
 [deps]
 Automa = "67c07d97-cdcb-5c2c-af73-a7f9c32a568b"
@@ -15,15 +15,15 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 TranscodingStreams = "3bb67fe8-82b1-5028-8e26-92a6c54297fa"
 
 [compat]
-Automa = "0.7, 0.8"
+Automa = "1"
 BGZFStreams = "0.3.1"
 BioAlignments = "3"
 BioGenerics = "0.1"
 BioSequences = "3"
 FormatSpecimens = "1.1"
 GenomicFeatures = "2"
 Indexes = "0.1"
-TranscodingStreams = "0.6, 0.7, 0.8, 0.9"
+TranscodingStreams = "0.6, 0.7, 0.8, 0.9, 0.10"
 julia = "1.6"
 
 [extras]

diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![Latest Release](https://img.shields.io/github/release/BioJulia/XAM.jl.svg)](https://github.com/BioJulia/XAM.jl/releases/latest)
+[![DOI](https://zenodo.org/badge/201858041.svg)](https://zenodo.org/badge/latestdoi/201858041)
 [![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BioJulia/XAM.jl/blob/master/LICENSE)
 [![Stable documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://biojulia.github.io/XAM.jl/stable)
 [![Latest documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://biojulia.github.io/XAM.jl/dev/)
@@ -26,7 +27,7 @@ XAM is tested against Julia `1.X` on Linux, OS X, and Windows.
 
 **Latest build status:**
 
-[![Unit tests](https://github.com/BioJulia/XAM.jl/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3A%22Unit+tests%22+branch%3Amaster)
+[![Unit Tests](https://github.com/BioJulia/XAM.jl/actions/workflows/UnitTests.yml/badge.svg?branch=develop)](https://github.com/BioJulia/XAM.jl/actions/workflows/UnitTests.yml)
 [![Documentation](https://github.com/BioJulia/XAM.jl/workflows/Documentation/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3ADocumentation+branch%3Amaster)
 [![codecov](https://codecov.io/gh/BioJulia/XAM.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/BioJulia/XAM.jl)
 
@@ -65,4 +66,4 @@ Your logo will show up here with a link to your website.
 
 
 ## Questions?
-If you have a question about contributing or using BioJulia software, come on over and chat to us on [the Julia Slack workspace](https://julialang.org/slack/), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio).
+If you have a question about contributing or using BioJulia software, come on over and chat to us on [the Julia Slack workspace](https://julialang.slack.com/channels/biology), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio).
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -25,7 +25,7 @@ XAM is tested against Julia `1.X` on Linux, OS X, and Windows.
 
 **Latest build status:**
 
-[![Unit tests](https://github.com/BioJulia/XAM.jl/workflows/Unit%20tests/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3A%22Unit+tests%22+branch%3Amaster)
+[![Unit Tests](https://github.com/BioJulia/XAM.jl/actions/workflows/UnitTests.yml/badge.svg?branch=develop)](https://github.com/BioJulia/XAM.jl/actions/workflows/UnitTests.yml)
 [![Documentation](https://github.com/BioJulia/XAM.jl/workflows/Documentation/badge.svg?branch=master)](https://github.com/BioJulia/XAM.jl/actions?query=workflow%3ADocumentation+branch%3Amaster)
 [![codecov](https://codecov.io/gh/BioJulia/XAM.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/BioJulia/XAM.jl)
 
@@ -64,4 +64,4 @@ Your logo will show up here with a link to your website.
 
 
 ## Questions?
-If you have a question about contributing or using BioJulia software, come on over and chat to us on [the Julia Slack workspace](https://julialang.org/slack/), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio).
+If you have a question about contributing or using BioJulia software, come on over and chat to us on [the Julia Slack workspace](https://julialang.slack.com/channels/biology), or you can try the [Bio category of the Julia discourse site](https://discourse.julialang.org/c/domain/bio).
diff --git a/docs/src/man/hts-files.md b/docs/src/man/hts-files.md
@@ -67,7 +67,7 @@ end
 ## SAM and BAM Headers
 
 Both `SAM.Reader` and `BAM.Reader` implement the `header` function, which returns a `SAM.Header` object.
-To extract certain information out of the headers, you can use the `find` method on the header to extract information according to SAM/BAM tag.
+To extract certain information out of the headers, you can use the `findall` method on the header to extract information according to SAM/BAM tag.
 Again we refer you to the [specification](https://samtools.github.io/hts-specs/SAMv1.pdf) for full details of all the different tags that can occur in headers, and what they mean.
 
 Below is an example of extracting all the info about the reference sequences from the BAM header.
@@ -76,7 +76,7 @@ In SAM/BAM, any description of a reference sequence is stored in the header, und
 ```jlcon
 julia> reader = open(SAM.Reader, "data.sam");
 
-julia> find(header(reader), "SQ")
+julia> findall(SAM.header(reader), "SQ")
 7-element Array{Bio.Align.SAM.MetaInfo,1}:
  Bio.Align.SAM.MetaInfo:
     tag: SQ
@@ -110,9 +110,9 @@ In the above we can see there were 7 sequences in the reference: 5 chromosomes,
 The `XAM` package supports the following accessors for `SAM.Record` types.
 
 ```@docs
-XAM.SAM.flag
+XAM.SAM.flags
 XAM.SAM.ismapped
-XAM.SAM.isprimary
+XAM.SAM.isprimaryalignment
 XAM.SAM.refname
 XAM.SAM.position
 XAM.SAM.rightposition
@@ -135,9 +135,9 @@ XAM.SAM.auxdata
 The `XAM` package supports the following accessors for `BAM.Record` types.
 
 ```@docs
-XAM.BAM.flag
+XAM.BAM.flags
 XAM.BAM.ismapped
-XAM.BAM.isprimary
+XAM.BAM.isprimaryalignment
 XAM.BAM.refid
 XAM.BAM.refname
 XAM.BAM.reflen

diff --git a/src/XAM.jl b/src/XAM.jl
@@ -1,29 +1,17 @@
 module XAM
 
+using BioGenerics
+import BioGenerics: isfilled #Note: used by `ismapped`.
+
 export
     SAM,
     BAM
 
-"""
-    flag(record::Union{SAM.Record, BAM.Record})::UInt16
-
-Get the bitwise flags of `record`. The returned value is a `UInt16` of each flag
-being OR'd together. The possible flags are:
+abstract type XAMRecord end
+abstract type XAMReader <: BioGenerics.IO.AbstractReader end
+abstract type XAMWriter <: BioGenerics.IO.AbstractWriter end
 
-    0x0001 template having multiple segments in sequencing
-    0x0002 each segment properly aligned according to the aligner
-    0x0004 segment unmapped
-    0x0008 next segment in the template unmapped
-    0x0010 SEQ being reverse complemented
-    0x0020 SEQ of the next segment in the template being reverse complemented
-    0x0040 the first segment in the template
-    0x0080 the last segment in the template
-    0x0100 secondary alignment
-    0x0200 not passing filters, such as platform/vendor quality controls
-    0x0400 PCR or optical duplicate
-    0x0800 supplementary alignment
-"""
-function flag end
+include("flags.jl")
 
 include("sam/sam.jl")
 include("bam/bam.jl")

diff --git a/src/bam/bam.jl b/src/bam/bam.jl
@@ -6,7 +6,8 @@ module BAM
 using BioGenerics
 using GenomicFeatures
 using XAM.SAM
-import ..XAM: flag
+import ..XAM: flags, XAMRecord, XAMReader, XAMWriter,
+	ismapped, isprimaryalignment, ispositivestrand, isnextmapped #TODO: Deprecate import of flag queries. These were imported to preseve existing API.
 
 import BGZFStreams
 import BioAlignments

diff --git a/src/bam/reader.jl b/src/bam/reader.jl
@@ -8,9 +8,9 @@ Create a data reader of the BAM file format.
 
 # Arguments
 * `input`: data source
-* `index=nothing`: filepath to a random access index (currently *bai* is supported)
+* `index=nothing`: filepath to a random access index (currently *bai* is supported) or BAI object
 """
-mutable struct Reader{T} <: BioGenerics.IO.AbstractReader
+mutable struct Reader{T} <: XAMReader
     stream::BGZFStreams.BGZFStream{T}
     header::SAM.Header
     start_offset::BGZFStreams.VirtualOffset
@@ -28,13 +28,8 @@ function BioGenerics.IO.stream(reader::Reader)
 end
 
 function Reader(input::IO; index=nothing)
-    if isa(index, AbstractString)
-        index = BAI(index)
-    elseif index != nothing
-        error("unrecognizable index argument")
-    end
     reader = init_bam_reader(input)
-    reader.index = index
+    reader.index = init_bam_index(index)
     return reader
 end
 
@@ -125,6 +120,11 @@ function init_bam_reader(input::IO)
     return init_bam_reader(BGZFStreams.BGZFStream(input))
 end
 
+init_bam_index(index::AbstractString) = BAI(index)
+init_bam_index(index::BAI) = index
+init_bam_index(index::Nothing) = nothing
+init_bam_index(index) = error("unrecognizable index argument")
+
 function _read!(reader::Reader, record)
     unsafe_read(
         reader.stream,