Add extensive documentation/explanation of results and figures

[veitveit]

Only in markdown or also in R/python?

Each jupyter cell could be introduced by a describing text

[jgriss]

I guess you mean that we should add a documentation string within the code? Or add a text (ie. markdown cell) before every code cell?

[veitveit]

Difficult to decide. I am tending towards a mix. We could document the figures more extensively as they appear and add text in between the cells that shortly explain the different parts.

Or, alternatively, make one larger section on the top that explains the entire workflow.

Code in the text

• allows accurate placing of comments and explanations
• will (in R parts)/can (in python cells) appear only when getting results and figures to explain

Markdown cells

• can be easily formatted and edited
• follow a common format (as python and R will have different outputs)

[jgriss]

I think a "dual" approach is probably best: adding mark down cells to explain what's happening and what the different types of plots show for the non-expert user.

Add (extensive) source code comments to allow more bioinformatics oriented users to adapt the code as they need it.

I'll give it a try and we'll see if it works. Ok?

[veitveit]

Yes, that could work. But we will need a more extensive description. This will not be enough though as a non-experienced user won't understand the different parameters (e.g. for quantification). On the other hand, the notebook should not be overfilled with information.

I added the file Description.ipynb where we can be more specific. Actually, we could start writing (or copying after writing) the paper there.

[veitveit]

A rather detailed documentation of parameters, output and access to the code is now available in https://github.com/ProtProtocols/IsoLabeledProtocol/blob/master/Description.ipynb

@jgriss please take a look so we can close this issue.

[jgriss]

@veitveit

Minor changes added from my side. Just re-open if you think we should change more.