Jacopo

.github/workflows/sphinx.yml

@@ -0,0 +1,24 @@
+name: "Sphinx: Render docs"
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

README.rst

@@ -0,0 +1,4 @@
+Welcome to BrainAge's documentation! 
+=======
+
+**BrainAge** (/lu'make/) is a Python program that aims to predict age of patients, processing the features obtained from MRI scan.

code/abspath.py

@@ -7,12 +7,13 @@ def abs_path(local_filename, data_folder):
     and the name of the file inside that folder and assuming that the repository contains a data folder
     and a code folder.
 
-    Arguments:
-    local_filename (str): name of the data file inside the data folder
-    data_folder (str): name of the folder which contains the data, default "data"
-
-    Result:
-    str: the function returns the absolute path of the selected file
+    :param local_filename: name of the data file
+    :type local_filename: str
+    :param data_folder: name of the folder which contains the data
+    :type data_folder: str
+    :return: the function returns the absolute path of the selected file
+    :rtype: str
+
     """
     script_dir = os.path.dirname(os.path.abspath(__file__))     # path of the code
 

code/csvreader.py

@@ -9,19 +9,17 @@ def csv_reader(csv_file, column_name=None, show_flag=False):
     csv_reader allows to read the data from a CSV file and converts them into a NumPy array.
     It can also show the entire dataset as a Pandas dataframe on terminal
     or show a single column of the data table.
-    When importing this code as a module by writing
+    The csv_reader function does not show the dataframe, unless specified by changing show_flag argument.
 
-    from csvreader import csv_reader
-
-    the csv_reader function does not show the dataframe, unless specified by changing show_flag argument. 
-
-    Arguments:
-    -csv_file (str): path to the CSV file
-    -column_name (str): optional, default = None. Name of the column to select
-    -show_flag (bool): optional, default = False. If True, the entire dataframe is shown.
-
-    Return:
-    numpy.ndarray: The function returns a NumPy array
+    :param csvfile: path to the CSV file
+    :type csvfile: str
+    :param column_name: optional (default = None): name of the column to select
+    :type column_name: str
+    :param show_flag: optional (default = False): if True, the entire dataframe is shown.
+    :type show_flag: bool
+    :return: the function returns a multidimensional numpy array if no column_name is passed as argument, otherwise it returns a unidimensional numpy array 
+    :rtype: numpy.ndarray
+
     """
     df = pd.read_csv(csv_file, delimiter=';')
     if column_name is None:

code/gaussian_reg.py

@@ -13,16 +13,19 @@
 
 def gaussian_reg(filename, n_splits, ex_cols=0,  plot_flag=False):
     """
-    gaussian_reg performs a Gaussian regression with k-fold cross-validation on the given dataset.
+    gaussian_reg performs a Gaussian regression with k-fold cross-validation on the given dataset
+    and prints evaluation metrics of the gaussian regression model.
+
+    :param filename: path to the CSV file containing the dataset 
+    :type filename: str
+    :param n_splits: number of folds for cross-validation
+    :type n_splits: int
+    :param ex_cols: optional (default = 0): number of folds for cross-validation
+    :type ex_cols: int
+    :param plot_flag: optional (default = False): Whether to plot the actual vs. predicted values
+    :type plot_flag: bool
+    :return: None
 
-    Arguments:
-    - filename (str): path to the CSV file containing the dataset
-    - n_splits (int):  Number of folds for cross-validation
-    - ex_cols (int): optional, default = 0. Number of columns excluded from dataset
-    - plot_flag (bool): optional, default = False. Whether to plot the actual vs. predicted values
-
-    Returns:
-    - None. Prints evaluation metrics of the gaussian regression model.
     """
     # Loading data...
     #Importing features excluded first three columns: FILE_ID, AGE_AT_SCAN, SEX

code/linear_reg.py

@@ -14,16 +14,19 @@
 def linear_reg(filename, n_splits, ex_cols=0, plot_flag=False):
 
     """
-    linear_reg performs linear regression with k-fold cross-validation on the given dataset.
+    linear_reg performs linear regression with k-fold cross-validation on the
+    given dataset and prints evaluation metrics of the linear regression model.
+
+    :param filename: path to the CSV file containing the dataset 
+    :type filename: str
+    :param n_splits: number of folds for cross-validation
+    :type n_splits: int
+    :param ex_cols: optional (default = 0): number of folds for cross-validation
+    :type ex_cols: int
+    :param plot_flag: optional (default = False): Whether to plot the actual vs. predicted values
+    :type plot_flag: bool
+    :return: None
 
-    Arguments:
-    - filename (str): path to the CSV file containing the dataset 
-    - n_splits (int): number of folds for cross-validation
-    - ex_cols (int): optional, default = 0. Number of columns excluded from dataset
-    - plot_flag (bool): optional, default = False. Whether to plot the actual vs. predicted values
-
-    Returns:
-    - None. Prints evaluation metrics of the linear regression model.
     """
     # Loading data...
     #Importing features excluded first three columns: FILE_ID, AGE_AT_SCAN, SEX

code/neural_net.py

@@ -37,6 +37,7 @@ def create_neural_net(input_shape,
 
     Return: the instance of the Sequential class, i.e. the model object
     """
+
     # Defining the model
     model = Sequential()
     model.add(layers.Input(shape=input_shape))
@@ -93,8 +94,27 @@ def training(features, targets, model, epochs, **kwargs):
     - MSE (mean squared error)
     - R-squared
     Optionally showing:
+
     - Actual vs Predicted brain age scatter plot
     - Training history plot
+
+    :param filename: path to the CSV file containing the dataset 
+    :type filename: str
+    :param epochs: number of epochs during neural network training
+    :type epochs: int
+    :param n_splits: number of folds for cross-validation
+    :type n_splits: int
+    :param ex_cols: optional (default = 0): number of folds for cross-validation
+    :type ex_cols: int
+    :param summary_flag: optional (default = False): print the structure of neural network
+    :type summary_flag: bool
+    :param hist_flag: optional (default = False): plot a graph showing val_loss(labeled as valuation) vs loss(labeled as training) during epochs
+    :type hist_flag: bool
+    :param plot_flag: optional (default = False): show the plot of actual vs predic
+    :type plot_flag: bool
+
+    return: None
+
     """
 
     # Optional kwargs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build/coverage/python.txt

@@ -0,0 +1,3 @@
+Undocumented Python objects
+===========================
+

docs/build/doctest/output.txt

@@ -0,0 +1,9 @@
+Results of doctest builder run on 2024-05-15 11:12:01
+=====================================================
+
+Doctest summary
+===============
+    0 tests
+    0 failures in tests
+    0 failures in setup code
+    0 failures in cleanup code

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 80b7203ed5d4921c95a4078a9871c22a
+tags: 645f666f9bcd5a90fca523b33c5a78b7