add accessors back, fix tests and doc tutorial

Author: jkanche

README.md

@@ -48,6 +48,7 @@ print(len(gg), len(df))
 
     ## output
     ## 77 77> [!NOTE]
+
 > `ends` are expected to be inclusive to be consistent with Bioconductor representations. If they are not, we recommend subtracting 1 from the `ends`.
 
 #### UCSC or GTF file
@@ -212,16 +213,16 @@ print(hits)
     [1]                1          1677082
     [2]                2          1003411
 
-## `GenomicRangesList`
+## `CompressedGenomicRangesList`
 
-Just as it sounds, a `GenomicRangesList` is a named-list like object. If you are wondering why you need this class, a `GenomicRanges` object lets us specify multiple genomic elements, usually where the genes start and end. Genes are themselves made of many sub-regions, e.g. exons. `GenomicRangesList` allows us to represent this nested structure.
+Just as it sounds, a `CompressedGenomicRangesList` is a named-list like object. If you are wondering why you need this class, a `GenomicRanges` object lets us specify multiple genomic elements, usually where the genes start and end. Genes are themselves made of many sub-regions, e.g. exons. `CompressedGenomicRangesList` allows us to represent this nested structure.
 
 **Currently, this class is limited in functionality.**
 
-To construct a GenomicRangesList
+To construct a CompressedGenomicRangesList
 
 ```python
-from genomicranges import GenomicRanges, GenomicRangesList
+from genomicranges import GenomicRanges, CompressedGenomicRangesList
 from iranges import IRanges
 from biocframe import BiocFrame
 
@@ -238,12 +239,12 @@ gr2 = GenomicRanges(
     strand=["-", "+", "*"],
     mcols=BiocFrame({"score": [2, 3, 4]}),
 )
-grl = GenomicRangesList(ranges=[gr1, gr2], names=["gene1", "gene2"])
+grl = CompressedGenomicRangesList.from_list(lst=[gr1, gr2], names=["gene1", "gene2"])
 print(grl)
 ```
 
     ## output
-    GenomicRangesList with 2 ranges and 2 metadata columns
+    CompressedGenomicRangesList with 2 ranges and 2 metadata columns
 
     Name: gene1
     GenomicRanges with 4 ranges and 4 metadata columns
@@ -270,12 +271,12 @@ print(grl)
 
 Performance comparison between Python and R GenomicRanges implementations. The query dataset contains approximately 564,000 intervals, while the subject dataset contains approximately 71 million intervals.
 
-| Operation | Python/GenomicRanges | Python/GenomicRanges (5 threads) | R/GenomicRanges |
-|-----------|---------------------|-----------------------------------|-----------------|
-| Overlap | 2.80s | 2.06s | 4.40s |
-| Overlap (single chromosome) | 6.73s | 5.19s | 10.06s |
-| Nearest | 2.27s | 1.5s | 42.16s |
-| Nearest (single chromosome) | 4.7s | 4.67s | 11.01s |
+| Operation                   | Python/GenomicRanges | Python/GenomicRanges (5 threads) | R/GenomicRanges |
+| --------------------------- | -------------------- | -------------------------------- | --------------- |
+| Overlap                     | 2.80s                | 2.06s                            | 4.40s           |
+| Overlap (single chromosome) | 6.73s                | 5.19s                            | 10.06s          |
+| Nearest                     | 2.27s                | 1.5s                             | 42.16s          |
+| Nearest (single chromosome) | 4.7s                 | 4.67s                            | 11.01s          |
 
 > [!NOTE]
 > The single chromosome benchmark ignores chromosome/sequence information and performs overlap operations solely on intervals.

docs/conf.py

@@ -315,6 +315,7 @@
     "biocutils": ("https://biocpy.github.io/BiocUtils", None),
     "iranges": ("https://biocpy.github.io/IRanges", None),
     "polars": ("https://docs.pola.rs/api/python/stable/", None),
+    "compressed-lists": ("https://biocpy.github.io/compressed-lists", None),
 }
 
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/tutorial.md

@@ -10,7 +10,7 @@ kernelspec:
 
 An `IRanges` holds a **start** position and a **width**, and is typically used to represent coordinates along a genomic sequence. The interpretation of the **start** position depends on the application; for sequences, the **start** is usually a 1-based position, but other use cases may allow zero or even negative values, e.g., circular genomes. Ends are considered inclusive. `IRanges` uses [LTLa/nclist-cpp](https://github.com/LTLA/nclist-cpp) under the hood to perform fast overlap and search-based operations.
 
-The package provides a `GenomicRanges` class to specify multiple genomic elements, typically where genes start and end. Genes are themselves made of many subregions, such as exons, and a `GenomicRangesList` enables the representation of this nested structure.
+The package provides a `GenomicRanges` class to specify multiple genomic elements, typically where genes start and end. Genes are themselves made of many subregions, such as exons, and a `CompressedGenomicRangesList` enables the representation of this nested structure.
 
 Moreover, the package also provides a `SeqInfo` class to update or modify sequence information stored in the object. Learn more about this in the [GenomeInfoDb package](https://bioconductor.org/packages/release/bioc/html/GenomeInfoDb.html).
 
@@ -68,10 +68,9 @@ human_gr = genomicranges.read_ucsc(genome="hg19")
 print(human_gr)
 ```
 
-
 ## Preferred way
 
-To construct a `GenomicRanges` object, we need to provide sequence information and genomic coordinates. This is achieved through the combination of the `seqnames` and `ranges` parameters. Additionally, you have the option to specify the `strand`, represented as a list of "+" (or 1) for the forward strand, "-" (or -1) for the reverse strand, or "*" (or 0) if the strand is unknown. You can also provide a NumPy vector that utilizes either the string or numeric representation to specify the `strand`. Optionally, you can use the `mcols` parameter to provide additional metadata about each genomic region.
+To construct a `GenomicRanges` object, we need to provide sequence information and genomic coordinates. This is achieved through the combination of the `seqnames` and `ranges` parameters. Additionally, you have the option to specify the `strand`, represented as a list of "+" (or 1) for the forward strand, "-" (or -1) for the reverse strand, or "\*" (or 0) if the strand is unknown. You can also provide a NumPy vector that utilizes either the string or numeric representation to specify the `strand`. Optionally, you can use the `mcols` parameter to provide additional metadata about each genomic region.
 
 ```{code-cell}
 from genomicranges import GenomicRanges
@@ -427,7 +426,7 @@ print(binned_avg_gr)
 ```
 
 ::: {tip}
-Now you might wonder how can I generate these ***bins***?
+Now you might wonder how can I generate these **_bins_**?
 :::
 
 # Generate tiles or bins
@@ -469,7 +468,7 @@ print(tiles)
 ```{code-cell}
 seqlengths = {"chr1": 100, "chr2": 75, "chr3": 200}
 
-tiles = GenomicRanges.tile_genome(seqlengths=seqlengths, n=10)
+tiles = GenomicRanges.tile_genome(seqlengths=seqlengths, ntile=10)
 print(tiles)
 ```
 
@@ -547,8 +546,6 @@ query_hits = gr.nearest(find_regions)
 
 query_hits = gr.precede(find_regions)
 
-query_hits = gr.follow(find_regions)
-
 print(query_hits)
 ```
 
@@ -609,7 +606,7 @@ print(combined)
 # Misc operations
 
 - **invert_strand**: flip the strand for each interval
-- **sample**: randomly choose ***k*** intervals
+- **sample**: randomly choose **_k_** intervals
 
 ```{code-cell}
 # invert strand
@@ -619,20 +616,22 @@ inv_gr = gr.invert_strand()
 samp_gr = gr.sample(k=4)
 ```
 
-# `GenomicRangesList` class
+# `CompressedGenomicRangesList` class
 
-Just as it sounds, a `GenomicRangesList` is a named-list like object.
+Just as it sounds, a `CompressedGenomicRangesList` is a named-list like object.
 
 If you are wondering why you need this class, a `GenomicRanges` object enables the
 specification of multiple genomic elements, usually where genes start and end.
 Genes, in turn, consist of various subregions, such as exons.
-The `GenomicRangesList` allows us to represent this nested structure.
+The `CompressedGenomicRangesList` allows us to represent this nested structure.
 
 As of now, this class has limited functionality, serving as a read-only class with basic accessors.
 
 ```{code-cell}
+from genomicranges import CompressedGenomicRangesList, GenomicRanges
+from iranges import IRanges
+from biocframe import BiocFrame
 
-from genomicranges import GenomicRangesList
 a = GenomicRanges(
     seqnames=["chr1", "chr2", "chr1", "chr3"],
     ranges=IRanges([1, 3, 2, 4], [10, 30, 50, 60]),
@@ -647,33 +646,17 @@ b = GenomicRanges(
     mcols=BiocFrame({"score": [2, 3, 4]}),
 )
 
-grl = GenomicRangesList(ranges=[a,b], names=["gene1", "gene2"])
+grl = CompressedGenomicRangesList.from_list(lst=[a,b], names=["gene1", "gene2"])
 print(grl)
 ```
 
-
 ## Properties
 
 ```{code-cell}
 grl.start
 grl.width
 ```
 
-## Combine `GenomicRangeslist` object
-
-Similar to the combine function from `GenomicRanges`,
-
-```{code-cell}
-grla = GenomicRangesList(ranges=[a], names=["a"])
-grlb = GenomicRangesList(ranges=[b, a], names=["b", "c"])
-
-# or use the combine generic
-from biocutils.combine import combine
-cgrl = combine(grla, grlb)
-```
-
-The functionality in `GenomicRangesLlist` is limited to read-only and a few methods. Updates are expected to be made as more features become available.
-
 ## Empty ranges
 
 Both of these classes can also contain no range information, and they tend to be useful when incorporates into larger data structures but do not contain any data themselves.
@@ -686,15 +669,7 @@ empty_gr = GenomicRanges.empty()
 print(empty_gr)
 ```
 
-Similarly, an empty `GenomicRangesList` can be created:
-
-```{code-cell}
-empty_grl = GenomicRangesList.empty(n=100)
-
-print(empty_grl)
-```
-
-----
+---
 
 ## Futher reading
 

src/genomicranges/__init__.py

@@ -19,4 +19,4 @@
 from .grangeslist import CompressedGenomicRangesList
 from .io.gtf import read_gtf
 from .io.ucsc import read_ucsc
-from .SeqInfo import SeqInfo
+from .sequence_info import SeqInfo

src/genomicranges/granges.py

@@ -10,7 +10,7 @@
 from biocframe import BiocFrame
 from iranges import IRanges
 
-from .SeqInfo import SeqInfo, merge_SeqInfo
+from .sequence_info import SeqInfo, merge_SeqInfo
 from .utils import (
     STRAND_MAP,
     compute_up_down,
@@ -3122,7 +3122,7 @@ def binned_average(
     #######################
 
     def split(self, groups: list) -> "CompressedGenomicRangesList":
-        """Split the `GenomicRanges` object into a :py:class:`~genomicranges.GenomicRangesList.GenomicRangesList`.
+        """Split the `GenomicRanges` object into a :py:class:`~genomicranges.grangeslist.CompressedGenomicRangesList`.
 
         Args:
             groups:
@@ -3132,7 +3132,7 @@ def split(self, groups: list) -> "CompressedGenomicRangesList":
                 in the object.
 
         Returns:
-            A `GenomicRangesList` containing the groups and their
+            A `CompressedGenomicRangesList` containing the groups and their
             corresponding elements.
         """
 
@@ -3188,7 +3188,7 @@ def subtract(
                 Defaults to False.
 
         Returns:
-            A `GenomicRangesList` with the same size as ``self`` containing
+            A `CompressedGenomicRangesList` with the same size as ``self`` containing
             the subtracted regions.
         """
 
@@ -3220,6 +3220,78 @@ def subtract(
 
         return CompressedGenomicRangesList.from_list(lst=psetdiff.values(), names=list(psetdiff.keys()))
 
+    ##########################
+    ######>> pairwise <<######
+    ##########################
+
+    def pintersect(self, other: GenomicRanges, ignore_strand: bool = False) -> GenomicRanges:
+        """Parallel intersection of genomic ranges.
+
+        Computes the intersection for each parallel pair of ranges in ``self`` and ``other``.
+        If seqnames mismatch or strands are incompatible (and not ignored), the result
+        for that index is an empty range (width 0).
+
+        Args:
+            other:
+                The other ``GenomicRanges`` object. Must have the same length as ``self``.
+
+            ignore_strand:
+                Whether to ignore strands. Defaults to False.
+
+        Returns:
+            A new ``GenomicRanges`` object.
+        """
+        if len(self) != len(other):
+            raise ValueError("'self' and 'other' must have the same length.")
+
+        merged_seqinfo = merge_SeqInfo([self.seqinfo, other.seqinfo])
+
+        s_names = self.get_seqnames(as_type="list")
+        o_names = other.get_seqnames(as_type="list")
+
+        s_strand = self.get_strand(as_type="numpy")
+        o_strand = other.get_strand(as_type="numpy")
+
+        new_starts = np.maximum(self.start, other.start)
+        new_ends = np.minimum(self.end, other.end)
+
+        match_seqnames = np.array([x == y for x, y in zip(s_names, o_names)])
+
+        if not ignore_strand:
+            match_strands = (s_strand * o_strand) != -1
+            mask = match_seqnames & match_strands
+        else:
+            mask = match_seqnames
+
+        no_overlap = new_starts > new_ends
+        invalid = (~mask) | no_overlap
+
+        final_starts = new_starts.copy()
+        final_ends = new_ends.copy()
+
+        final_starts[invalid] = 1
+        final_ends[invalid] = 0
+
+        final_widths = final_ends - final_starts + 1
+        final_widths[final_widths < 0] = 0
+
+        if ignore_strand:
+            new_strands = np.zeros(len(self), dtype=int)
+        else:
+            new_strands = s_strand.copy()
+            use_other = s_strand == 0
+            new_strands[use_other] = o_strand[use_other]
+            new_strands[invalid] = 0
+
+        new_ranges = IRanges(final_starts, final_widths)
+
+        return GenomicRanges(
+            seqnames=s_names,
+            ranges=new_ranges,
+            strand=new_strands,
+            seqinfo=merged_seqinfo,
+        )
+
 
 def _fast_combine_GenomicRanges(*x: GenomicRanges) -> GenomicRanges:
     return GenomicRanges(