.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
         - id: rst-directive-colons
         - id: rst-inline-touching-normal
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.7.2
+      rev: v0.8.1
       hooks:
         - id: ruff
         - id: ruff-format

README.md

@@ -23,7 +23,7 @@ conda activate movement-env
 ```
 
 > [!Note]
-> Read the [documentation](https://movement.neuroinformatics.dev) for more information, including [full installation instructions](https://movement.neuroinformatics.dev/getting_started/installation.html) and [examples](https://movement.neuroinformatics.dev/examples/index.html).
+> Read the [documentation](https://movement.neuroinformatics.dev) for more information, including [full installation instructions](https://movement.neuroinformatics.dev/user_guide/installation.html) and [examples](https://movement.neuroinformatics.dev/examples/index.html).
 
 ## Overview
 
@@ -61,7 +61,9 @@ Find out more on our [mission and scope](https://movement.neuroinformatics.dev/c
 Contributions to movement are absolutely encouraged, whether to fix a bug, develop a new feature, or improve the documentation.
 To help you get started, we have prepared a detailed [contributing guide](https://movement.neuroinformatics.dev/community/contributing.html).
 
-You are welcome to chat with the team on [zulip](https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement). You can also [open an issue](https://github.com/neuroinformatics-unit/movement/issues) to report a bug or request a new feature.
+- [Chat with the team on Zulip](https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement).
+- [Open an issue](https://github.com/neuroinformatics-unit/movement/issues) to report a bug or request a new feature.
+- [Follow this Zulip topic](https://neuroinformatics.zulipchat.com/#narrow/channel/406001-Movement/topic/Community.20Calls) to receive updates about upcoming Community Calls.
 
 ## Citation
 

docs/requirements.txt

@@ -1,4 +1,5 @@
 -e .
+ablog
 linkify-it-py
 myst-parser
 nbsphinx
@@ -8,5 +9,6 @@ sphinx
 sphinx-autodoc-typehints
 sphinx-design
 sphinx-gallery
+sphinx-notfound-page
 sphinx-sitemap
 tables

docs/source/_templates/api_index_head.rst

@@ -3,7 +3,7 @@
 
 .. _target-api:
 
-API Reference
+API reference
 =============
 
 Information on specific functions, classes, and methods.

docs/source/blog/index.md

@@ -0,0 +1,9 @@
+# Blog
+
+```{postlist}
+:list-style: circle
+:category:
+:date: "%B %d, %Y"
+:format: "{date} | {title}, by {author}"
+:excerpts:
+```

docs/source/blog/movement-v0_0_21.md

@@ -0,0 +1,95 @@
+---
+blogpost: true
+date: Dec 5, 2024
+author: Niko Sirmpilatze
+location: London, England
+category: release
+language: English
+---
+
+# Release v0.0.21 and next steps
+
+_This is our inaugaural blogpost, containing a summary of the `v0.0.21` release and a preview of what's coming next in 2025._
+
+## What's new in movement v0.0.21?
+
+:::{tip}
+See our [installation guide](target-installation) for instructions on how to
+install the latest version or upgrade from an existing installation.
+:::
+
+__Input/Output__
+
+- We have added the {func}`movement.io.load_poses.from_multiview_files` function to support loading pose tracking data from multiple camera views.
+- We have made several small improvements to reading bounding boxes tracks. See our new {ref}`example <sphx_glr_examples_load_and_upsample_bboxes.py>` to learn more about working with bounding boxes.
+- We have added a new {ref}`example <sphx_glr_examples_convert_file_formats.py>` on using `movement` to convert pose tracking data between different file formats.
+
+__Kinematics__
+
+The {mod}`kinematics <movement.kinematics>` module has been moved from `movement.analysis.kinematics` to `movement.kinematics` and packs a number of new functions:
+- {func}`compute_forward_vector <movement.kinematics.compute_forward_vector>`
+- {func}`compute_head_direction_vector <movement.kinematics.compute_head_direction_vector>`
+- {func}`compute_pairwise_distances <movement.kinematics.compute_pairwise_distances>`
+- {func}`compute_speed <movement.kinematics.compute_speed>`
+- {func}`compute_path_length <movement.kinematics.compute_path_length>`
+
+__Breaking changes__
+
+- We have dropped support for using filtering and
+kinematic functions via the `move` accessor syntax,
+because we've found the concept hard to convey to new users. All functions are henceforth solely accessible by importing them from the relevant modules. Having one way of doing things simplifies the mental model for users and reduces the maintenance effort on our side. See an example below:
+
+  ```python
+  # Instead of:
+  position_filt = ds.move.median_filter(window=5)
+  velocity = ds.move.compute_velocity()
+
+  # Use:
+  from movement.filtering import median_filter
+  from movement.kinematics import compute_velocity
+
+  position_filt = median_filter(ds.position, window=5)
+  velocity = compute_velocity(ds.position)
+  ```
+- We have slightly modified the [structure of movement datasets](target-poses-and-bboxes-dataset), by changing the order of dimensions. This should have no effect when indexing data by dimension names, i.e. using the {meth}`xarray.Dataset.sel` or {meth}`xarray.Dataset.isel` methods. However, you may need to update your code if you are using Numpy-style indexing, for example:
+
+  ```python
+  # Indexing with dimension names (recommended, works always)
+  position = ds.position.isel(
+      individuals=0, keypoints=-1     # first individual, last keypoint
+  )
+
+  # Numpy-style indexing with the old dimension order (will no longer work)
+  position = ds.position[:, 0, -1, :]  # time, individuals, keypoints, space
+
+  # Numpy-style indexing with the updated dimension order (use this instead)
+  position = ds.position[:, :, -1, 0]  # time, space, keypoints, individuals
+  ```
+
+
+## Looking to v0.1 and beyond
+
+Over the last 1.5 years, we have gradually built up the core functionalities we envisioned for `movement` version `v0.1`,
+as described in our [roadmap](target-roadmaps).
+These have included [input/output support](target-io) for a few popular animal tracking frameworks, as well as methods for data cleaning and computing kinematic variables.
+
+What we're still missing is a [napari](napari:) plugin for `movement`, which we envision both as an interactive visualisation framework for motion tracking data as well as a graphical user interface for `movement`.
+We have been working on a minimal version of this plugin for a while and are expecting to ship it as part of the `v0.1` release in early 2025.
+
+After `v0.1`, we'll be switching to [semantic versioning](https://semver.org/), as it applies to MINOR (new features) and PATCH (bug fixes) versions. Until we are ready for a `v1` MAJOR version, we cannot commit to backward compatibility, but any breaking changes will be clearly communicated in the release notes.
+
+## Announcing movement Community Calls
+
+We are committed to fostering openness, transparency, and a strong sense of
+community within the `movement` project.
+Starting next year, we will host regular Community Calls via Zoom.
+
+The calls will take place every second Friday from **11:00 to 11:45 GMT**,
+beginning on **10 January 2025**.
+These calls are open to anyone interested in contributing to `movement` or
+sharing feedback on the project's progress and direction.
+
+A few days before each call, we will post an announcement on Zulip with the Zoom link and agenda.
+We encourage everyone who's interested in
+joining to follow this [Zulip topic](movement-community-calls:)
+to stay updated.

docs/source/conf.py

@@ -44,10 +44,12 @@
     "sphinx.ext.intersphinx",
     "myst_parser",
     "nbsphinx",
+    "notfound.extension",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
     "sphinx_sitemap",
     "sphinx.ext.autosectionlabel",
+    "ablog",
 ]
 
 # Configure the myst parser to enable cool markdown features
@@ -109,11 +111,12 @@
         "dependencies": ["environment.yml"],
     },
     "reference_url": {"movement": None},
-    "default_thumb_file": "source/_static/data_icon.png",  # default thumbnail image  
+    "default_thumb_file": "source/_static/data_icon.png",  # default thumbnail image
     "remove_config_comments": True,
     # do not render config params set as # sphinx_gallery_config [= value]
 }
 
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 html_theme = "pydata_sphinx_theme"
@@ -185,6 +188,7 @@
     "mailto": None,
     "movement-github": "https://github.com/neuroinformatics-unit/movement/{{path}}",
     "movement-zulip": "https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement",
+    "movement-community-calls": "https://neuroinformatics.zulipchat.com/#narrow/channel/406001-Movement/topic/Community.20Calls",
     "conda": "https://docs.conda.io/en/latest/",
     "dlc": "https://www.mackenziemathislab.org/deeplabcut/",
     "gin": "https://gin.g-node.org/{{path}}#{{fragment}}",
@@ -199,9 +203,30 @@
     "xarray": "https://docs.xarray.dev/en/stable/{{path}}#{{fragment}}",
     "lp": "https://lightning-pose.readthedocs.io/en/stable/{{path}}#{{fragment}}",
     "via": "https://www.robots.ox.ac.uk/~vgg/software/via/{{path}}#{{fragment}}",
+    "anipose": "https://anipose.readthedocs.io/en/latest/",
 }
 
 intersphinx_mapping = {
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+}
+
+
+# What to show on the 404 page
+notfound_context = {
+    "title": "Page Not Found",
+    "body": """
+<h1>Page Not Found</h1>
+
+<p>Sorry, we couldn't find that page.</p>
+
+<p>We occasionally restructure the movement website, and some links may have broken.</p> 
+
+<p>Try using the search box or go to the homepage.</p>
+""",
 }
+
+# needed for GH pages (vs readthedocs),
+# because we have no '/<language>/<version>/' in the URL
+notfound_urls_prefix = None

docs/source/index.md

@@ -6,11 +6,11 @@ A Python toolbox for analysing animal body movements across space and time.
 ::::{grid} 1 2 2 3
 :gutter: 3
 
-:::{grid-item-card} {fas}`rocket;sd-text-primary` Getting Started
-:link: getting_started/index
+:::{grid-item-card} {fas}`book;sd-text-primary` User guide
+:link: user_guide/index
 :link-type: doc
 
-Installation, first steps and key concepts.
+Installation, supported formats and key concepts.
 :::
 
 :::{grid-item-card} {fas}`chalkboard-user;sd-text-primary` Examples
@@ -60,8 +60,9 @@ Find out more on our [mission and scope](target-mission) statement and our [road
 :maxdepth: 2
 :hidden:
 
-getting_started/index
+user_guide/index
 examples/index
 community/index
 api_index
+blog/index
 ```

docs/source/snippets/get-in-touch.md

@@ -1,3 +1,5 @@
 :::{admonition} Get in touch
-You are welcome to chat with the team on [Zulip](movement-zulip:). You can also [open an issue](movement-github:issues) to report a bug or request a new feature.
+- [Chat with the team on Zulip](movement-zulip:).
+- [Open an issue](https://github.com/neuroinformatics-unit/movement/issues) to report a bug or request a new feature.
+- [Follow this Zulip topic](movement-community-calls:) to receive updates about upcoming Community Calls.
 :::

docs/source/user_guide/index.md

@@ -0,0 +1,45 @@
+# User guide
+
+Start by [installing the package](installation.md) and
+[loading your own tracking data](input_output.md), or playing with some
+[sample data](target-sample-data) provided with the package.
+
+Before you dive deeper, we highly recommend reading about the structure
+and usage of [movement datasets](movement_dataset.md), which are a central
+concept in the package.
+
+::::{grid} 1 2 2 3
+:gutter: 3
+
+:::{grid-item-card} {fas}`wrench;sd-text-primary` Installation
+:link: installation
+:link-type: doc
+
+Install the package with `conda` or `pip`.
+:::
+
+:::{grid-item-card} {fas}`download;sd-text-primary` Input/Output
+:link: input_output
+:link-type: doc
+
+Load and save tracking data.
+:::
+
+:::{grid-item-card} {fas}`table;sd-text-primary` The movement datasets
+:link: movement_dataset
+:link-type: doc
+
+Learn about our data structures.
+:::
+
+::::
+
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+installation
+input_output
+movement_dataset
+```