Update 'README.md'

README.md

@@ -1,2 +1,54 @@
-# dHCP_fetal_fMRI_release_paper
+# The resourse contains materials and scripts associated with dHCP fetal fMRI release paper
+This page is in the process of being updated, for specific queries please write to: slava.karolis@kcl.ac.uk
+
+
+
+# temporal filtering
+The folder containing the code is `denoise`
+The core script performing temporal filtering is `dnx.py`
+Running this script is faciliated by `dnx_wrapper.py`, which allows customising temporal filtering model and saves the processed data.
+
+dnx_wrapper.py accepts 4 non-optional inputs:  
+`--sub` - subject ID, e.g., CC00856XX15 
+
+`--ses` - session ID, e.g., 3530  
+
+`--root_dir` - root directory for the dHCP data (the one that contains rawdata and derivatives data structures  
+
+`--odir` - directory for writing the output. Needs to be unique for each case/model; otherwise, the outputs will be overwritten. Two outputs are generated: `data.nii.gz` (data after temporal filtering) and `yhat.nii.gz` (timeseries that has been removed from the data as a result of temporal filtering). In other words, `data.nii.gz` + `yhat.nii.gz` will reconstruct the data prior to filtering
+
+The optional parameters can be defined to customise the temporal filtering model and/or overwrite the default settings:
+
+`--config` - this allows using your own configuration file. Note that you will have to modify the code if you want to use regressors, which are not available in the release 
+
+`--regr_set` - customised regressor set, space-separated. The keys to the regressor types are:
+>`vc` - volume censoring   
+`dm` - density map  
+`fm` - folding maps  
+`ica` - temporal courses of independent components, obtained by FSL melodic, derived from white matter + csf mask  
+`bp` - frequency bandpath filtering  
+`mp_pca` - motion-parameter (MP) based regressors>  
+The default option (used for the release) includes all of the above  
+
+`--ica-options` - number of independent components to include (max 6, which is default). These components are derived from combined eroded white matter + CSF mask. If you want to use a larger number of components, you will need to re-run FSL melodic with dimensionality of your choice and alter config file correspondingly. The eroded WF+CSF mask is included in the release
+
+`--mp_pca-options` - customises the set of motion-parameter(MP)-based voxelwise regressors using convention `XX_YY_pZZ` or `XX_YY_nZZ`, where `XX` is the number of regressors of the 1st type, `YY` - the number of regressors of the 2nd type, and `pZZ` or `nZZ` is the rule for the regressor set truncation. Below is the a more detailed explanation.  
+There are two types of MP-based regressors, one is based on MP proper and the other is representing slice-to-to-slice MP changes (see the section "Motion parameter (MP)-based voxelwise maps" in the paper for the exact definition). The code takes these as an input and performs - indpendently for each type - their expansion, adding to them, in exact order, their squared value, volumetric differential, squared value of volumetric differentials, second order volumetric differentials, the squared value of their second order differentials. Internally, the script prevents using options that are divisible by 6 with a remainder, which is the number of motion parametes (3 rotation and 3 translation parameters). The expansions of the two types of regressors are then concatentated and converted into principal component representation. There are two ways that allow one to truncate the obtained set, using the flag `p` for the percent of variance explained by obtained components in the entire regressor set and `n` for the number of regressors to keep. For instance, the default option is `36_24_p99`, which signifies 36 regressors of the 1st type, 24 of the second type, and using components that account for 99 percent of variance in the concatentated regressor set. Alternatively, `36_24_n6` signifies the identical expansions of the MP-based regressors and subsequent PCA representation, but only the first 6 principal components will be included into the model     
+
+`--bp-options` - define bandpath for the frequencies to regress out using convention `lXX_hYY`, `hYY_lXX`, `lXX` or `hYY`, where XX is a decimal fraction for a cut-off lowpass frequency and YY is the same for a cut-off highpass frequency. For instance `l1` represents the cut-off lowpass frequency of 0.1. The default is `h0067` (the cut-off highpass frequency .0067)
+
+Examples: 
+
+The filtering model used for the release, using parameters defined in config.yml and therefore dropping optional parameters, is:
+
+`python ./dnx_wrapper.py --sub $subID --ses $sesID --root_dir $path_to_dHCP_data_directory  --odir $output_directory` 
+
+The same model can be written explicitly (and can be used as a template for modification of the model) as:
+
+`python ./dnx_wrapper.py --sub $subID --ses $sesID --root_dir $path_to_dHCP_data_directory  --odir $output_directory --config ./config.yml --regr_set vc bp dm fm ica mp_pca --mp_pca-options 36_24_p99 --ica-options 6 --bp-options h0067`
+
+
+
+
+