Merge pull request #822 from Remi-Gau/boilerplate_cli

Remi-Gau · web-flow · commit ce55f5d5fe11 · 2022-11-19T23:25:55.000+01:00
[ENH] add boilerplate to CLI
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,4 @@
-*_report.md
 
-src/batches/cfg
 
 # General
 .DS_Store
@@ -11,24 +9,27 @@ src/batches/cfg
 *.html
 *.ps
 
-.vscode/settings.json
 
 tmp
 
+# logs and options
+error_logs
+*_report.md
+src/batches/cfg
+options_task*[0-9][0-9].json
+
 # created by tests
 CHANGES
 README
 
 # Project specific
-options_task-*date*.json
 onsets*_events.mat
 
 ## virtual env
 env
 venv
 
 ## from running tests in root dir
-*/cfg/*
 */group/*
 models/*
 
diff --git a/bidspm.m b/bidspm.m
@@ -304,13 +304,20 @@ function preprocess(args)
 
   try
 
-    reportBIDS(opt);
+    saveOptions(opt);
+
+    bidsReport(opt);
     bidsCopyInputFolder(opt);
     if opt.dummy_scans > 0
       bidsRemoveDummies(opt, ...
                         'dummyScans', opt.dummy_scans, ...
                         'force', false);
     end
+
+    boilerplate(opt, ...
+                'outputPath', fullfile(opt.dir.output, 'reports'), ...
+                'pipelineType', 'preproc', ...
+                'verbosity', opt.verbosity);
     if opt.useFieldmaps && ~opt.anatOnly
       bidsCreateVDM(opt);
     end
@@ -337,6 +344,7 @@ function default_model(args)
   opt = checkOptions(opt);
 
   try
+    saveOptions(opt);
     createDefaultStatsModel(opt.dir.raw, opt, lower(args.Results.ignore));
   catch ME
     bugReport(opt, ME);
@@ -368,13 +376,19 @@ function stats(args)
 
   try
 
+    saveOptions(opt);
+
+    boilerplate(opt, ...
+                'outputPath', fullfile(opt.dir.output, 'reports'), ...
+                'pipelineType', 'stats', ...
+                'verbosity', opt.verbosity);
+
     if opt.glm.roibased.do
 
       bidsFFX('specify', opt);
       if ~opt.model.designOnly
         bidsRoiBasedGLM(opt);
       end
-
     else
 
       if estimate
diff --git a/demos/.gitignore b/demos/.gitignore
@@ -2,4 +2,4 @@
 */outputs/
 */inputs/
 */*.nii
-*/cfg
+*.png
diff --git a/demos/MoAE/moae_01_bids_app.ipynb b/demos/MoAE/moae_01_bids_app.ipynb
@@ -5,14 +5,8 @@
    "id": "13de9b92",
    "metadata": {},
    "source": [
-    "# MoAE demo"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "074b10dd",
-   "metadata": {},
-   "source": [
+    "# MoAE demo\n",
+    "\n",
     "This script shows how to use the bidspm BIDS app\n",
     "\n",
     "- **Download**\n",
diff --git a/demos/MoAE/moae_01_bids_app.m b/demos/MoAE/moae_01_bids_app.m
@@ -1,5 +1,5 @@
 % # MoAE demo
-
+%
 % This script shows how to use the bidspm BIDS app
 %
 % - **Download**
diff --git a/demos/renaming/spm_2_bids_filenames.ipynb b/demos/renaming/spm_2_bids_filenames.ipynb
@@ -1,13 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "27817b7d",
-   "metadata": {},
-   "source": [
-    "(C) Copyright 2022 Remi Gau"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "748352c4",
@@ -45,12 +37,17 @@
     "\n",
     "- **prefixes are not a thing in official BIDS names**\n",
     "\n",
-    "BIDS has a number of [officially recognised entities](https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html) \n",
+    "BIDS has a number of officially recognised entities \n",
     "(`sub`, `ses`, `task`...) that must come in a specific order for each data type.\n",
     "\n",
+    "https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html\n",
+    "\n",
     "BIDS derivatives adds a few more entities (`desc`, `space`, `res`...)\n",
     "and suffixes (`pseg`, `dseg`, `mask`...)\n",
-    "that can be used to name and describe preprocessed data."
+    "that can be used to name and describe preprocessed data.\n",
+    "\n",
+    "\n",
+    "(C) Copyright 2022 Remi Gau"
    ]
   },
   {
diff --git a/demos/renaming/spm_2_bids_filenames.m b/demos/renaming/spm_2_bids_filenames.m
@@ -1,5 +1,3 @@
-% (C) Copyright 2022 Remi Gau
-
 % # BIDS filenames
 %
 % Ideally we would like to have the same pipeline for statistical analysis
@@ -32,12 +30,17 @@
 %
 % - **prefixes are not a thing in official BIDS names**
 %
-% BIDS has a number of (https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html)
+% BIDS has a number of officially recognised entities
 % (`sub`, `ses`, `task`...) that must come in a specific order for each data type.
 %
+% https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html
+%
 % BIDS derivatives adds a few more entities (`desc`, `space`, `res`...)
 % and suffixes (`pseg`, `dseg`, `mask`...)
 % that can be used to name and describe preprocessed data.
+%
+%
+% (C) Copyright 2022 Remi Gau
 
 % The toolbox BIDS Matlab has some function to help you create bids valid names.
 
@@ -210,8 +213,6 @@
 
 demo_dir = fullfile(pwd, '..', 'MoAE');
 
-opt.taskName = 'auditory';
-
 opt.dir.derivatives = fullfile(demo_dir, 'outputs', 'derivatives');
 opt.dir.preproc = fullfile(opt.dir.derivatives, 'bidspm-preproc');
 
diff --git a/docs/print_boilerplate.m b/docs/print_boilerplate.m
@@ -31,7 +31,7 @@
 opt = checkOptions(opt);
 
 % dataset descriptor
-reportBIDS(opt);
+bidsReport(opt);
 
 % preprocessing
 boilerplate(opt, 'outputPath', fullfile(WK, 'source', 'examples'), ...
diff --git a/docs/source/dev_doc.rst b/docs/source/dev_doc.rst
@@ -80,6 +80,8 @@ workflows
 .. autofunction:: src.workflows.bidsRsHrf
 .. _bidsChangeSuffix:
 .. autofunction:: src.workflows.bidsChangeSuffix
+.. _bidsReport:
+.. autofunction:: src.workflows.bidsReport
 .. _setUpWorkflow:
 .. autofunction:: src.workflows.setUpWorkflow
 .. _cleanUpWorkflow:
@@ -234,8 +236,6 @@ reports
 .. autofunction:: src.reports.copyFigures
 .. _boilerplate:
 .. autofunction:: src.reports.boilerplate
-.. _reportBIDS:
-.. autofunction:: src.reports.reportBIDS
 
 
 .. _infra:
@@ -244,6 +244,8 @@ infra
 =====
 .. _checkToolbox:
 .. autofunction:: src.infra.checkToolbox
+.. _returnBsmDocURL:
+.. autofunction:: src.infra.returnBsmDocURL
 .. _getRepoInfo:
 .. autofunction:: src.infra.getRepoInfo
 .. _elapsedTime:
@@ -266,6 +268,8 @@ infra
 .. autofunction:: src.infra.getVersion
 .. _isOctave:
 .. autofunction:: src.infra.isOctave
+.. _returnRtdURL:
+.. autofunction:: src.infra.returnRtdURL
 
 
 .. _QA:
diff --git a/docs/source/method_section.rst b/docs/source/method_section.rst
@@ -4,7 +4,7 @@ Methods section
 Dataset description
 ===================
 
-Use the :func:`src.reports.reportBIDS` function to description of your dataset
+Use the :func:`src.workflows.bidsReport` function to description of your dataset
 that can be used for your methods section
 
 Preprocessing & GLM
diff --git a/lib/bids-matlab b/lib/bids-matlab
@@ -1 +1 @@
-Subproject commit 0f63858c61b1c637442178957648f75a24d8d68b
+Subproject commit 16c3c988dc18f4f53ffed7d44848b0e9c420eace
diff --git a/src/IO/saveOptions.m b/src/IO/saveOptions.m
@@ -1,6 +1,6 @@
 function saveOptions(opt)
   %
-  % Saves options in a JSON file in a ``cfg`` folder.
+  % Saves options in a JSON file in a ``options`` folder.
   %
   % USAGE::
   %
@@ -13,8 +13,8 @@ function saveOptions(opt)
 
   % (C) Copyright 2020 bidspm developers
 
-  optionDir = fullfile(pwd, 'cfg');
-  [~, ~, ~] = mkdir(optionDir);
+  optionDir = fullfile(pwd, 'options');
+  spm_mkdir(optionDir);
 
   taskString = '';
   if isfield(opt, 'taskName')
@@ -23,8 +23,7 @@ function saveOptions(opt)
 
   filename = fullfile(optionDir, ['options', taskString, '_', timeStamp(), '.json']);
 
-  jsonFormat.indent = '    ';
-  spm_jsonwrite(filename, opt, jsonFormat);
+  bids.util.jsonwrite(filename, opt);
 
   printToScreen(sprintf('Options saved in: %s\n\n', ...
                         pathToPrint(filename)), opt);
diff --git a/src/messages/bugReport.m b/src/messages/bugReport.m
@@ -23,7 +23,10 @@ function bugReport(opt, ME)
     json.ME = ME;
   end
 
-  logFile = spm_file(sprintf('error_%s.log', timeStamp()), 'cpath');
+  output_dir = fullfile(pwd, 'error_logs');
+  spm_mkdir(output_dir);
+
+  logFile = spm_file(fullfile(output_dir, sprintf('error_%s.log', timeStamp())), 'cpath');
   bids.util.jsonwrite(logFile, json);
   printToScreen(sprintf(['\nERROR LOG SAVED:\n\t%s\n', ...
                          'Use it when opening an issue <a href="%s">%s</a>.\n'], ...
diff --git a/src/reports/bidspm.bib b/src/reports/bidspm.bib
@@ -1,9 +1,9 @@
 @software{bidspm,
-  author    = {Gau, Rémi and Barilari, Marco and Battal, Ceren and Rezk, Mohamed and Collignon, Olivier and Gurtubay, Ane and Falagiarda, Federica and MacLean, Michèle and Cerpelloni, Filippo and Shahzad, Iqra and Nunes, Márcia},
+  author    = {Gau, Rémi and Barilari, Marco and Battal, Ceren and Rezk, Mohamed and Collignon, Olivier and Gurtubay, Ane and Falagiarda, Federica and MacLean, Michèle and Cerpelloni, Filippo and Shahzad, Iqra and Nunes, Márcia and Caron-Guyon, Jeanne and Chouinard-Leclaire, Christine and Yang, Ying},
   license   = {GPL-3.0},
   title     = {bidspm},
   url       = {https://github.com/cpp-lln-lab/bidspm},
-  version   = {1.1.5dev},
+  version   = {2.2.0}
   doi       = {10.5281/zenodo.3554331},
   publisher = {Zenodo},
   journal   = {Software}
diff --git a/src/reports/boilerplate.m b/src/reports/boilerplate.m
@@ -69,6 +69,8 @@
     opt.OS.name = 'unix';
   end
 
+  copyBibFile(outputPath);
+
   if strcmp(pipelineType, 'spatial_preproc')
 
     opt.normalization = false;
@@ -248,25 +250,36 @@
   end
 end
 
-function outputFile = printToFile(output, outputPath, pipelineType)
+function copyBibFile(outputPath)
+  bibFile = fullfile(returnRootDir(), 'src', 'reports', 'bidspm.bib');
+  copyfile(bibFile, outputPath);
+end
+
+function outputFile = printToFile(output, outputPath, pipelineType, modelName)
 
   outputFile = '';
 
+  if nargin < 4
+    modelName = '';
+  end
+
   if ~isempty(outputPath)
 
     spm_mkdir(outputPath);
 
     if strcmp(pipelineType, 'preproc')
-      outputFile = 'preprocess.md';
+      outputFile = 'preprocess_CITATION.md';
     elseif strcmp(pipelineType, 'stats')
-      outputFile = 'stats.md';
+      outputFile = ['stats_model-' modelName '_CITATION.md'];
     end
 
     outputFile = fullfile(outputPath, outputFile);
 
     fid = fopen(outputFile, 'wt');
     if fid == -1
-      error('Unable to open file "%s" for writing.', outputFile);
+      error(['Unable to open file "%s" for writing.', ...
+             '\nIf you are using a datalad dataset, make sure the file is unlocked.'], ...
+            bids.internal.file_utils(outputFile, 'cpath'));
     end
     fprintf(fid, '%s', output);
     fclose(fid);
diff --git a/src/reports/boilerplate_stats.mustache b/src/reports/boilerplate_stats.mustache
@@ -8,7 +8,7 @@ The input data were the preprocessed BOLD images in{{space}}space for the task "
 At the subject level, we performed a mass univariate analysis with a linear
 regression at each voxel of the brain, using generalized least squares with a
 global {{SerialCorrelationCorrection}} model to account for temporal auto-correlation
-{{#FAST}}(Corbin et al, 2018){{/FAST}}
+{{#FAST}}[@Corbin2018]{{/FAST}}
 and a drift fit with discrete cosine transform basis ({{HighPassFilterCutoffSecs}}seconds cut-off).
 
 Image intensity scaling was done run-wide before statistical modeling such that
diff --git a/src/reports/partials/computing_environment.mustache b/src/reports/partials/computing_environment.mustache
@@ -1,6 +1,6 @@
-{{generatedBy.name}} ({{generatedBy.Version}}; {{generatedBy.CodeURL}}; DOI: {{generatedBy.DOI}})
+{{generatedBy.name}} ({{generatedBy.Version}}; {{generatedBy.CodeURL}}; DOI: {{generatedBy.DOI}} - [@bidspm])
 using statistical parametric mapping
 ({{OS.spmVersion}}; Wellcome Center for Neuroimaging, London, UK;
 https://www.fil.ion.ucl.ac.uk/spm; RRID:SCR_007037)
 using {{#OS}}{{platform.name}} {{platform.version}}
-on a {{name}} computer ({{version}}){{/OS}}.
+on a {{name}} computer ({{version}}){{/OS}}
diff --git a/src/workflows/bidsReport.m b/src/workflows/bidsReport.m
@@ -1,4 +1,4 @@
-function reportBIDS(opt)
+function bidsReport(opt)
   %
   % Prints out a human readable description of a BIDS data set for every subject
   % in ``opt.subjects``.
@@ -10,7 +10,7 @@ function reportBIDS(opt)
   % USAGE::
   %
   %   opt.dir.input = "path_to_dataset"
-  %   reportBIDS(opt)
+  %   bidsReport(opt)
   %
   % :type opt:  structure
   % :param opt: Options chosen for the analysis.
diff --git a/tests/tests_infra/test_bugReport.m b/tests/tests_infra/test_bugReport.m
@@ -19,7 +19,7 @@ function test_bugReport_basic()
 
   bugReport(opt);
 
-  delete *.log;
+  cleanUp('error_logs');
 
 end
 
@@ -36,4 +36,6 @@ function test_bugReport_error()
     bugReport(opt, ME);
   end
 
+  cleanUp('error_logs');
+
 end
diff --git a/tests/tests_reports/test_boilerplate.m b/tests/tests_reports/test_boilerplate.m
diff --git a/tests/tests_reports/test_reportBIDS.m b/tests/tests_reports/test_reportBIDS.m
diff --git a/tests/tests_unit/IO/test_saveOptions.m b/tests/tests_unit/IO/test_saveOptions.m
diff --git a/tests/tests_workflows/test_bidsReport.m b/tests/tests_workflows/test_bidsReport.m
diff --git a/tools/bump_version.sh b/tools/bump_version.sh

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`% # MoAE demo`
`2`		`-`
	`2`	`+%`
`3`	`3`	`% This script shows how to use the bidspm BIDS app`
`4`	`4`	`%`
`5`	`5`	`% - Download`