Define the "movement dataset" and reorganise the Getting Started section

niksirbi commented 4 months ago

Description

What is this PR

[ ] Bug fix
[x] Addition of a new feature
[ ] Other

Why is this PR needed?

The recently merged PR #174 changed the way we conceptualise and use the xarray.Dataset accessor, aligning it closer with this proposal. This prompted me to extensively document the current structure and usage of this accessor, as was described in the proposal.

What does this PR do?

I renamed the MoveAccessor to MovementDataset, which may be more transparent to users. the module is still named move_accessor.py, but the MovementDataset class can be directly imported as from movement import MovementDataset (the user doesn't need to know about the move_accessor.py module). I significantly shrunk the docsrtring of the MovementDataset class, because we will now have a whole docs section to serve as the authoritative source for how the dataset is structured (see next point).

I vastly expanded the description of dataset structure, which is now a standalone page named "The movement dataset". Within it, I describe the structure and usage of movement datasets, built-in vs movement-specific functionalities etc.

Since the above section was "split away" from the Getting Started guide, I decided to also refactor the rest of the guide into more modular sections. This is not yet fully following #70 but is hopefully a step in the right direction. The Getting Started section now has the following pages/subsections:

installation (self-explanatory, this includes the movement info command for checking the installation
input/output (supported file formats, loading and saving files)
sample data (which was previously "hidden" in a dropdown, this is up-to-date with https://github.com/neuroinformatics-unit/movement/pull/171)
the movement dataset (as described above).

Keep in mind that this is not the endpoint for how the docs will look like. More restructuring is to follow. That said, the updated Getting Started section should serve its purpose for the upcoming Measuring Behavior conference, and I needed to make sure that it reflects recent changes in the accessor and in sample data.

This is how the Getting Started section looks with these changes: Screenshot from 2024-05-13 18-33-41

How to review

The best way is to build the docs locally and inspect the rendered result. You may ignore syntax such as class{xarray.Dataset} (in must markdown) and :py:class:`xarray.Dataset` (in docstrings and rst). They don't have much of an effect right now, but they will pay off once we configure intersphinx.

References

https://github.com/neuroinformatics-unit/movement/issues/162 https://github.com/neuroinformatics-unit/movement/issues/70 https://github.com/neuroinformatics-unit/movement/pull/171 https://github.com/neuroinformatics-unit/movement/pull/174

How has this PR been tested?

Please explain how any new code has been tested, and how you have ensured that no existing functionality has changed.

Is this a breaking change?

No

Does this PR require an update to the documentation?

It's all about documentation.

Checklist:

[x] The code has been tested locally
[ ] Tests have been added to cover all new functionality
[x] The documentation has been updated to reflect any changes
[x] The code has been formatted with pre-commit

codecov[bot] commented 4 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.68%. Comparing base (ae702ad) to head (5fab39e).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #177 +/- ## ======================================= Coverage 99.68% 99.68% ======================================= Files 11 11 Lines 637 638 +1 ======================================= + Hits 635 636 +1 Misses 2 2 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.