[JOSS Review] Installation issues, suggested code reorganization

[0todd0000]

This issue highlights a few different issues related to installation. I am submitting this as one issue because they are all related, and I've suggested one solution below that would solve all of these issues.

Minor issue: Installation instructions

• The current installation instructions are insufficient. Adding the fctSPM root to the path using addpath, for example, is insufficient because the fctSPM function will only execute if the subfolders are also added.

Minor issue: Unneeded directories added to path

• addAbovePath.m adds far too many directories, and mainly unnecessary directories to the path. Below is a full list of the directories that it added to my path. Only few of these directories actually need to be added to the path.

./fctSPM
./fctSPM/.git
./fctSPM/.git/branches
./fctSPM/.git/hooks
./fctSPM/.git/info
./fctSPM/.git/logs
./fctSPM/.git/logs/refs
./fctSPM/.git/logs/refs/heads
./fctSPM/.git/logs/refs/remotes
./fctSPM/.git/logs/refs/remotes/origin
./fctSPM/.git/objects
./fctSPM/.git/objects/info
./fctSPM/.git/objects/pack
./fctSPM/.git/refs
./fctSPM/.git/refs/heads
./fctSPM/.git/refs/remotes
./fctSPM/.git/refs/remotes/origin
./fctSPM/.git/refs/tags
./fctSPM/Article@JOSS
./fctSPM/Examples
./fctSPM/Figures
./fctSPM/mainFunctions
./fctSPM/plotFunctions
./fctSPM/spm1d_Pataky
./fctSPM/spm1d_Pataky/examples
./fctSPM/spm1d_Pataky/examples/nonparam
./fctSPM/spm1d_Pataky/examples/nonparam/0d
./fctSPM/spm1d_Pataky/examples/nonparam/1d
./fctSPM/spm1d_Pataky/examples/normality
./fctSPM/spm1d_Pataky/examples/normality/0d
./fctSPM/spm1d_Pataky/examples/normality/1d
./fctSPM/spm1d_Pataky/examples/stats0d
./fctSPM/spm1d_Pataky/examples/stats1d
./fctSPM/spm1d_Pataky/examples/stats1d_roi
./fctSPM/spm1d_Pataky/examples/stats2d
./fctSPM/spm1d_Pataky/spm8
./fctSPM/utilityFunctions
./fctSPM/utilityFunctions/cbrewer

Major issue: DO NOT ADJUST USER PATHS The current scripts in Examples call the addAbovePath.m function. This is highly problematic for two main reasons:

1. addAbovePath.m is undocumented.
2. Please never alter users' paths without their knowledge and explicit permission.

---

To solve these problems I suggest the following:

• Remove addAbovePath.m from the repository
• Reorganize the code to make it clearer what directories actually need to be added to the directory.

Currently the directory structure is:

./Article@JOSS
./Examples
./Figures
LICENSE
./mainFunctions
./plotFunctions
README
./spm1d_Pataky
./utilityFunctions

I suggest reorganizing as follows:

./Article@JOSS
./Examples
LICENSE
README
./src/    % contains contents of "mainFunctions"
./src/plot    % contains contents of "plotFunctions"
./src/util    % contains contents of "utilFunctions"
./src/spm1d_Pataky

With this organization it will be easy to explain installation, and to solve all other problems mentioned in this issue. Installation could be explained using, for example:

addpath( genpath( "./fctSPM/src" ) )

[tramarobin]

The folder was reorganized as recommended and the addAbovePath was deleted. However, can I still let the a line addpath(genpath("../src")) in the example scripts to add only the source code path or is this prohibited ? I still wrote how to add only the required path in the installation instructions.

[0todd0000]

Please do not alter the path in scripts. Paths are relevant only to installation.

If the package is not installed correctly, then the scripts should not execute. When the package is correctly installed, then the scripts should execute properly.

Please do not mix installation with demo scripts.

[tramarobin]

The line with the installation procedure was deleted from all the examples.

[0todd0000]

Ok, thank you!