Confusion about configfile usage in GGIR

[javierlealmartin]

Hi community!

I would like to ask for some clarification and share a possible improvement regarding the explanation of the configfile parameter in the GGIR documentation (https://wadpac.github.io/GGIR/articles/chapter2_Pipeline.html#configuration-file-).

From my reading of the first paragraph of the Configuration file section, I find it somewhat unclear whether configfile is used to specify an alternative directory for saving a new (re-run) config.csv file (to avoid overwriting an annotated version), or to retrieve GGIR parameter settings so that explicit calls in the R source or console can be avoided. The second paragraph of the section helped clarify this somewhat, pointing toward the second interpretation, but the overall explanation still feels a bit blurred to me.

Based on my interpretation, I suggest the section’s paragraphs could be clarified as follows (amendments are shown in bold and italic):

GGIR stores all the parameter values in a csv-file named config.csv. The file is stored after each run of GGIR in the root of the output folder, overwriting any existing config.csv file. So, if you would like to add annotations in the file, for example in the fourth column, then you will need to store it somewhere outside the output folder to avoid overwriting and preserve those changes. The config.csv file can also be used to run GGIR with the parameter settings it contains, so that explicit parameter calls in the R source or console are not needed. This can be done by specifying the path to the config.csv file using the configfile parameter. Note that the datadir and outputdir parameters discussed below always need to be specified directly and are not part of the configfile.
library(GGIR)

The practical value of this is that it eases the replication of the analysis, because instead of having to share you R script with colleagues, sharing your config.csv file will be sufficient for GGIR to retrieve the suitable parameter settings. Please make sure you have the same GGIR and R version installed when using this for reproducibility. See here for guidance on how to install older package versions.

Please let me know if this change makes sense to you, or if you see it differently.

Thank you very much in advance!

Best
Javier

[vincentvanhees]

Thanks, see my suggestion on how to rewrite the text here:
main...issue1473_configfile_documentation

Motivation:

• I think it is better to avoid "so that explicit parameter calls in the R source or console are not needed", because we can use both a configfile and parameter specification via an R script, and the extraction order is explained in the next section.
• Your addition "to avoid overwriting and preserve those changes" should refer to "comments" and not to "changes", because otherwise reader may think this relates to parameter changes.
• I would not say "for GGIR to retrieve the suitable parameter settings." because this sentence is specific about replicating analysis and not about whether settings are suitable. So, I think it reads better mention again the replication.

Hopefully my suggestion above helps to clarify the parameters. Let me know what you think?

[javierlealmartin]

Hi Vincent!

Thanks for your reply and for taking the time to propose an improved version of the text. I really appreciate it.

I’d like to clarify a bit better what I meant. To my understanding, in the first paragraph I learn that:

• GGIR writes a config.csv file.
• This file gets overwritten at each run.
• And that, if I want to add annotations in the file, then I need to:

1. store it somewhere outside the output folder, and
2. specify the path to that file with the configfile parameter.

At that point, the text seems to suggest to me that specifying the file via configfile is part of the process of adding annotations, which makes me lose the thread a bit (I tell myself: since I already reallocated the annotated config.csv, I should be fine preserving it in subsequent reruns, so why should I need to specify it to configfile, and how does that help me further?). It is confusing because the text hasn’t yet explained why someone would want GGIR to use configfile.

So up to that point, I clearly understand that I need to move the config.csv to a different location to preserve annotations (as a descriptive reservoir?), but I'm confused why GGIR would need me to pass that file back in through configfile, especially for the purpose of adding annotations.

Once I read the second paragraph, and the subsequent section "Parameter extraction order", it becomes clear that configfile plays a role in retrieving the config.csv settings, so everything makes sense, but the connection relies on reaching that later explanation.

My only thought was that the reason for supplying the file back to GGIR could perhaps be clarified further in the first paragraph, or moved to the second paragraph where the replicability aspect is introduced. But maybe this is simply my personal reading of the text, and I fully defer to your judgement.

Thanks again for your time. I really value the work behind it, and especially this configfile parameter, which I think is extremely helpful when collaborating with other researchers!

Javier

[vincentvanhees]

Thanks for clarifying, I agree that this part is confusing.

I have now rephrased the text to focus on the main reason we have a configuration file, and I removed the statement about leaving annotations.

Using the configfile parameter for annotations is problematic because the parameters inside it are not updated after:

• Changed parameter settings in the R code
• Changed GGIR defaults or new GGIR parameters when GGIR itself is updated.

Therefore, there is a real risk for outdated information in the configuration file, this is why I think it is best not to use the file for annotations at all.

[vincentvanhees]

@javierlealmartin when you have time please let me know whether you are happy with the changes I made, which you can see here:
#1486
(click on 'Files changed' to see what I changed).

[javierlealmartin]

@vincentvanhees Your new description is much clearer to me now. I hope it helps others!

Thank you very much for considering my suggestion.