feat: Replace higlass.tilesets.register with higlass.Tileset (#177)

* Replace `higlass.tilesets.register` with `higlass.Tileset`

The `register` naming is not very clear, and also the meta-programming
in the previous approach erased type information. By having a shared
based class, implementing a custom tileset is much nicer:

```py
from dataclasses import dataclass

import higlass as hg
from clodius.tiles import cooler

@DataClass
class MyCustomCoolerTileset(hg.Tileset):
    path: str
    datatype = "matrix"

    def tiles(self, tile_ids):
        return cooler.tiles(self.path, tile_ids)

    def info(self):
        return cooler.tileset_info(self.path)

ts = MyCustomCoolerTileset("test.mcool")
hg.view(ts.track())
```

* Remove _TilesetMixin

* Add docstring

Author: manzt

examples/JupyterServer.ipynb

@@ -29,7 +29,27 @@
    "id": "2e2c753f-fb13-4d54-b031-10cf5865e138",
    "metadata": {},
    "outputs": [],
-   "source": []
+   "source": [
+    "from dataclasses import dataclass\n",
+    "\n",
+    "from clodius.tiles.cooler import tiles, tileset_info\n",
+    "\n",
+    "\n",
+    "@dataclass\n",
+    "class MyCustomCoolerTileset(hg.Tileset):\n",
+    "    path: str\n",
+    "    datatype = \"matrix\"\n",
+    "\n",
+    "    def tiles(self, tile_ids):\n",
+    "        return tiles(self.path, tile_ids)\n",
+    "\n",
+    "    def info(self):\n",
+    "        return tileset_info(self.path)\n",
+    "\n",
+    "\n",
+    "ts = MyCustomCoolerTileset(\"test.mcool\")\n",
+    "hg.view(ts.track())"
+   ]
   },
   {
    "cell_type": "code",

src/higlass/__init__.py

@@ -10,6 +10,32 @@
 
 from higlass_schema import *
 
-import higlass.tilesets as tilesets
-from higlass.api import *
-from higlass.tilesets import bed2ddb, beddb, bigwig, cooler, hitile, multivec, remote
+from higlass.api import (
+    CombinedTrack,
+    EnumTrack,
+    HeatmapTrack,
+    IndependentViewportProjectionTrack,
+    PluginTrack,
+    TrackT,
+    View,
+    Viewconf,
+    ViewT,
+    combine,
+    concat,
+    divide,
+    hconcat,
+    lock,
+    track,
+    vconcat,
+    view,
+)
+from higlass.tilesets import (
+    Tileset,
+    bed2ddb,
+    beddb,
+    bigwig,
+    cooler,
+    hitile,
+    multivec,
+    remote,
+)

src/higlass/api.py

@@ -3,7 +3,6 @@
 import functools
 from collections import defaultdict
 from typing import (
-    TYPE_CHECKING,
     ClassVar,
     Generic,
     Literal,
@@ -38,8 +37,6 @@
     "view",
 ]
 
-if TYPE_CHECKING:
-    from higlass._track_helper import TrackHelper
 
 ## Mixins
 
@@ -124,46 +121,16 @@ def opts(
         return track
 
 
-class _TilesetMixin:
-    def tileset(
-        self: TrackT,  # type: ignore
-        tileset: TrackHelper,
-        inplace: bool = False,
-    ) -> TrackT:  # type: ignore
-        """Replace or add a tileset to a Track.
-
-        A convenience method to update a track with a tileset.
-
-        Parameters
-        ----------
-        tileset : TilesetResource
-            A tileset resource returned from `hg.server`.
-
-        inplace : bool, optional
-            Whether to modify the existing track in place or return
-            a new track (default: `False`)
-
-        Returns
-        -------
-        track : A track with the bound tileset.
-
-        """
-        track = self if inplace else utils.copy_unique(self)
-        track.server = tileset.server
-        track.tilesetUid = tileset.tileset.uid
-        return track
-
-
 ## Extend higlass-schema classes
 
 
-class EnumTrack(hgs.EnumTrack, _OptionsMixin, _PropertiesMixin, _TilesetMixin):
+class EnumTrack(hgs.EnumTrack, _OptionsMixin, _PropertiesMixin):
     """Represents a generic track."""
 
     ...
 
 
-class HeatmapTrack(hgs.HeatmapTrack, _OptionsMixin, _PropertiesMixin, _TilesetMixin):
+class HeatmapTrack(hgs.HeatmapTrack, _OptionsMixin, _PropertiesMixin):
     """Represets a specialized heatmap track."""
 
     ...
@@ -173,20 +140,19 @@ class IndependentViewportProjectionTrack(
     hgs.IndependentViewportProjectionTrack,
     _OptionsMixin,
     _PropertiesMixin,
-    _TilesetMixin,
 ):
     """Represents a view-independent viewport projection track."""
 
     ...
 
 
-class CombinedTrack(hgs.CombinedTrack, _OptionsMixin, _PropertiesMixin, _TilesetMixin):
+class CombinedTrack(hgs.CombinedTrack, _OptionsMixin, _PropertiesMixin):
     """Represents a track combining multiple tracks."""
 
     ...
 
 
-class PluginTrack(hgs.BaseTrack, _OptionsMixin, _PropertiesMixin, _TilesetMixin):
+class PluginTrack(hgs.BaseTrack, _OptionsMixin, _PropertiesMixin):
     """Represents an unknown plugin track."""
 
     plugin_url: ClassVar[str]

src/higlass/tilesets.py

@@ -1,21 +1,22 @@
 from __future__ import annotations
 
+import abc
 import functools
 import pathlib
 import typing
 from dataclasses import dataclass
 
 import higlass.api
-from higlass._tileset_registry import TilesetInfo, TilesetProtocol, TilesetRegistry
+from higlass._tileset_registry import TilesetInfo, TilesetRegistry
 from higlass._utils import TrackType, datatype_default_track
 
 __all__ = [
+    "Tileset",
     "bed2ddb",
     "bigwig",
     "cooler",
     "hitile",
     "multivec",
-    "register",
     "remote",
 ]
 
@@ -29,19 +30,60 @@
     "vector",
 ]
 
-T = typing.TypeVar("T", bound=TilesetProtocol)
 
+@dataclass
+class RemoteTileset:
+    uid: str
+    server: str
+    name: str | None = None
+
+    def track(self, type_: TrackType, **kwargs):
+        track = higlass.api.track(
+            type_=type_,
+            server=self.server,
+            tilesetUid=self.uid,
+            **kwargs,
+        )
+        if self.name is not None:
+            track.opts(name=self.name, inplace=True)
+        return track
+
+
+def remote(
+    uid: str, server: str = "https://higlass.io/api/v1", name: str | None = None
+):
+    """Create a remote tileset reference.
 
-def register(klass: type[T]) -> type[T]:
-    """Decorator that adds a `track` method to a class implementing `TilesetProtocol`.
+    Parameters
+    ----------
+    uid : str
+        The unique identifier for the remote tileset.
+    server : str, optional
+        The HiGlass server URL (default is "https://higlass.io/api/v1").
+    name : str, optional
+        An optional name for the tileset.
+
+    Returns
+    -------
+    RemoteTileset
+        A RemoteTileset instance that can be used to create HiGlass tracks.
+    """
+    return RemoteTileset(uid, server, name)
 
-    The `track` method automatically registers the tileset with the `TilesetRegistry`
-    and returns a HiGlass track object, which can be used for visualization.
+
+class Tileset(abc.ABC):
+    """Base class for defining custom tilesets in `higlass`.
+
+    Subclasses must implement the `tiles` and `info` methods.
+
+    The provided `track` method is a helper which automatically registers the
+    tileset with the `TilesetRegistry` and returns a HiGlass track object
+    ready for visualization.
 
     Parameters
     ----------
     klass : type[T]
-        A class that implements `TilesetProtocol`.
+        A class implementing `TilesetProtocol`.
 
     Returns
     -------
@@ -50,12 +92,12 @@ def register(klass: type[T]) -> type[T]:
 
     Examples
     --------
+    >>> import higlass as hg
     >>> from dataclasses import dataclass
-    >>> from clodius.tiles.cooler import tiles, tileset_info
+    >>> from clodius.tiles import cooler
     >>>
-    >>> @register
     >>> @dataclass
-    >>> class MyCoolerTileset:
+    >>> class MyCoolerTileset(hg.Tileset):
     >>>     filepath: str
     >>>     datatype = "matrix"
     >>>
@@ -66,12 +108,16 @@ def register(klass: type[T]) -> type[T]:
     >>>         return tiles(self.filepath, tile_ids)
     >>>
     >>> tileset = MyCoolerTileset("test.mcool")
-    >>> track = tileset.track("heatmap")
+    >>> hg.view(tileset.track("heatmap"))
     """
 
-    def track(
-        self: TilesetProtocol, type_: TrackType | None = None, /, **kwargs
-    ) -> higlass.api.Track:
+    @abc.abstractmethod
+    def tiles(self, tile_ids: typing.Sequence[str], /) -> list[dict]: ...
+
+    @abc.abstractmethod
+    def info(self) -> TilesetInfo: ...
+
+    def track(self, type_: TrackType | None = None, /, **kwargs) -> higlass.api.Track:
         """
         Create a HiGlass track for the tileset.
 
@@ -111,53 +157,9 @@ def track(
 
         return track
 
-    setattr(klass, "track", track)
-    return klass
-
-
-@dataclass
-class RemoteTileset:
-    uid: str
-    server: str
-    name: str | None = None
-
-    def track(self, type_: TrackType, **kwargs):
-        track = higlass.api.track(
-            type_=type_,
-            server=self.server,
-            tilesetUid=self.uid,
-            **kwargs,
-        )
-        if self.name is not None:
-            track.opts(name=self.name, inplace=True)
-        return track
-
-
-def remote(
-    uid: str, server: str = "https://higlass.io/api/v1", name: str | None = None
-):
-    """Create a remote tileset reference.
-
-    Parameters
-    ----------
-    uid : str
-        The unique identifier for the remote tileset.
-    server : str, optional
-        The HiGlass server URL (default is "https://higlass.io/api/v1").
-    name : str, optional
-        An optional name for the tileset.
-
-    Returns
-    -------
-    RemoteTileset
-        A RemoteTileset instance that can be used to create HiGlass tracks.
-    """
-    return RemoteTileset(uid, server, name)
-
 
-@register
 @dataclass
-class ClodiusTileset(TilesetProtocol):
+class ClodiusTileset(Tileset):
     datatype: DataType
     tiles_impl: typing.Callable[[typing.Sequence[str]], list[typing.Any]]
     info_impl: typing.Callable[[], TilesetInfo]

test/test_tileset_registery.py

@@ -5,7 +5,7 @@
 import pytest
 
 from higlass._tileset_registry import TilesetRegistry
-from higlass.tilesets import ClodiusTileset, register
+from higlass.tilesets import ClodiusTileset, Tileset
 
 
 def mock_tileset() -> ClodiusTileset:
@@ -42,8 +42,7 @@ def test_tilesets_are_weakly_referenced(Registry: type[TilesetRegistry]) -> None
 
 
 def test_custom_tileset_without_uid(Registry: type[TilesetRegistry]) -> None:
-    @register
-    class MyTileset:
+    class MyTileset(Tileset):
         def tiles(self, tile_ids: typing.Sequence[str]) -> list[typing.Any]:
             return []