restructure tutorials
mihai-sysbio opened this issue · 7 comments
Based on team discussions, it it proposed to alter the userData folder and protocol.m as follows:
- Rename
userDatatotutorial - Mention the ecYeastGEM that is generated in GECKO3 explicitly as tutorial model, so the protocol constructs a tutorial ecModel which is based on S. cerevisiae. This means that e.g. various model-specific filenames would include _tutorial or something similar.
- Because of the above, it is very important to (repeatedly) mention that the model generated in protocol.m is a tutorial model. It will also be included in the filename, explicitly mentioned somewhere in the text.
- make sure there is a functional
protocol.mfortutorial_Human-GEM
Added another to-do to provide a protocol.m for tutorial_Human-GEM.
After having a first attempt at it, I propose the content of the tutorials to look like this:
tutorial_modelAtutorial_modelBblankExamplewhere the protocol and adapter are shared in full will all comments
Each tutorial_ has its own protocol and adapter. To avoid having to maintain documentation in all protocols (in all tutorials), the tutorial_ protocols are compressed (only useful code). The only "full" protocol.m is the one from the blankExample.
The Readme should also now point to the different tutorials.
The idea has been to have protocol.m match the manuscript text. That means, protocol.m generates a model for S. cerevisiae, and the user could have the MATLAB code open while reading through the paper. With that in mind, it is less convenient to have the detailed comments in blankExample instead.
Meanwhile, the idea of blankExample was to provide a suggested minimal configuration of folder structure and model adapter file. In that light it makes less sense to include a script with commands that refer to a specific yeast model.
So my suggestion is to leave out protocol from blankExample, and keep the detailed comments in the protocol in tutorial_yeast.
I'm thinking as a user, what would I do - where would I start from?
a) An existing tutorial_. The tutorial should "just work" as-is. Since probably the next step is to modify some parameters, I will then need to understand more about these so I will look at the documentation, which is the full protocol.m and the generic adapter. For me it's normal for documentation to sit elsewhere from the tutorial/example.
b) An empty canvas, the blankExample. Here I probably need the full protocol and generic adapter, so I can start coding. Probably the documentation can be elsewhere, but I will have go through it closely since I am not familiar with all the parameters and options. To me, it is an improved experience to have the documentation in the blank example so that as a user I only need that folder to have a complete picture.
Now, here is what I think is potentially very tricky:
The idea has been to have protocol.m match the manuscript text.
and
the user could have the MATLAB code open while reading through the paper
The manuscript text is expected to stay the same after publication. At the same time, we can expect some post-publication fixes and other changes. Therefore, coupling these together might be okay only for a short while.
Now I understand. Considering the comments from you both, I kind of agree with @edkerk , i.e., do not use the blankExample, just keep detailed comments in tutorial_yeast.
Providing the blankExample sounds super convenient, but making a general blankExample suitable for any organism seems to be impossible. If @mihai-sysbio you can achieve this, then I would be very happy to include it.
Regarding tutorial_ecoli, I will make it.
This is just like what we proposed on Teams, i.e., provide several organism-specific protocols but do not save the resulting ecModels.