Documentation updates and minor fixes (#28)

* Update panel version, add watchfiles and use Viewer for app

* Rename immutable_id to predefined

* Add license

* Update dev docs to describe admin panel and dev mode

* Remove obsolete configuration value width_policy

* Add example to docstring

* Fix github actions syntax

* Comment out failing github actions line

* Remove Python 3.13

* Recomment failing actions line

* Fix ignn formatting

* Make rye fmt ignore _version.py

Author: percyfal

.github/workflows/ci.yml

@@ -7,15 +7,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        py: ["3.12", "3.13"]
+        py: ["3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: eifinger/setup-rye@v3
-      - run: rye pin $
+      - run: rye pin ${{ matrix.py }}
       - run: |
           rye sync
-          [[ -n $(git diff --stat requirements.lock) ]] && exit 1
-      - run: rye fmt --check
+          # [[ -n $(git diff --stat requirements.lock) ]] && exit 1
+      - run: rye fmt --check $( find src/tseda -name "*.py" | grep -v _version.py )
       - run: rye lint src
       - run: rye run check
       - run: rye run test

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributor guide 
+# Contributor guide
 
 Thank you for your interest in improving this project. This project is
 open-source under the [MIT license] and welcomes contributions in the
@@ -21,16 +21,16 @@ introduction to rye, see the [postmodern python] blog post.
 Use rye to add and remove dependencies from `pyproject.toml`.
 Development packages are added by applying the `--dev` flag:
 
-	rye add package
-	rye add dev-package --dev
-	rye remove package
-	rye remove dev-package --dev
+    rye add package
+    rye add dev-package --dev
+    rye remove package
+    rye remove dev-package --dev
 
 After modifying dependencies, make sure to run `rye sync` to update
 the virtual environment.
 
 [rye]: https://rye.astral.sh/
-[postmodern python]: https://rdrn.me/postmodern-python/ 
+[postmodern python]: https://rdrn.me/postmodern-python/
 
 ## Virtual environment
 
@@ -40,7 +40,7 @@ you have `pyenv` installed you may run into the issue that nothing
 seems to load. This is a known issue (see [pyenv issue]). You can
 always run programs in the virtual environment with `rye run`, e.g.,
 
-	rye run pytest -v -s
+    rye run pytest -v -s
 
 [pyenv issue]: https://github.com/astral-sh/rye/issues/317
 
@@ -49,25 +49,44 @@ always run programs in the virtual environment with `rye run`, e.g.,
 rye provides support for Python code formatting, linting, and more.
 The steps can be run separately
 
-	rye fmt
-	rye lint --fix
-	rye run check
-	rye test
-	
-Alternativel, you can run the entire toolchain with
+    rye fmt
+    rye lint --fix
+    rye run check
+    rye test
 
-	rye run all
+Alternatively, you can run the entire toolchain with
+
+    rye run all
 
 ## Development with small test data set
 
 Development is facilitated by loading the small data set that is
 provided and reloading upon code changes:
 
-	rye run python -m tseda tests/data/test.trees
-	
+    rye run python -m tseda tests/data/test.trees
+
 The test data is a modified simulation of the [out of Africa]
 demographic model (stdpopsim model `OutOfAfrica_3G09`), amended with
 three outgroup species. The geolocations are dummy locations meant to
 reflect typical metadata.
 
 [out of africa]: https://github.com/popsim-consortium/stdpopsim/blob/main/stdpopsim/catalog/HomSap/demographic_models.py
+
+## Monitoring resource usage and user behaviour
+
+The `--admin` option will activate the `/admin` panel:
+
+    rye run python -m tseda tests/data/test.trees --admin
+
+If the project is served locally on port 5006, the `/admin` endpoint
+would be available at `http://localhost:5006/admin. See [admin] for
+more information.
+
+[admin]: https://panel.holoviz.org/how_to/profiling/admin.html
+
+## Serving the application in development mode
+
+For interactive development, you can serve the app in development mode
+with `panel serve`:
+
+    rye run panel serve src/tseda --dev --show --args tests/data/test.trees

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tskit developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyproject.toml

@@ -5,7 +5,7 @@ authors = [
     { name = "Per Unneberg", email = "[email protected]" }
 ]
 dependencies = [
-    "panel~=1.5.2",
+    "panel~=1.5.3",
     "tskit~=0.5.8",
     "tszip~=0.2.5",
     "click~=8.1.7",
@@ -46,12 +46,13 @@ packages = ["src/tseda"]
 managed = true
 dev-dependencies = [
     "jupyter~=1.0.0",
-    "pyright~=1.1.386",
+    "pyright~=1.1.388",
     "pytest~=8.3.2",
     "stdpopsim~=0.2.0",
     "geodatasets~=2024.7.0",
     "pip~=24.2",
     "hatch-vcs~=0.4.0",
+    "watchfiles~=0.24.0",
 ]
 
 [project.scripts]
@@ -96,4 +97,4 @@ test = "rye test"
 all = { chain = ["fmt", "lint", "check", "test"] }
 
 [tool.pytest.ini_options]
-addopts = "--doctest-modules"
+addopts = "--doctest-modules --ignore src/tseda/main.py"

requirements-dev.lock

@@ -13,6 +13,7 @@
 anyio==4.4.0
     # via httpx
     # via jupyter-server
+    # via watchfiles
 appdirs==1.4.4
     # via stdpopsim
     # via tseda
@@ -334,7 +335,7 @@ pandas==2.2.2
     # via xarray
 pandocfilters==1.5.1
     # via nbconvert
-panel==1.5.2
+panel==1.5.3
     # via geoviews
     # via holoviews
     # via hvplot
@@ -400,7 +401,7 @@ pyproj==3.6.1
     # via cartopy
     # via geopandas
     # via geoviews
-pyright==1.1.386
+pyright==1.1.388
 pyshp==2.3.1
     # via cartopy
 pyslim==1.0.4
@@ -544,6 +545,7 @@ uri-template==1.3.0
     # via jsonschema
 urllib3==2.2.2
     # via requests
+watchfiles==0.24.0
 wcwidth==0.2.13
     # via prompt-toolkit
 webcolors==24.8.0

requirements.lock

@@ -162,7 +162,7 @@ pandas==2.2.2
     # via hvplot
     # via panel
     # via xarray
-panel==1.5.2
+panel==1.5.3
     # via geoviews
     # via holoviews
     # via hvplot

src/tseda/__main__.py

@@ -97,14 +97,17 @@ def preprocess(tszip_path, output):
     default=True,
     help="Launch a web-browser showing the app",
 )
+@click.option(
+    "--admin", default=False, is_flag=True, help="Add bokeh admin panel"
+)
 @click.option("--log-level", default="INFO", help="Logging level")
 @click.option(
     "--no-log-filter",
     default=False,
     is_flag=True,
     help="Do not filter the output log (advanced debugging only)",
 )
-def serve(path, port, show, log_level, no_log_filter):
+def serve(path, port, show, log_level, no_log_filter, admin):
     """
     Run the tseda datastore server, version based on View base class.
     """
@@ -123,7 +126,7 @@ def serve(path, port, show, log_level, no_log_filter):
         title="TSEda Datastore App",
         views=[IndividualsTable],
     )
-    pn.serve(app_.view(), port=port, show=show, verbose=False)
+    pn.serve(app_.view(), port=port, show=show, verbose=False, admin=admin)
 
 
 if __name__ == "__main__":

src/tseda/app.py

@@ -5,6 +5,7 @@
 import panel as pn
 import param
 from holoviews import opts
+from panel.viewable import Viewer
 
 from tseda import config, datastore, pages, vpages
 
@@ -84,8 +85,7 @@ def get_sidebar(selected_page):
         return template
 
 
-# class DataStoreApp(Viewer):
-class DataStoreApp(param.Parameterized):
+class DataStoreApp(Viewer):
     datastore = param.ClassSelector(class_=datastore.DataStore)
 
     title = param.String()
@@ -114,14 +114,6 @@ def __init__(self, **params):
             else pn.state.curdoc.unhold()
         )
 
-    def servable(self):
-        if pn.state.served:
-            return self._template.servable()
-        return self
-
-    def show(self, selected_page):
-        yield self.pages[selected_page]
-
     @param.depends("views")
     def view(self):
         page_titles = list(self.pages.keys())

src/tseda/datastore.py

@@ -24,7 +24,7 @@ def make_individuals_table(tsm):
 def make_sample_sets_table(tsm):
     result = []
     for ts_pop in tsm.ts.populations():
-        ss = SampleSet(id=ts_pop.id, population=ts_pop, immutable_id=True)
+        ss = SampleSet(id=ts_pop.id, population=ts_pop, predefined=True)
         result.append(ss)
     return SampleSetsTable(table=pd.DataFrame(result))
 
@@ -197,17 +197,17 @@ def sidebar(self):
 
 
 class SampleSetsTable(Viewer):
-    default_columns = ["name", "color", "immutable_id"]
+    default_columns = ["name", "color", "predefined"]
     editors = {k: None for k in default_columns}
     editors["color"] = {
         "type": "list",
         "values": config.COLORS,
         "valueLookup": True,
     }
-    editors["name"] = {"type": "input"}
+    editors["name"] = {"type": "input", "validator": "unique", "search": True}
     formatters = {
         "color": {"type": "color"},
-        "immutable_id": {"type": "tickCross"},
+        "predefined": {"type": "tickCross"},
     }
 
     create_sample_set_textinput = param.String(
@@ -247,7 +247,7 @@ def __panel__(self):
             self.create_sample_set_textinput = None
         table = pn.widgets.Tabulator(
             self.data,
-            layout="fit_columns",
+            layout="fit_data_table",
             selectable=True,
             page_size=100,
             pagination="remote",
@@ -260,14 +260,14 @@ def __panel__(self):
     def sidebar_table(self):
         table = pn.widgets.Tabulator(
             self.data,
-            layout="fit_columns",
+            layout="fit_data_table",
             selectable=True,
             page_size=100,
             pagination="remote",
             margin=10,
             formatters=self.formatters,
             editors=self.editors,
-            hidden_columns=["id", "immutable_id"],
+            hidden_columns=["id"],
         )
         return pn.Card(
             pn.Column(self.tooltip, table),

src/tseda/model.py

@@ -93,7 +93,7 @@ class SampleSet:
     name: str = None
     color: str = None
     population: dataclasses.InitVar[tskit.Population | None] = None
-    immutable_id: bool = False
+    predefined: bool = False
 
     colormap = config.COLORS
 

src/tseda/pages/gnnhaplotype.py

@@ -21,7 +21,6 @@
 import param
 
 hv.extension("bokeh")
-pn.extension(width_policy="max")
 
 
 def make_windows(window_size, sequence_length):

src/tseda/vpages/ignn.py

@@ -143,7 +143,7 @@ class VBar(View):
         doc=(
             "Change sort order within sample sets. Default is "
             "to sort by sample index. Provide a list of strings "
-            "where items correspond to sample set names."
+            'where items correspond to sample set names, e.g. `["sampleset"]`.'
         ),
     )