pyplis tutorials (jupyter notebooks)

[jgliss]

Currently, the user friendliness is a little limited, since tutorials are missing. The current recommendation to get started is, to download the example dataset which is also used in the paper.

However, these scripts do not contain a lot of explanatory text and are currently also used to perform high-level testing. These scripts will have to remain unchanged for historical reasons as they are referred to throughout the paper.

However, looking into the future, I think it would be valuable to have a number of tutorial jupyter notebooks that introduce individual features of pyplis and to guide through a typical analysis.

That's the idea and help and input from others is highly appreciated as the time that I can spend on developing pyplis is very limited.

Here are some first thoughts / things to discuss:

• Separate repo?: I think it could be good to have the tutorial notebooks in a separate repo (e.g. pyplis-tutorials) that may also contain the data that is used to avoid that pyplis repo grows too big over time.
  • This could make it a little more tricky to embed them in the autogeneration of the documentation on the RTD website based on the sphinx docs.
• Which data should they be based on?
  • I think it should not be (or only in parts) based on the pyaerocom example dataset that is used in the paper as this is quite big (2.7 GB) and not required to illustrate most of the features.
  • It would be good to have at least one or a few example image(s) from different user groups.
  • Investigate wheter data in pyplis/data/ could be used, particularly testdata_minimal (4MB)
• What should be the layout / logical structure / naming conventions of the tutorials? Do we need different categories (like feature introduction or data analysis similar to the example scripts)?

[johannjacobsohn]

This sounds like a very good idea to reduce the necessary effort to get started with pyplis, and I'll be glad to help.

I agree the scripts should stay to ensure backwards-compability via automated tests.

I don't think this should go into a separate repo. Adding a couple of text and sample files wont blow up the repository size too much and if repo size is an issue, users can always shallow-clone.

I think the example date should only contain as much as needed to get started, and there should be additional unit tests using supplied "real-world" data sets from all supported groups.

As for layout, I think it might be best to have a "getting-started" notebook that goes from reading files to aa or so2 data, and advanced scripts for flux etc. And notebooks should not refer to each other as the current scripts do, which makes it really intricate to follow a single example.

I'll try to find the time to make a simple getting-started notebook so that we can play around with the idea.

[jgliss]

Thanks a lot, Johann, for offering to help on this and I agree with you in all points. I agree that a getting started tutorial will be a good first tutorial and I am looking forward to your input. Note that I am very busy until the second week of April and I might not be very responsive until then.

[jgliss]

@johannjacobsohn hope all is well and that you are still in the volcano imaging business. Just wanted to hear if you still have plans to contribute to pyplis in the future? Cheers, Jonas