Skip to content

Commit

Permalink
Merge pull request #710 from int-brain-lab/iblrigv8dev
Browse files Browse the repository at this point in the history
* feature: post hardware information to alyx
* generate PDF documentation
* increase verbosity of error handling in base task
* remove dead code
  • Loading branch information
bimac authored Aug 26, 2024
2 parents db04546 + b07f1f4 commit ad41db2
Show file tree
Hide file tree
Showing 21 changed files with 567 additions and 341 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/documentation.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ on:
paths:
- '.github/workflows/documentation.yaml'
- 'docs/**'
- 'iblrig/__init__.py'
- 'CHANGELOG.md'
- 'README.md'
- 'pyproject.toml'
Expand All @@ -20,13 +21,12 @@ jobs:
- name: Set up PDM
uses: pdm-project/setup-pdm@v4
with:
python-version: ${{ matrix.python-version }}
cache: true
python-version-file: pyproject.toml
- name: Install requirements
run: pdm sync -dG doc
- name: Sphinx build
run: |
pdm run sphinx-build docs/source docs/build/html
run: pdm run sphinx-build docs/source docs/build/html
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
Expand Down
44 changes: 44 additions & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Release

on:
push:
branches:
- iblrigv8
tags:
- '[0-9]+.[0-9]+.[0-9]+'

jobs:
pdf:
name: Build PDF
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up PDM
uses: pdm-project/setup-pdm@v4
with:
cache: true
python-version-file: pyproject.toml
- name: Install requirements
run: pdm sync -dG doc
- name: Build PDF
run: pdm run make -C docs/ simplepdf
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: documentation
path: docs/build/simplepdf/*.pdf
retention-days: 1

release:
name: Publish GitHub Release
needs: pdf
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: documentation
- uses: softprops/action-gh-release@v2
with:
files: documentation/*.pdf
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
Changelog
=========

8.23.1
------
* feature: post hardware information to alyx
* generate PDF documentation
* increase verbosity of error handling in base task
* remove dead code

8.23.0
------
* hardware validation: check for unexpected events on Bpod's digital input ports
Expand Down
18 changes: 17 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
from datetime import date

from iblrig import __version__
from iblrig.constants import BASE_PATH

project = 'iblrig'
copyright = f'2018 – {date.today().year} International Brain Laboratory'
author = 'International Brain Laboratory'
version = '.'.join(__version__.split('.')[:3])
release = '.'.join(__version__.split('.')[:3])

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel']
extensions = ['sphinx_lesson', 'sphinx.ext.autosectionlabel', 'sphinx_simplepdf']
autosectionlabel_prefix_document = True
source_suffix = ['.rst', '.md']

Expand All @@ -23,3 +25,17 @@

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']


simplepdf_vars = {
'primary': '#004f8c',
'secondary': '#004f8c',
'cover': 'white',
'cover-bg': 'linear-gradient(180deg, #004f8c 0%, #00a1d9 50%, #cc3399 100%)',
}
simplepdf_file_name = f'iblrig_{__version__}_reference.pdf'
simplepdf_weasyprint_flags = ['-j70', '-D150', '--hinting']
html_context = {
'docs_scope': 'external',
'cover_meta_data': 'International Brain Laboratory',
}
26 changes: 15 additions & 11 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. include:: ../../README.md
:parser: myst_parser.sphinx_
.. if-builder:: html

.. include:: ../../README.md
:parser: myst_parser.sphinx_

.. toctree::
:caption: Contents:
:maxdepth: 3
:hidden:

installation
Expand All @@ -12,14 +14,16 @@
reference_developer_guide
faq

.. toctree::
:hidden:
.. if-builder:: html

changelog
.. toctree::
:hidden:

.. toctree::
:caption: Links
:hidden:
changelog

.. toctree::
:caption: Links
:hidden:

IBLRIG on GitHub <https://github.com/int-brain-lab/iblrig>
Appendix 3: IBL protocol for setting up the behavioral training rig <https://doi.org/10.6084/m9.figshare.11634732>
IBLRIG on GitHub <https://github.com/int-brain-lab/iblrig>
Appendix 3: IBL protocol for setting up the behavioral training rig <https://doi.org/10.6084/m9.figshare.11634732>
6 changes: 3 additions & 3 deletions docs/source/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ Now, run the following command at the prompt of Windows PowerShell:
and usability.


Installing MS Visual C++ Redistributable
----------------------------------------
Installing Visual C++ Redistributable
-------------------------------------

With the Administrator PowerShell still open, run the following commands:

Expand All @@ -67,7 +67,7 @@ With the Administrator PowerShell still open, run the following commands:
.. admonition:: Background
:class: seealso

These commands will create a temporary directory, download and silently install the Visual C++ Redistributable package for
These commands will create a temporary directory, download and install the Visual C++ Redistributable package for
64-bit Windows systems. The installer is retrieved from a Microsoft server and executed with parameters to ensure a seamless
and unobtrusive installation process.

Expand Down
58 changes: 33 additions & 25 deletions docs/source/reference_developer_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Developer Guide
Versioning Scheme
-----------------

IBLRIG v8 uses `Semantic Versioning 2.0.0 <https://semver.org/spec/v2.0.0.html>`_.
IBLRIG v8 uses `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
Its version string (currently "|version|") is a combination of three fields, separated by dots:

.. centered:: ``MAJOR`` . ``MINOR`` . ``PATCH``
Expand All @@ -32,18 +32,21 @@ Here,
* ``post3`` indicates the third unversioned commit after the latest versioned release, and
* ``dirty`` indicates the presence of uncommited changes in your local repository of IBLRIG.

Both of these fields are inferred by means of git describe and do not require manual interaction from the developer.
Both of these fields are automatically inferred (by means of ``git describe``) and do not require manual interaction from the
developer.


PDM
---
Package Management and Development Workflows with PDM
-----------------------------------------------------

We use `PDM <https://pdm-project.org/en/latest/>`_ to manage dependencies of IBLRIG.
See `PDM's documentation <https://pdm-project.org/en/latest/#installation>` for help with installing PDM.
PDM can also be used to run various commands with relevance to the development process without having to activate a virtual
environment first.
Please refer to `PDM's documentation <https://pdm-project.org/en/latest/#installation>`_ for help with installing PDM.


Installing Developer Dependencies
---------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To install additional dependencies needed for working on IBLRIG's code-base, run:

Expand All @@ -52,45 +55,39 @@ To install additional dependencies needed for working on IBLRIG's code-base, run
pdm sync -d
Running Unit Tests Locally
--------------------------
Running Unit Tests
^^^^^^^^^^^^^^^^^^

To run unit tests locally, run:

.. code-block:: console
pdm run pytest
This will also generate a coverage report which can be found in the ``htmlcov`` directory.
This will also generate a HTML based coverage report which can be found in the ``htmlcov`` directory.


Linting & Formatting
--------------------

To lint your code, run the:

.. code-block:: console
^^^^^^^^^^^^^^^^^^^^

pdm run ruff check
We use `Ruff <https://docs.astral.sh/ruff>`_ for linting and formatting our code-base in close accordance with `the Black code
style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.

Adding the commandline flag ``--fix`` will automatically fix issues that are deemed safe to handle:
To lint your code, run:

.. code-block:: console
pdm run ruff check --fix
To *check* if your code conforms to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:

.. code-block:: console
pdm run ruff check
pdm run ruff format --check
Appending the flag ``--fix`` to the above command will automatically fix issues that are deemed safe to handle.

To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_, run:
To reformat your code according to the `Black code style <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_ run:

.. code-block:: console
pdm run ruff format
Appending the flag ``--check`` to the above command will check your code for formatting issues without applying any changes.
Refer to `Ruff Formater's documentation <https://docs.astral.sh/ruff/formatter/>`_ for further details.


Expand All @@ -115,18 +112,29 @@ Release Checklist
Building the documentation
--------------------------

To build the documentation, run:

.. code-block:: console
pdm run sphinx-autobuild ./docs/source ./docs/build
You can also export the documentation to a PDF file:

.. code-block:: console
pdm run make -C docs/ simplepdf
Find the exported PDF file in ``docs/build/simplepdf``.


Contribute to the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To write the documentation:

* Write the documentation in the ``iblrig/docs/source`` folder
* If you are writing in a new file, add it to the ``index.rst`` so it appears in the table of content
* Push all your changes to the ``iblrigv8dev`` branch ; if this branch does not exist, create it first
* Push all your changes to the ``iblrigv8dev`` branch; if this branch does not exist, create it first

To release the documentation onto the `website <https://int-brain-lab.github.io/iblrig>`_:

Expand Down
2 changes: 1 addition & 1 deletion iblrig/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# 5) git tag the release in accordance to the version number below (after merge!)
# >>> git tag 8.15.6
# >>> git push origin --tags
__version__ = '8.23.0'
__version__ = '8.23.1'


from iblrig.version_management import get_detailed_version_string
Expand Down
41 changes: 26 additions & 15 deletions iblrig/base_choice_world.py
Original file line number Diff line number Diff line change
Expand Up @@ -676,21 +676,32 @@ def trial_completed(self, bpod_data):
# get the trial outcome
state_names = ['correct', 'error', 'no_go', 'omit_correct', 'omit_error', 'omit_no_go']
raw_outcome = {sn: ~np.isnan(bpod_data['States timestamps'].get(sn, [[np.NaN]])[0][0]) for sn in state_names}
outcome = next(k for k in raw_outcome if raw_outcome[k])
# Update response buffer -1 for left, 0 for nogo, and 1 for rightward
position = self.trials_table.at[self.trial_num, 'position']
if 'correct' in outcome:
self.trials_table.at[self.trial_num, 'trial_correct'] = True
self.session_info.NTRIALS_CORRECT += 1
self.trials_table.at[self.trial_num, 'response_side'] = -np.sign(position)
elif 'error' in outcome:
self.trials_table.at[self.trial_num, 'response_side'] = np.sign(position)
elif 'no_go' in outcome:
self.trials_table.at[self.trial_num, 'response_side'] = 0
super().trial_completed(bpod_data)
# here we throw potential errors after having written the trial to disk
assert np.sum(list(raw_outcome.values())) == 1
assert position != 0, 'the position value should be either 35 or -35'
try:
outcome = next(k for k in raw_outcome if raw_outcome[k])
# Update response buffer -1 for left, 0 for nogo, and 1 for rightward
position = self.trials_table.at[self.trial_num, 'position']
if 'correct' in outcome:
self.trials_table.at[self.trial_num, 'trial_correct'] = True
self.session_info.NTRIALS_CORRECT += 1
self.trials_table.at[self.trial_num, 'response_side'] = -np.sign(position)
elif 'error' in outcome:
self.trials_table.at[self.trial_num, 'response_side'] = np.sign(position)
elif 'no_go' in outcome:
self.trials_table.at[self.trial_num, 'response_side'] = 0
super().trial_completed(bpod_data)
# here we throw potential errors after having written the trial to disk
assert np.sum(list(raw_outcome.values())) == 1
assert position != 0, 'the position value should be either 35 or -35'
except StopIteration as e:
log.error(f'No outcome detected for trial {self.trial_num}.')
log.error(f'raw_outcome: {raw_outcome}')
log.error('State names: ' + ', '.join(bpod_data['States timestamps'].keys()))
raise e
except AssertionError as e:
log.error(f'Assertion Error in trial {self.trial_num}.')
log.error(f'raw_outcome: {raw_outcome}')
log.error('State names: ' + ', '.join(bpod_data['States timestamps'].keys()))
raise e


class BiasedChoiceWorldSession(ActiveChoiceWorldSession):
Expand Down
9 changes: 7 additions & 2 deletions iblrig/gui/wizard.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
from iblrig.path_helper import load_pydantic_yaml
from iblrig.pydantic_definitions import HardwareSettings, RigSettings
from iblrig.raw_data_loaders import load_task_jsonable
from iblrig.tools import alyx_reachable, internet_available
from iblrig.tools import alyx_reachable, get_lab_location_dict, internet_available
from iblrig.valve import Valve
from iblrig.version_management import check_for_updates, get_changelog
from iblutil.util import Bunch, setup_logger
Expand Down Expand Up @@ -229,7 +229,12 @@ def login(

# validate connection and some parameters now that we're connected
try:
self.alyx.rest('locations', 'read', id=self.hardware_settings.RIG_NAME)
self.alyx.rest(
'locations',
'partial_update',
id=self.hardware_settings.RIG_NAME,
data={'json': get_lab_location_dict(self.hardware_settings, self.iblrig_settings)},
)
except HTTPError as ex:
if ex.response.status_code not in (404, 400): # file not found; auth error
# Likely Alyx is down or server-side issue
Expand Down
Loading

0 comments on commit ad41db2

Please sign in to comment.