Changed region_map and region_map_into_granges interface.

 - Now, both of these functions will pass a region tuple of
   the `(seqname, start, end)` coordinates to allow users to
   access the coordinates of the present slice.

 - Major version bump since this changes the API.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "granges"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 license = "MIT"
 authors = ["Vince Buffalo <[email protected]>"]

src/lib.rs

@@ -405,6 +405,7 @@ pub type PositionOffset = i64;
 
 /// The main exports of the GRanges library.
 pub mod prelude {
+    pub use crate::{Position, PositionOffset};
     pub use crate::error::GRangesError;
     pub use crate::granges::{GRanges, GRangesEmpty};
     pub use crate::io::file::read_seqlens;

src/sequences/nucleotide.rs

@@ -169,12 +169,12 @@ impl Sequences for NucleotideSequences {
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: Fn(Self::Slice<'_>) -> V,
+        F: Fn(Self::Slice<'_>, (&str, Position, Position)) -> V,
     {
         let seq = self.get_sequence(seqname)?;
         let range = try_range(start, end, seq.len().try_into().unwrap())?;
         let data = &seq[range];
-        Ok(func(data))
+        Ok(func(data, (&seqname, start, end)))
     }
 
     /// Get the length of a particular sequence.
@@ -303,11 +303,11 @@ impl Sequences for LazyNucleotideSequences {
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: for<'b> Fn(&'b [u8]) -> V,
+        F: for<'b> Fn(&'b [u8], (&str, Position, Position)) -> V,
     {
         let seq = self.get_sequence(seqname)?;
         let range = try_range(start, end, seq.len().try_into().unwrap())?;
-        Ok(func(&seq[range]))
+        Ok(func(&seq[range], (seqname, start, end)))
     }
 
     /// Get the length of a particular sequence.
@@ -382,7 +382,7 @@ pub fn gc_content(seq: &[u8]) -> f64 {
 ///
 /// # Arguments
 /// * `seq` - a byte slice.
-pub fn gc_content_strict(seq: &[u8]) -> f64 {
+pub fn gc_content_strict(seq: &[u8], _: (&str, Position, Position)) -> f64 {
     let gc_count = seq
         .iter()
         .filter(|&&base| matches!(base.to_ascii_uppercase(), b'G' | b'C'))
@@ -402,7 +402,7 @@ pub fn gc_content_strict(seq: &[u8]) -> f64 {
 #[cfg(test)]
 mod tests {
     use super::{gc_content_strict, LazyNucleotideSequences, NucleotideSequences};
-    use crate::{granges::GRangesEmpty, sequences::nucleotide::Nucleotides, traits::Sequences};
+    use crate::{granges::GRangesEmpty, sequences::nucleotide::Nucleotides, traits::Sequences, Position};
 
     #[test]
     fn test_nucleotide_sequences() {
@@ -438,7 +438,7 @@ mod tests {
         // chromosome sequence length through the apply funcs
         let seq1_len = seqlens.get("chr1").unwrap();
 
-        fn get_len(seq: &[u8]) -> usize {
+        fn get_len(seq: &[u8], _: (&str, Position, Position)) -> usize {
             seq.len()
         }
 
@@ -473,7 +473,7 @@ mod tests {
         // len([l for l in 'TTCACTACTATTAGTACTCACGGCGCAATA'[3:10] if l == 'C'])
         let total_Cs = reference
             .region_map(
-                &|seq| seq.iter().filter(|c| **c == b'C').count(),
+                &|seq, _| seq.iter().filter(|c| **c == b'C').count(),
                 "chr1",
                 3,
                 10,
@@ -486,7 +486,7 @@ mod tests {
         // len([l for l in 'TTCACTACTATTAGTACTCACGGCGCAATA'[3:10] if l == 'A'])
         let total_As = reference
             .region_map(
-                &|seq| seq.iter().filter(|c| **c == b'A').count(),
+                &|seq, _| seq.iter().filter(|c| **c == b'A').count(),
                 "chr1",
                 3,
                 10,
@@ -505,7 +505,7 @@ mod tests {
 
         let windows = GRangesEmpty::from_windows(&seqlens, 10, None, false).unwrap();
 
-        let make_string = |seq: &[u8]| String::from_utf8(seq.to_vec()).unwrap();
+        let make_string = |seq: &[u8], _: (&str, Position, Position)| String::from_utf8(seq.to_vec()).unwrap();
 
         // our test: get subsequences (as Strings), with *no step*, and reconstruct the
         // original sequence

src/sequences/numeric.rs

@@ -89,12 +89,12 @@ where
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: for<'b> Fn(Self::Slice<'b>) -> V,
+        F: for<'b> Fn(Self::Slice<'b>, (&str, Position, Position)) -> V,
     {
         let seq = self.get_sequence(seqname)?;
         let range = try_range(start, end, seq.len().try_into().unwrap())?;
         let view = seq.slice(s![range]);
-        Ok(func(view))
+        Ok(func(view, (seqname, start, end)))
     }
 
     fn get_sequence_length(&self, seqname: &str) -> Result<Position, GRangesError> {
@@ -204,6 +204,7 @@ where
     /// # Examples
     ///
     /// ```
+    /// use crate::granges::prelude::Position;
     /// use crate::granges::traits::Sequences;
     /// use granges::sequences::numeric::NumericSequences1;
     /// use granges::test_utilities::random_array1_sequences;
@@ -213,7 +214,7 @@ where
     /// let mut data = random_array1_sequences(100);
     /// let numeric_seq = NumericSequences1::new(data);
     /// let result = numeric_seq.region_map(
-    ///     &|view: ArrayView1<'_, f64> | view.sum(),
+    ///     &|view: ArrayView1<'_, f64>, _: (&str, Position, Position)| view.sum(),
     ///     "chr1",
     ///     0,
     ///     10
@@ -227,13 +228,13 @@ where
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: for<'b> Fn(Self::Slice<'_>) -> V,
+        F: for<'b> Fn(Self::Slice<'_>, (&str, Position, Position)) -> V,
     {
         let seq = self.get_sequence(seqname)?;
         let range = try_range(start, end, seq.len().try_into().unwrap())?;
         let seq = self.get_sequence(seqname)?;
         let view = seq.slice(s![range, ..]);
-        Ok(func(view))
+        Ok(func(view, (seqname, start, end)))
     }
 
     /// Retrieves the length of a specific sequence.
@@ -355,12 +356,12 @@ where
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: for<'b> Fn(ArrayView2<'b, T>) -> V,
+        F: for<'b> Fn(ArrayView2<'b, T>, (&str, Position, Position)) -> V,
     {
         let seq = self.get_sequence(seqname)?;
         let range = try_range(start, end, seq.len().try_into().unwrap())?;
         let view = seq.slice(s![range, ..]);
-        let value = func(view);
+        let value = func(view, (seqname, start, end));
         Ok(value)
     }
 

src/traits.rs

@@ -354,7 +354,8 @@ pub trait Sequences {
     /// Apply a function on a [`Sequences::Slice`] of a sequence.
     ///
     /// # Arguments
-    /// * `func` - a function that takes a `Self::Slice` and returns a [`Result<V, GRangesError>`]
+    /// * `func` - a function that takes a `Self::Slice`, `start`, and `end` positions
+    ///            and returns a [`Result<V, GRangesError>`].
     /// * `seqname` - sequence name.
     /// * `start` - a [`Position`] start position.
     /// * `end` - a [`Position`] *inclusive* end position.
@@ -370,6 +371,11 @@ pub trait Sequences {
     ///
     /// to validate the range and to avoid panics.
     ///
+    /// Note that the `start` and `end` positions can often be ignored 
+    /// by the function processing the `Slice`. However, this information
+    /// is useful when functions need to know the slice coordinates to 
+    /// e.g. combine with other data in this region.
+    ///
     fn region_map<V, F>(
         &self,
         func: &F,
@@ -378,7 +384,7 @@ pub trait Sequences {
         end: Position,
     ) -> Result<V, GRangesError>
     where
-        F: Fn(<Self as Sequences>::Slice<'_>) -> V;
+        F: Fn(<Self as Sequences>::Slice<'_>, (&str, Position, Position)) -> V;
 
     fn seqlens(&self) -> Result<IndexMap<String, Position>, GRangesError> {
         let mut seqlens = IndexMap::new();
@@ -401,7 +407,7 @@ pub trait Sequences {
     where
         V: Clone,
         C: IterableRangeContainer + 'b,
-        F: Fn(<Self as Sequences>::Slice<'_>) -> V,
+        F: Fn(<Self as Sequences>::Slice<'_>, (&str, Position, Position)) -> V,
     {
         let granges_ref = granges.as_granges_ref();
         let seqlens = &granges_ref.seqlens().clone();