Need for more specific terminology when referring to visual reports

[vincentvanhees]

We have been referring to the GGIR pdf reports as visual report, QC report or time series report. This has been confusing as all of them are visual reports, all of them serve a purpose for quality checking, and all of them show time series. I would like to explore whether we can revise how we name and refer to the reports to be more distinct.

Currently we have:

No.	File name	Purpose
1	results/QC/plots_to_check_data_quality_1.pdf	Basic check for recording length and compliance to study protocol in part 2
2	results/visualisation_sleep.pdf	Basic check of sleep detection and sleep diary in part 4
3	results/file summary reports/Time_report_.....pdf	Elaborate check of derived time series of both data and its classification after part 5
4	results/file summary reports/Report_.....pdf	Old visual report that is not ideal for data quality checking but has been used

I am ignoring the 'sleep.qc' pdfs as I think those can eventually be deprecated as they now overlap with report 3.

Idea A

No.	Proposed new filename	Proposed way of referring to the file in documentation and in GitHub issues
1	part2_report_1.pdf	Part 2 visual report
2	part4_report.pdf	Part 4 visual report
3	Report_v2_....pdf	File summary report v1
4	Report_v1_....pdf	File summary report v2

Advantages:

• It is clear in which GGIR part they were generated
• Name does not put restrictions on future content.

Disadvantage:

• Filenames themselves do not say much about what the report represents.
• Giving version numbers to the reports is not ideal as it gives the impression that any update will result in a new number.

Idea B

No.	Proposed new filename	Proposed way of referring to the file in documentation and in GitHub issues
1	basic_report_1.pdf	Basic visual report
2	sleep_report.pdf	Visual sleep report
3	general_report....pdf	General visual report
4	Report_....pdf (same as how it was)	Older visual report

Advantages:

• Filenames provide a hint about their contents

Disadvantage:

• It is not clear in which GGIR part they are generated

@jhmigueles or anyone else seeing this: Do you have a preference or do you have alternative suggestions?

I may want to implement these updates before the 3.2-0 release in February.

[vincentvanhees]

Once we have decided on new naming:

• Update file names
• Update documentation references to these filenames
• Update function names and if applicable unit-tests.

[jhmigueles]

@vincentvanhees

What about combining the options you provide? Something like...

No.	Proposed new filename	Proposed way of referring to the file in documentation
1	part2_basic_report.pdf	Part 2 basic report
2	part4_sleep_report.pdf	Part 4 sleep report
3	Report_[...].pdf	General visual report (either older or updated)

Not sure if we need to differentiate older and newer in the general report name, it can complicate future versions (if any). There are other functionalities that are updated over time without receiving new names, although I can see that it can be useful to log what version is used in the file name... Not sure what is the best option here.

[vincentvanhees]

@forget999 please do not post questions unrelated to the issue.
If you have new question then just open a new issue.

I have now hidden all your responses. Please continue your discussion elsewhere.

[vincentvanhees]

thanks @jhmigueles

Not sure if we need to differentiate older and newer in the general report name, it can complicate future versions (if any). There are other functionalities that are updated over time without receiving new names, although I can see that it can be useful to log what version is used in the file name... Not sure what is the best option here.

We currently generate both the new and old report to avoid a radical change in GGIR and to give user some time to get used to the new report. However, eventually I hope to deprecate the old report, so we just need a temporary solution.

How about including old in the "old" report name, and no old in the new report name.