Review and refactor figure and data scripts before submission

[adonath]

See title.

[aboucaud]

Hey,

I would like to come back on the rather blunt remark I made during the paper presentation of the sprint week with a more constructive input than "I don't understand this figure".

I lead the software development activities in the CS department at APC and was invited by Regis and Bruno to have an overview of the current status of Gammapy. Even though I have a good idea of the main structure of the software, I tried to look at this figure as a completely external developer and tried to find the information I am usually looking for in an overview figure for a software package.

Here are my main comments.

Overall impression

• First thing I see is a bunch of logos of various sizes, including one duplicate and it feels like this relative size has a meaning. I don't think it has (I might be wrong)
• Then I see a triangular structure created by these logos, which prevents me from imagining this is a workflow
• Then, I finally manage to focus on the gray/shaded arrows that indicate this is actually a workflow, but I do have to make an effort to see the direction of these arrows.
• Last I try to read what's in the boxes/arrows and I encounter several abbreviations which I am not familiar with and cannot find any help of definition in the caption.

Various ideas/comments

• use a horizontal and linear representation for depicting a workflow
• reduce the size of the experiments logos and make sure to set a common size
• do not use gray/dark gray on white
• use the same font and fontsize for the data levels and skip the abbreviations
• drawing boxes around the DL3 / DL4 / DL5-6 might help seeing this as workflow steps
• not sure GADF is relevant is such overview figure, however "gamma-like events" and "binned data" found on Fig 3 would be appreciated
• mixing Fig1 and Fig3 might be a good idea if you remove pure API details (classes) and stick to the submodules.
• producing such figure with matplotlib is very brave and I like the idea (as well as the showyourwork initiative) but to enforce good visualisation principles, this might not give the best value/time spent.

@registerrier @bkhelifi

[adonath]

Thanks a lot @aboucaud, this is important feedback!

Some short inline comments:

use a horizontal and linear representation for depicting a workflow

The workflow is not fully linear, as some data is "injected" at the DL3 other at the DL4 level. I will think about it again...

reduce the size of the experiments logos and make sure to set a common size

The CTA is intentionally larger, the others can have equal size. I will double check whether this is fulfilled.

do not use gray/dark gray on white

Why is that? I think it is good practice to use gray scale / transparency to introduce layers to a figure. Gray or transparent elements are less important, which I consider the helpful to structure the content.

drawing boxes around the DL3 / DL4 / DL5-6 might help seeing this as workflow steps

Agree, this might help...

not sure GADF is relevant is such overview figure, however "gamma-like events" and "binned data" found on Fig 3 would be appreciated

The data levels are relevant, as some data comes in on the DL3 the on the DL4 data level. However when merging the figure this should become clearer...

mixing Fig1 and Fig3 might be a good idea if you remove pure API details (classes) and stick to the submodules.

Yes, this was exactly the plan. I will propose a new version of the figure soon, any more feedback is appreciated.

producing such figure with matplotlib is very brave and I like the idea (as well as the showyourwork initiative) but to enforce good visualisation principles, this might not give the best value/time spent.

Yes, I mostly agree. The figure was initially created for the documentation and updated multiple times. Good visualization practices can be realized with matplotlib as well. However the time effort for placing resizing elements is still too high, compared to a drag and drop. For me it was an interesting "experiment", as I'am almost "fluent" in matplotlib, but in the end the only person, that could work on the figure was me...would never do it again.

[aboucaud]

Why is that? I think it is good practice to use gray scale / transparency to introduce layers to a figure. Gray or transparent elements are less important, which I consider the helpful to structure the content.

I did not mean my comment as a general rule. But in this particular figure, with the colourful logos and inserted plots and figures, the gray used here is IMO not visible enough to structure the content as you intent to. Maybe a slightly darker flavour would be best, at least.

For me it was an interesting "experiment", as I'am almost "fluent" in matplotlib, but in the end the only person, that could work on the figure was me...would never do it again.

I can only agree with that 😄