Merge branch 'master' into fuse-unmount

Author: nvictus

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: master
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Build
+        run: hatch run docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: './docs/_build/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+

.gitignore

@@ -6,6 +6,7 @@ __pycache__/
 .ipynb_checkpoints/
 demo/
 notebooks/mnt/
+docs/_build/
 dist/
 
 hg/_version.py

README.md

@@ -41,25 +41,40 @@ view_lock = hg.lock(view1, view2)
 
 ## Development
 
-Create a virtual environment with Jupyter installed.
+**higlass-python** uses [the recommended](https://packaging.python.org/en/latest/flow/#) `hatchling` build-system,
+which is convenient to use via the [`hatch` CLI](https://hatch.pypa.io/latest/). We recommend installing `hatch` 
+globally (e.g., via `pipx`) and running the various commands defined within `pyproject.toml`. `hatch` will take care
+of creating and synchronizing a virtual environment with all dependencies defined in `pyproject.toml`.
 
-```bash
-conda create -n higlass python=3.11 jupyterlab
-```
+### Commands Cheatsheet
 
-Install the package in _editable_ mode. The `.[dev]` ensures that you also install linting/testing tools.
+All commands are run from the root of the project, from a terminal:
 
-```bash
-pip install -e ".[dev]"
-```
+| Command                | Action                                                              |
+| :--------------------- | :------------------------------------------------------------------ |
+| `hatch run fix`        | Format project with `black .` and apply linting with `ruff --fix .` |
+| `hatch run lint`       | Lint project with `ruff .`.                                         |
+| `hatch run test`       | Run unit tests with `pytest` in latest Python version.              |
+| `hatch run test:test`  | Run unit tests with `pytest` in all target Python versions.         |
+| `hatch run docs:build` | Build the documentation in `docs/_build/html`.                      |
+| `hatch run docs:serve` | Start an dev-server for live editing RST files in `docs/`.          |
 
-Our CI checks formatting (`black .`), linting (`ruff .`), and tests (`pytest`).
+> **Note**: `hatch build` and `hatch publish` are available to build and publish the project to
+PyPI, but all releases are handled automatically via CI.
 
-## Editing the docs
+Alternatively, you can develop **higlass-python** by manually creating a virtual environment and
+managing installation and dependencies with `pip`. For example, create a virtual environment 
+with `conda`:
 
-To work on the docs, start the autoserver and edit the rst files in the `docs` directory:
+```bash
+conda create -n higlass python=3.11
+conda activate higlass
+```
+
+and install **higlass-python** in _editable_ mode with all optional dependencies:
 
 ```bash
-cd docs
-./serve.sh
+pip install -e ".[dev,fuse,docs]"
 ```
+
+Our CI checks formatting (`black .`), linting (`ruff .`), and tests (`pytest`).

docs/conf.py

@@ -3,6 +3,8 @@
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
+from higlass import __version__
+from pkg_resources import parse_version
 
 # -*- coding: utf-8 -*-
 #
@@ -58,24 +60,24 @@
 
 # General information about the project.
 project = "HiGlass"
-copyright = "2017-2020 HiGlass Authors"
+copyright = "2017-2023 HiGlass Authors"
 author = "HiGlass Authors"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = "v1.0"
+version = parse_version(__version__).base_version
 # The full version, including alpha/beta/rc tags.
-release = "v1.0"
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -108,7 +110,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -254,3 +256,6 @@ class Vimeo(IframeVideo):
 def setup(builder):
     directives.register_directive("youtube", Youtube)
     directives.register_directive("vimeo", Vimeo)
+
+
+autodoc_typehints = "none"

docs/examples.rst

@@ -5,80 +5,36 @@ Synchronizing location, zoom and value scales
 ---------------------------------------------
 
 To synchronize, the locations, zoom levels and value scales, use the provided
-``location_syncs``, ``zoom_syncs`` and ``value_scale_syncs`` parameters of
-the of the ``display`` function.
-
-The ``location_syncs`` and ``zoom_syncs`` parameters both take a list of lists
-of views which will have their location and / or zoom synchronized. While the
-HiGlass implementation allows for synching of location and zoom independently
-at a given offset, the Python API currently only allows synchronization at
-the same location and / or same zoom level. It is highly recommended that the
-zoom and location syncs are both provided and identical to ensure that zoom
-and location change together in the provided list of views.
-
-.. code-block:: python
-
-	from higlass.client import View, Track
-	import higlass
-
-	t1 = Track(track_type='top-axis', position='top')
-	t2 = Track(track_type='heatmap', position='center',
-	          tileset_uuid='CQMd6V_cRw6iCI_-Unl3PQ',
-	          server="http://higlass.io/api/v1/")
-
-	# the entire viewport has a width of 12 so a width of 6 for
-	# each view means they take up half the width
-	view1 = View([t1, t2], width=6)
-	view2 = View([t1, t2], width=6, x=6)
-
-	display, server, viewconf = higlass.display(
-	    [view1, view2],
-	    location_syncs = [[view1, view2]],
-	    zoom_syncs = [[view1, view2]],
-	    value_scale_syncs = [[(view1, t2), (view2, t2)]])
-	display
-
-
-BAM Files
----------
-
-View sequencing read mappings. First we must load the `higlass-pileup plugin track <https://github.com/higlass/higlass-pileup>`_:
+``hg.lock`` to create a lock object and then register the given lock for the
+visualization with ``hg.Viewconf.locks()``.
 
 .. code-block:: python
 
-	%%javascript
-
-	require(["https://unpkg.com/higlass-pileup/dist/higlass-pileup.min.js"],
-	    function(hglib) {
+    import higlass as hg
 
-	});
-
-And then we can view pileups:
-
-.. code-block:: python
+    ts = hg.remote(
+      uid='CQMd6V_cRw6iCI_-Unl3PQ',
+      server="http://higlass.io/api/v1/",
+    )
 
-	import higlass
-	from higlass.tilesets import Tileset, bam
-	from higlass.client import Track, View
+    # the entire viewport has a width of 12 so a width of 6 for
+    # each view means they take up half the width
+    view1 = hg.view(
+        ts.track("chromosome-labels"),
+        ts.track("heatmap"),
+        width=6,
+    )
 
-	filename = '../data/ont.10K.bam'
-	indexfile = '../data/ont.10K.bam.bai'
+    view2 = hg.view(
+        ts.track("chromosome-labels"),
+        ts.track("heatmap"),
+        width=6,
+    )
 
-	bam_ts = bam(filename, indexfile)
+    lock = hg.lock(view1, view2)
 
-	display, server, viewconf = higlass.display(
-	    [View([
-	        Track('top-axis', height=20),
-	        Track(track_type="pileup",
-	        	position='top', tileset=bam_ts, height=50 )
-	    ], initialXDomain = [
-	        0,
-	        2000
-	      ])]
-	)
-	display
+    (view1 | view2).locks(lock)
 
-.. image:: img/jupyter-pileup-no-code.png
 
 Multivec Files
 ---------------
@@ -98,70 +54,30 @@ Create the multivec and output file:
 
 .. code-block:: python
 
-	from clodius.multivec import create_multivec_multires
-    from higlass.tilesets import multivec
+    from clodius.multivec import create_multivec_multires
 
-	output_file = "/Users/pete/tmp/my_file.multires.hdf5"
+    output_file = "/Users/pete/tmp/my_file.multires.hdf5"
 
-	create_multivec_multires(
-	    array,
-	    [('chr1', chrom_len)],
-	    agg=lambda x: np.nansum(x.T.reshape((x.shape[1], -1, 2)), axis=2).T,
-	    starting_resolution=1,
-	    row_infos = ["match", 'a', 'g', 't'],
-	    output_file=output_file,
-	    tile_size=256
-	)
+    create_multivec_multires(
+        array,
+        [('chr1', chrom_len)],
+        agg=lambda x: np.nansum(x.T.reshape((x.shape[1], -1, 2)), axis=2).T,
+        starting_resolution=1,
+        row_infos = ["match", 'a', 'g', 't'],
+        output_file=output_file,
+        tile_size=256
+    )
 
-	ts = multivec(output_file)
 
 Create the viewer:
 
 .. code-block:: python
 
-	import higlass
-	from higlass.client import Track, View
-
-	display, server, viewconf = higlass.display(
-	    [View([
-	        Track('top-axis', height=20),
-	        Track(track_type="horizontal-stacked-bar", position='top', tileset=ts, height=50 )
-	    ], initialXDomain = [
-	        0,
-	        1000000
-	      ])]
-	)
-	display
-
-Bed-like data
--------------
-
-If you have data representing intervals in a Python object, you can load it
-directly into higlass using the `bedtiles` helper function:
-
-.. image:: img/beditems.png
-
-.. code-block:: python
-
-	from higlass.client import View, Track
-	from higlass.inline_tiles import bedtiles
-	import higlass
-
-	bed = [['chr1', 1000, 2000, 'item #1', '.', '+'],
-	       ['chr2', 3000, 3500, 'item #1', '.', '-']]
-
-	chroms = [['chr1', 2100], ['chr2', 4000]]
-
-
-	data = bedtiles(bed, chroms)
-	track = Track(track_type='bedlike', position='top',
-	              height=50, data=data, options={"minusStrandColor": "red"})
-
-
-	d,s,v = higlass.display([[track]])
-	d
-
+    import higlass as hg
 
-Note that this function loads all the data into the viewconf and does
-not use a server. Do not use this function with more than ~3000 items of
-data.
+    ts = multivec(output_file)
+    view = hg.view(
+        hg.track("top-axis", height=20),
+        ts.track("horizontal-stacked-bar", height=50),
+    )
+    view.domain(x=[0, 1000000])