Package: osl-dynamics
============
osl-dynamicsSee the read the docs page for a description of this project:https://osl-dynamics.readthedocs.io <https://osl-dynamics.readthedocs.io>_.CitationIf you find this toolbox useful, please cite:**Gohil C., Huang R., Roberts E., van Es M.W.J., Quinn A.J., Vidaurre D., Woolrich M.W. (2023) osl-dynamics: A toolbox for modelling fast dynamic brain activity. eLife 12:RP91949 https://doi.org/10.7554/eLife.91949.2**InstallationCondaWe recommend installing osl-dynamics within a virtual environment. You can do this withAnaconda <https://docs.anaconda.com/free/anaconda/install/index.html>_ (orminiconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>_).LinuxHere, we describe how to install osl-dynamics from source. We recommend using the conda environment files in/envs. For a generic linux machine, osl-dynamics can be installed in editable mode with:.. code-block:: shellgit clone https://github.com/OHBA-analysis/osl-dynamics.git
cd osl-dynamics
conda env create -f envs/linux.yml
conda activate osld
pip install -e .Note, if you have a Mac you may want to use theenvs/mac.ymlenvironment file instead.WindowsIf you are using a Windows computer, we recommend first installing linux (Ubuntu) as a Windows Subsystem by following the instructionshere <https://ubuntu.com/wsl>_. Then following the instructions above in the Ubuntu terminal.Oxford specific computersIf you're installing on the Oxford BMRC server, useenvs/bmrc.yml. If you're installing on the OHBA workstation, useenvs/hbaws.yml. Note, thehbaws.ymlenvironment will automatically install spyder and jupyter notebooks.Within an osl environmentIf you have already installedOSL <https://github.com/OHBA-analysis/osl>_ you can install osl-dynamics in theoslenvironment with:.. code-block:: shellconda activate osl
cd osl-dynamics
pip install tensorflow==2.9.1
pip install tensorflow-probability==0.17
pip install -e .DevelopersDevelopers might want to clone the repo using SSH instead of HTTPS:.. code-block:: shellgit clone git@github.com:OHBA-analysis/osl-dynamics.gitDocumentationThe read the docs page should be automatically updated whenever there's a new commit on themainbranch.The documentation is included as docstrings in the source code. Please write docstrings to any classes or functions you add following thenumpy style <https://numpydoc.readthedocs.io/en/latest/format.html>_. The API reference documentation will only be automatically generated if the docstrings are written correctly. The documentation directory/docalso contains.rstfiles that provide additional info regarding installation, development, the models, etc.To compile the documentation locally you need to install the required packages (sphinx, etc.) in your conda environment:.. code-block:: shellcd osl-dynamics
pip install -r doc/requirements.txtTo compile the documentation locally use:.. code-block:: shellpython setup.py build_sphinxThe local build of the documentation webpage can be found inbuild/sphinx/html/index.html.ReleasesThe process of packaging a python project is described here:https://packaging.python.org/en/latest/tutorials/packaging-projects <https://packaging.python.org/en/latest/tutorials/packaging-projects>_.A couple packages are needed to build and upload a project to PyPI, these can be installed in your conda environment with:.. code-block:: shellpip install build twineThe following steps can be used to release a new version:#. Update the version on line 5 ofsetup.cfgby removingdevfrom the version number.
#. Commit the updated setup.cfg to themainbranch of the GitHub repo.
#. Delete any old distributions that have been built (if there are any):rm -r dist.
#. Build a distribution in the osl-dynamics root directory withpython -m build. This will create a new directory calleddist.
#. Test the build by installing in a test conda environment withcd dist; pip install <build>.whl.
#. Upload the distribution to PyPI withtwine upload dist/*. You will need to enter the username and password that you used to register withhttps://pypi.org <https://pypi.org>_.
#. Tag the commit uploaded to PyPI with the version number using the 'Create a new release' link on the right of the GitHub repo webpage.
#. Change the version toX.Y.devZinsetup.cfgand commit the new dev version tomain.The uploaded distribution will then be available to be installed with:.. code-block:: shellpip install osl-dynamicsEditing Source CodeSeehere <https://github.com/OHBA-analysis/osl-dynamics/blob/main/doc/using_bmrc.rst>_ for useful info regarding how to use the BMRC cluster and how to edit the source code.