Merge pull request #31 from CBICA/documentation

New read-the-docs documentation

README.rst

@@ -0,0 +1,106 @@
+spare scores
+============
+
+.. image:: https://codecov.io/gh/CBICA/spare_score/graph/badge.svg?token=7yk7pkydHE
+   :target: https://codecov.io/gh/CBICA/spare_score
+
+.. image:: https://github.com/CBICA/spare_score/actions/workflows/macos-tests-3.12.yml/badge.svg
+   :alt: macos tests
+
+.. image:: https://github.com/CBICA/spare_score/actions/workflows/ubuntu-tests-3.12.yml/badge.svg
+   :alt: ubuntu tests
+
+
+Overview
+--------
+
+"SPARE" is short for "Spatial Pattern of Abnormalities for Recognition of ..." If you have brain images of a case population, such as the Alzheimer's disease (AD), the SPARE model will try to find characteristic brain patterns of AD with respect to a control population, such as cognitively normal. This would be an example of a classification-based SPARE model (currently powered by support vector machine or SVM). This model (that we named SPARE-AD) then computes SPARE-AD scores on an individual-basis that indicates how much the individual carries the learned brain patterns of AD.
+
+Alternatively, you may want to find the spatial pattern related to brain aging (BA). In this case, you would provide sample images and indicate that chronological age is what you expect the model to learn patterns for. This would be an example of a regression-based SPARE model (also powered by SVM). This model (that we named SPARE-BA) then computes SPARE-BA scores on an individual-basis that predicts your brain age.
+\
+\
+\
+For detailed documentation, please see here: **[spare_scores](https://cbica.github.io/spare_score/)**
+
+Installation
+____________
+
+You can install the spare_score package for python 3.8 up to python 3.12
+Please open an issue if you find any bugs for the newer versions of spare_score
+
+*********
+Using pip
+*********
+
+You can install our latest stable PyPI wheel: ::
+
+  $ pip install spare_scores
+
+**************************
+Manually build spare_score
+**************************
+
+You can install spare_scores from source: ::
+
+    # for python 3.12
+    $ git clone https://github.com/CBICA/spare_score.git
+      cd spare_score
+      python -m pip install .
+
+    # for python 3.8 and similar
+    # python setup.py bdist_wheel
+      cd dist && pip install <wheel file>
+
+
+Usage
+_____
+
+Example of training a model (given the example data): ::
+
+  $ spare_score --action train \
+      --input spare_scores/data/example_data.csv \
+      --predictors H_MUSE_Volume_11 H_MUSE_Volume_23 H_MUSE_Volume_30 \
+      --ignore_vars Sex \
+      --to_predict Age \
+      --kernel linear \
+      --verbose 2 \
+      --output my_model.pkl.gz
+
+Example of testing (applying) a model (given the example data): ::
+
+  $ spare_score -a test \
+      -i spare_scores/data/example_data.csv  \
+      --model my_model.pkl.gz \
+      -o test_spare_data.csv \
+      -v 0 \
+      --logs test_logs.txt
+
+.. note::
+
+  You can always see all of the CLI documentation with ``spare_score -h``
+
+References
+__________
+
+- SPARE-AD
+
+  Davatzikos, C., Xu, F., An, Y., Fan, Y. & Resnick, S. M. Longitudinal progression of Alzheimer's-like patterns of atrophy in normal older adults: the SPARE-AD index. Brain 132, 2026-2035, [doi:10.1093/brain/awp091](https://doi.org/10.1093/brain/awp091) (2009).
+
+- SPARE-BA
+
+  Habes, M. et al. Advanced brain aging: relationship with epidemiologic and genetic risk factors, and overlap with Alzheimer disease atrophy patterns. Transl Psychiatry 6, e775, [doi:10.1038/tp.2016.39](https://doi.org/10.1038/tp.2016.39) (2016).
+
+- diSPARE-AD
+
+  Hwang, G. et al. Disentangling Alzheimer's disease neurodegeneration from typical brain ageing using machine learning. Brain Commun 4, fcac117, [doi:10.1093/braincomms/fcac117](https://doi.org/10.1093/braincomms/fcac117) (2022).
+
+Disclaimer
+__________
+
+- The software has been designed for research purposes only and has neither been reviewed nor approved for clinical use by the Food and Drug Administration (FDA) or by any other federal/state agency.
+- By using spare_scores, the user agrees to the following license: [CBICA Software License](https://www.med.upenn.edu/cbica/software-agreement-non-commercial.html)
+
+Contact
+_______
+
+For more information and support, please post on the [Discussions](https://github.com/CBICA/spare_score/discussions) section or contact [CBICA Software](mailto:[email protected])

docs/spare_scores.rst → docs/api.rst

@@ -1,5 +1,5 @@
-spare\_scores package
-=====================
+spare\_scores source code
+=========================
 
 Submodules
 ----------

docs/conf.py

@@ -9,9 +9,9 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../spare_scores/"))
+sys.path.insert(0, os.path.abspath("../"))
 
-project = "spare-scores"
+project = "spare scores"
 copyright = "2024, Gyujoon Hwang, George Aidinis"
 author = "Gyujoon Hwang, George Aidinis"
 release = "2024"
@@ -35,7 +35,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 github_username = "CBICA"
-github_repository = "github.com/CBICA/spare_score"
+github_repository = "github.com/CBICA/spare_scores"
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]

docs/contributors.rst

@@ -0,0 +1,76 @@
+############
+Contributing
+############
+
+This document explains how to prepare your environment to contribute to our package.
+Note that we always update our main branch if we want to update the stable release on PyPI, thus, creating
+your own branch is recommended so that you can open a pull request.
+
+*****************
+Third party tools
+*****************
+
+We use pre-commit as our main tool for code formatting and checking. You always have to make sure that pre-commit pass in order to open a pull request.
+You can perform this test just following these steps: ::
+
+    # If you don't have pre-commit installed
+    $ pip install pre-commit && pre-commit install
+
+    # Then run pre-commit
+    pre-commit run --color=always --all-files
+
+We already have all the necessairy hooks at our `configuration <../../../.pre-commit-config.yaml>`_.
+
+For our unit testing, we use pytest. Again, in order to contribute you need to make sure that all of the unit tests pass.
+You can perform this test following these steps: ::
+
+    # If you don't have pytest installed
+    $ pip install pytest pytest-cov
+
+    # Run pytest
+    cd tests/ && pytest
+
+.. note::
+
+    We highly suggest you to install the dev requirements before contributing: ::
+
+       $ pip install -r requirements.txt
+
+************
+Coding style
+************
+
+We follow a specific coding style that, luckily, can be easily checked with pre-commit. First and foremost, you should always add documentation to any new features you add.
+We follow ``sphinx``'s docstring style so that the parser can detect the code comments and display them beautifully at our read-the-docs. Let's assume that you add a new function:
+
+.. code-block:: python
+
+    def foo(param1: int, param2: str, param3: list) -> int:
+        """
+        Brief explanation of what foo does.
+
+        :param param1: Description of param1.
+        :type param1: int
+        :param param2: Description of param2.
+        :type param2: str
+        :param param3: Description of param3.
+        :type param3: list
+        :return: Description of the return value.
+        :rtype: int
+        """
+
+``pre-commit`` will also check if you include libraries that are not needed, any extra spaces you might have, logic errors and much more.
+
+Also, as you see above, you should always add types and return types to every function and class. We only write Python 3 code. If you don't follow all of the above, ``pre-commit`` won't pass, and a maintainer won't review your pull request.
+
+**************
+Good practices
+**************
+
+    - At your pull request, explain your additions, why are they useful or what they fix. There are currently no templates to follow for this, but you can just write a sufficient explanation so that a maintainer can understand your additions/fixes.
+
+    - Write a nice commit message.
+
+    - Make sure to follow the issue template if you want to open an issue.
+
+    - Make sure to always add any third-party libraries that you add at the requirements so that the actions can install them.