Add spliceinto! function. (#338)

This function inserts a sequence into a biosequence, and optionally deletes part
of the original sequence.
The naming difference from `Base.splice!` reflects is slightly different API.

Author: jakobnissen

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.5.0]
+* Add `spliceinto!`. This function inserts a sequence into a biosequence,
+  and optionally deletes part of the original sequence. The naming difference
+  from `Base.splice!` reflects is slightly different API.
+* Optimise various methods
+
 ## [3.4.0]
 * Deprecate functions `n_ambiguous`, `n_gaps` and `n_certain`. Instead, use the
   equivalent methods `count(f, seq)` with the appropriate function `f`.

Project.toml

@@ -1,7 +1,7 @@
 name = "BioSequences"
 uuid = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
 authors = ["Sabrina Jaye Ward <[email protected]>", "Jakob Nissen <[email protected]>"]
-version = "3.4.2"
+version = "3.5.0"
 
 [deps]
 BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
@@ -11,19 +11,22 @@ Twiddle = "7200193e-83a8-5a55-b20d-5d36d44a0795"
 
 [compat]
 BioSymbols = "5.1.2"
+LinearAlgebra = "1.10"
 PrecompileTools = "1"
 Random = "1.5"
 StableRNGs = "0.1, 1.0"
+StatsBase = "0.34.5"
+Test = "1.10"
 Twiddle = "1.1.1"
+YAML = "0.4.14"
 julia = "1.10"
 
 [extras]
-Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [targets]
-test = ["Documenter", "Test", "StatsBase", "YAML", "LinearAlgebra", "StableRNGs"]
+test = ["Test", "StatsBase", "YAML", "LinearAlgebra", "StableRNGs"]

docs/Project.toml

@@ -3,5 +3,8 @@ BioSequences = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
 BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
+[sources]
+BioSequences = {path = ".."}
+
 [compat]
 Documenter = "1"

docs/src/transforms.md

@@ -66,6 +66,8 @@ deleteat!(::BioSequences.BioSequence, ::Integer)
 append!(::BioSequences.BioSequence, ::BioSequences.BioSequence)
 resize!(::BioSequences.LongSequence, ::Integer)
 empty!(::BioSequences.BioSequence)
+spliceinto!(::BioSequence, ::Integer, ::Any)
+spliceinto!(::BioSequence, ::UnitRange, ::Any)
 ```
 
 Here are some examples:

src/BioSequences.jl

@@ -132,6 +132,7 @@ export
     ungap,
     ungap!,
     join!,
+    spliceinto!,
 
     ###
     ### LongSequence

src/biosequence/transformations.jl

@@ -44,16 +44,97 @@ end
     insert!(seq::BioSequence, i, x)
 
 Insert a biological symbol `x` into a biological sequence `seq`, at the given
-index `i`.
+index `i`. Returns the mutated `seq`.
+
+# Examples
+```jldoctest
+julia> seq = dna"ATGCA"
+5nt DNA Sequence:
+ATGCA
+
+julia> insert!(seq, 3, 'A')
+6nt DNA Sequence:
+ATAGCA
+```
 """
 function Base.insert!(seq::BioSequence, i::Integer, x)
+    i == length(seq) + 1 && return push!(seq, x)
     checkbounds(seq, i)
     resize!(seq, length(seq) + 1)
     copyto!(seq, i + 1, seq, i, lastindex(seq) - i)
     @inbounds seq[i] = x
     return seq
 end
 
+"""
+    spliceinto!(seq::BioSequence, i::Integer, x)
+
+Insert the sequence `x` into a biological sequence `seq`, at the given index `i`.
+After splicing, the `seq`'s symbols at indices `i:i+length(x)-1` are equal to `x`,
+and the the symbols that were previously there are moved to the right.
+
+# Examples
+```jldoctest
+julia> seq = dna"TAGTGCA";
+
+julia> spliceinto!(seq, 3, "CAGGA")
+12nt DNA sequence:
+TACAGGAGTGCA
+```
+"""
+function spliceinto!(seq::BioSequence, i::Integer, x)
+    oldlen = length(seq)
+    i == oldlen + 1 && return append!(seq, x)
+    @boundscheck checkbounds(seq, i)
+    resize!(seq, oldlen + length(x))
+    copyto!(seq, i + length(x), seq, i, oldlen - i + 1)
+    copyto!(seq, i, x, 1, length(x))
+    return seq
+end
+
+"""
+    spliceinto!(seq::BioSequence, span::UnitRange, x)
+
+Delete the symbols at indices `span` in `seq`, and then copy `x` into the
+first deleted position, then return `seq`.
+
+This is equivalent to `deleteat!(seq, span); spliceinto!(seq, first(span), x)`,
+but is more efficient.
+`span` must be nonempty, or this function will throw an `ArgumentError`. To handle
+potentially empty spans, check if the span is empty, and if so use `spliceinto(seq, first(span), x)`.
+
+# Examples
+```jldoctest
+julia> seq = dna"TAGTGCA";
+
+julia> spliceinto!(seq, 3:5, "CAGGA")
+9nt DNA sequence:
+TACAGGACA
+```
+"""
+function spliceinto!(seq::BioSequence, span::UnitRange, x)
+    isempty(span) && throw(ArgumentError("span cannot be empty"))
+    @boundscheck checkbounds(seq, span)
+    oldlen = length(seq)
+    xlen = length(x)
+    if length(span) == xlen
+        # Same lengths: Just copy in x
+        copyto!(seq, first(span), x, 1, length(span))
+    elseif length(span) < xlen
+        # x is longer. Resize and shift to make room for more symbols,
+        # then copy in x
+        resize!(seq, oldlen + xlen - length(span))
+        copyto!(seq, first(span) + xlen, seq, last(span) + 1, oldlen - last(span))
+        copyto!(seq, first(span), x, 1, xlen)
+    else
+        # Span is longer. Delete the rightmost bases (to cause the smallest possible shift),
+        # then copy in
+        deleteat!(seq, first(span) + xlen:last(span))
+        copyto!(seq, first(span), x, 1, xlen)
+    end
+    return seq
+end
+
 """
     deleteat!(seq::BioSequence, range::UnitRange{<:Integer})
 
@@ -89,7 +170,7 @@ end
 Add a biological sequence `other` onto the end of biological sequence `seq`.
 Modifies and returns `seq`.
 """
-function Base.append!(seq::BioSequence, other::BioSequence)
+function Base.append!(seq::BioSequence, other)
     resize!(seq, length(seq) + length(other))
     copyto!(seq, lastindex(seq) - length(other) + 1, other, 1, length(other))
     return seq

test/longsequences/mutability.jl

@@ -122,9 +122,88 @@
         seq = dna"ACGT"
         @test insert!(seq, 2, DNA_G) == dna"AGCGT"
         @test insert!(seq, 5, DNA_A) == dna"AGCGAT"
+        @test insert!(seq, 1, 'G') == dna"GAGCGAT"
+        @test insert!(seq, length(seq) + 1, 'C') == dna"GAGCGATC"
         @test_throws BoundsError insert!(seq, 10, DNA_T)
     end
 
+    @testset "spliceinto!" begin
+        @testset "spliceinto integer" begin
+            function manual_spliceinto(seq, i, x)
+                s = typeof(seq)(undef, length(seq) + length(x))
+                copyto!(s, 1, seq, 1, i-1)
+                copyto!(s, i, x, 1, length(x))
+                copyto!(s, i + length(x), seq, i, length(seq)-i+1)
+                return s
+            end
+
+            seq = dna"TAGTGCA"
+            @test spliceinto!(seq, 2, "CA") === seq
+            @test seq == dna"TCAAGTGCA"
+
+            str = "ATGTGCTCGTGTCGTGATAGTGAGTAGTAGTCGTAGTAGTGATTGCTGTAGTA"
+            seq = LongDNA{2}(str)
+
+            @test_throws BoundsError spliceinto!(seq, 0, "CA")
+            @test_throws BoundsError spliceinto!(seq, -1, "CA")
+            @test_throws BoundsError spliceinto!(seq, length(seq) + 2, "CA")
+
+            for (i, s) in Any[
+                (1, ""),
+                (1, "CAC"),
+                (1, "ATGCTGCTGATGTGATGA"),
+                (2, dna"ATGTCGA"),
+                (15, rna"AUGUCGUAGUAACCAACA"),
+                (16, dna"ATGTCGTGATGATGTAGTGTCGTA"),
+                (18, b"ATGCTGTGATGATGTCC"),
+                (length(seq), dna"TAGCGGAGA"),
+                (length(seq) + 1, "AGCGGGAGA"),
+            ]
+                copy!(seq, str)
+                cp = copy(seq)
+                @test spliceinto!(seq, i, s) == manual_spliceinto(cp, i, s)
+            end
+        end
+
+        @testset "spliceinto span" begin
+            function manual_spliceinto(seq, span, x)
+                deleteat!(seq, span)
+                spliceinto!(seq, first(span), x)
+                return seq
+            end
+
+            seq = dna"ATGTCGTGA"
+            @test spliceinto!(seq, 2:2, "CA") === seq
+            @test seq == dna"ACAGTCGTGA"
+
+            str = "ATGTGCTCGTGTCGTGATAGTGAGTAGTAGTCGTAGTAGTGATTGCTGTAGTA"
+            seq = LongDNA{2}(str)
+
+            @test_throws ArgumentError spliceinto!(seq, 0:-1, "CA")
+            @test_throws ArgumentError spliceinto!(seq, 1:0, "CA")
+            @test_throws ArgumentError spliceinto!(seq, lastindex(seq):5, "CA")
+
+            @test_throws BoundsError spliceinto!(seq, 0:0, "CA")
+            @test_throws BoundsError spliceinto!(seq, 0:1, "CA")
+            @test_throws BoundsError spliceinto!(seq, 4:100, "CA")
+            @test_throws BoundsError spliceinto!(seq, length(seq):length(seq)+1, "CA")
+
+            for (i, s) in Any[
+                (1:1, ""),
+                (4:6, "T"),
+                (4:9, "ATGCGTA"),
+                (3:6, "AGCA"),
+                (30:35, "ATGTCGTAG"),
+                (15:20, rna"UAGC"),
+                (9:40, dna"ATGTCGTGATGAA")
+            ]
+                copy!(seq, str)
+                cp = copy(seq)
+                @test spliceinto!(seq, i, s) == manual_spliceinto(cp, i, s)
+            end
+        end
+    end
+
     @testset "deleteat!" begin
         seq = dna"ACGT"
         @test deleteat!(seq, 1) == dna"CGT"

test/runtests.jl

@@ -1,7 +1,6 @@
 module TestBioSequences
 
 using Test
-using Documenter
 
 using Random
 using StableRNGs