Common-Issues.md

@@ -91,3 +91,53 @@ If that output does not appear, try running `eidors_startup`, which should be lo
 
 (note: this is largely peripheral to ViNERS itself, but is included here for completeness. Some of the solutions to these problems )
 
+**Problem:** Unrecognized function or variable `expdir`.
+
+**Solution:** add the Utilities folder to the path or remove the call to `expdir` and replace it with the full path to the resource you are trying to access. The utilities folder is available on gitlab at https://gitlab.unimelb.edu.au/ceiber/matlab-utilities. 
+
+In order to work efficiently, routine tasks (file path handling, PDF generation, and some others) have been off-loaded to a series of simple utilities which lived in my local utilities folder (Documents/MATLAB/Utilities). The function `expdir` is an example of such a utility which provides a compact syntax for accessing a library of standardized file-paths across my systems. `expdir` is used in nearly every model run or analysis script, at a minimum to add ViNERS to the path and occasionally to access other resources. 
+
+If you are continuing development, I recommend maintaining the `expdir` system for your filesystem as I have found it very useful. For instance, if I have needed to move a resource, updating the path in `expdir` has the effect of preventing the need to update that path across hundreds of scripts. Many of the other utilities which I found most useful have been duplicated in the [+tools](Tools/Overview) folder of ViNERS, e.g. `tidyPlotForIllustrator` is provided as `tools.tidyPlot`. 
+
+**Problem:** Unable to resolve the name `tools.file`.
+
+**Solution:** Add ViNERS to your path. If you have expdir, `path(path,expdir('ViNERS'))` will do the trick. See [+tools.file](Tools/file.m) for more information. 
+
+**Problem:** Error using expdir (line 120)
+`CE-20****** not found in Experiment folders.`
+
+**Solution:** Replace the call to expdir with the full path to the required resource, or update expdir. 
+
+The resource you are trying to access has been moved, or you are using expdir on a system for which it no longer has the correct paths to the required resources. 
+ 
+**Problem:** Error using load: `Unable to read file '../data/missingFile.mat'. No such file or directory.`
+
+**Solution:** Update the code to the current path to the resource. 
+
+Many filenames and filepaths were changed during the process of experiment curation and archival. The most common changes are renaming “results” to “derivative” (or “figures”) and “data” to “primary” (or “derivative”). In some places I have updated the code to point to these new locations but in general the code likely relies on old resource locations. 
+
+**Note:** many scripts iterate over files, using code like 
+
+```matlab
+list = dir(‘../data/filespec*.mat’).
+```
+
+These scripts may not throw an error for missing files, but instead run and return nothing or generate empty figures. The underlying issue remains the same. 
+
+**Problem:** Error using tools.file>set_subject_ID (line 334)
+```
+Missing sub-*** in ~/primary, did you mean to call tools.make_SPARC_subject?
+Error in tools.file (line 69)
+      sub = set_subject_ID(info,varargin{:});
+```
+
+**Solution:** Update the code to the current subject/sample path to the resource. 
+
+Similar to the above issue, this relates to missing or moved data. In this case, in a call to `
+tools.file('set', ... )` the requested subject path was not found in `[ViNERS]/primary/`. Most often, this is because the requested subject has been moved to `[experiment]/primary/`, but it is also possible that the experiment number has been changed for other reasons (e.g. different subjects folders have different numbers for instances of ViNERS on different platforms, or related work was grouped by sample or split by run). In many cases, solving this issue where `tools.file('set')` is called will make will fix all of the other `tools.file` path outputs. In the case of folders having been moved to `[experiment]/primary/`, replacing the subject in `tools.file` with `'../primary/sub-...'` (i.e. a local subject path) will work as long as the current version of ViNERS is on the path. 
+
+For experiments where subjects.xlsx is generative, it may be necessary to either update the subject/sample path specified in subjects.xlsx, or replace the call in the script a constant, valid subject/sample path. 
+
+`tools.file('list')` will list all subjects currently saved to `[ViNERS]/primary/` 
+
+IF you have multiple installations of ViNERS on your system, this issue can also arise if you have the wrong instance of ViNERS on your path. This can be tested by running `cd(tools.file)` and observing if the ViNERS path where you land is where you expected to land.