Repository navigation
ENH - Naming and categorisation of example scripts #256
Description
From this discussion comment #254 (comment)
- Rename the example scripts:
gettingstarted,starter, or start could indicate scripts to start with as a newbie
demo to demonstrate a(n advanced) functionality - Files that are not an example script, but a examples-related utility function, should be recognizable as such, and / or be put in a subdirectory
- Additionally, in the README.md within the examples folder, list a preferred order of using the starter scripts.
Activity
AljenU commentedon Oct 21, 2021
Current names and descriptions (gathered by using the aa_example_crawler function), main examples directory only:L
Script: meeg_aa
Automatic analysis
User master script example (aa version 5..)
This script demonstrates a basic EEG pipeline on the LEMON dataset: http://fcon_1000.projects.nitrc.org/indi/retro/MPI_LEMON.html.
It requires the following software to be configured in your parameterset
- SPM
- FSL
- EEGLAB with extensions Fileio, bva-io, clean_rawdata, AMICA, dipfit, Fieldtrip-lite, firfilt, fitTwoDipoles, ICLabel, Viewprops
- FieldTrip
See aa_parametersets/aap_parameters_defaults_UoS.xml, lines 21-56 for example configuration
N.B.: Time-resolved (CONT branch) aamod_meeg_timefrequencystatistics at source level is disabled because it requires high amount of memory. You can
enable it by uncommenting the corresponding lines in the tasklist and this UMS marked with corresponding comment.
Script: aa_example_helloworld_model
this script runs basic preprocessing, and first- and second-level model
on the ds000114 dataset used in the "helloworld" example script. It also
demonstrates how to do processing using the Matlab Parallel Computing
Toolbox if it is available.
Script: demo_branching1_aa
Automatic analysis (aa) - user master script This example runs one session of one
subject through a standard SPM-based fMRI analysis. See also aa_user_demo.
This script demonstrates how branching can be used to explore how the order of slice
time and motion correction affects results (see aap_tasklist_demo_branching1.xml).
v3: Johan Carlin, MRC CBU, 2018-08-06
v2: Tibor Auer MRC Cognition and Brain Sciences Unit, 2016-02-17
v1: Rhodri Cusack Brain and Mind Institute, Western University, 2014-12-15
Script: bids_ds000114_aa
Automatic analysis
User master script example (aa version 5..)
This is an example how to process a BIDS multimodal NIfTI dataset. We assume that you
have already downloaded the dataset to your directory.
Tibor Auer, MRC-CBSU
08-02-2016
Script: demo_branching2_aa
Automatic analysis (aa) - user master script
This example runs one session of one subject through a standard SPM-based
fMRI analysis. See also aa_user_demo.
This script demonstrates nested multi-level branching (see also
aa_user_demo_branching1).
v3: Johan Carlin, MRC CBU, 2018-08-06
v2: Tibor Auer MRC Cognition and Brain Sciences Unit, 2016-02-17
v1: Rhodri Cusack Brain and Mind Institute, Western University, 2014-12-15
Script: aa_example_helloworld
this is a simple aa script that runs a bare minimum tasklist using
OpenNeuro dataset ds000114 (which you must download before running)
This isn't a useful analysis; it's intended to check that your
paths, parameter files, etc are set up correctly.
See "aa_example_helloworld_model" to actually do something useful
with the data.
Script: aa_example_SPM_CH30
This script runs the Auditory fMRI example from the SPM manual
(chapter 30, as of this writing) in aa. It uses BIDS version
of the data. available for download at:
https://www.fil.ion.ucl.ac.uk/spm/download/data/MoAEpilot/MoAEpilot.bids.zip
(NB: this data is missing gzip'ed versions of the structral and epi which
confuses aa. The easiest fix is just gzip /sub-01/anat/sub-01_T!w.nii
and /sub-01/func/sub-01_task-auditory_bold.nii after downloading).
Script: demo_basic_aa
Automatic analysis (aa) - user master script
This example runs one session of one subject through a standard SPM-based
fMRI analysis. After running, look at the results using SPM in
aa_demo_results/auditory/aamod_firstlevel_contrasts_00001/2014_03_29_9001/stats
v3: Johan Carlin, MRC CBU, 2018-08-06
v2: Tibor Auer MRC Cognition and Brain Sciences Unit, 2016-02-17
v1: Rhodri Cusack Brain and Mind Institute, Western University, 2014-12-15
jones-michael-s commentedon Oct 21, 2021
For example renaming, how do people feel about "tutorials" and "demos"?
I was thinking these would be directories under /examples. The tutorials directory would contain helloworld, helloworld_model, and SPM30. The demos directory would contain all other example scripts.
This would saves us having to rename all of the files (the file names are rather inconsistent at present). We could note in the README that tutorials is a good place to get started and demos contain examples meant to be helpful demonstrations of specific aa functionality but not necessarily something a user should expect to be able to run as written.
Additionally, we could include a pdf of my tutorial guide in the tutorials directory (perhaps expanded to include helloworld and helloword_model). That way it doesn't compete with the official aa documentation on the wiki (or wherever we eventually put it). This of course depends on people finding my tutorial useful...
AljenU commentedon Nov 19, 2021
1 I think "tutorials" and "demos" directories would be good. Additionally, have a utilities directory for functions that are used in the examples, but are not example scripts themselves. So it would look like
2 Further, I think helloworld_model and SPM30 can be combined into one, they do almost the same analysis it seems? I'd opt for keeping SPM30, since that also shows the comparison with SPM workflow, but enhancing it with some of the extra comments that are available in helloworld_model.
3 I think the tutorial document, and the appendix, do contain a lot of useful information. And since it goes along with the SPM30 script, it would be good to have it close to it. However, i do think it should not be in pdf format (only), since that would make it hard to update for changes in AA (for instance, recent updates make it so FSL is no longer required to run the SPM30 example, and also i do not get into problems when there are empty newlines at the end of an xml).
I don't know what the current source format is, but for inclusion in the repository, and since it does not have complicated formulas, markdown would be nice. Other editable formats could also work. A pdf export of the source can also be part of the repository, for easier reading. It would need to be kept up to date with the source.
tiborauer commentedon Nov 19, 2021
Ad 1: +1
Ad 2: +1
Ad 3: +1
Reorganize the examples directory
jones-michael-s commentedon Nov 19, 2021
I generally agree. My only question is helloworld_model does a second level analysis and SPM30 does not. Is that important for an introduction?
It seems to me the tutorial would be easy to add to the current on-line documentation (maybe as a tab on the Getting Started page?). The appendix is a bit tricker as similar information is spread throughout the documentation (old wiki). Not sure how to handle that.