Added first draft of template for documentation of prediction algorithm

[tdraebing]

Description

I added a first draft of a template for documenting candidates of prediction algorithms that could be included into this project.

Reference to official issue

Issue #58

Motivation and Context

The template contains the following sections:

• A short summary
• Source of the algorithm
• License
• Prerequisites
• Description of the algorithm design
• Reference/User instructions to the trained model
• Model performance
• Use cases
• Changes that are needed for adaptation into this project
• Misc. comments
• References

How Has This Been Tested?

The markdown is displayed correctly in PyCharm.
This is just a first draft and I encourage everybody to comment or commit possible improvements to this pull request.

Screenshots (if appropriate):

CLA

• I have signed the CLA; if other committers are in the commit history, they have signed the CLA as well

[lamby]

@reubano Assigning to thee for review :)

[reubano]

@tdraebing this is looking good! I didn't see a place to document the ML engine/backend, e.g., Keras/TensorFlow/etc. Where do you envision that information going?

[tdraebing]

You are right. That should be a separate point. It would show up in the dependencies section, but that might not be easy and convenient to find for somebody reading the docs.
Before I add that point, is the aim of the project to support several frameworks? Or would you rather try to rewrite the models to fit one backend of choice (e.g. all to Keras with Tensorflow-backend)? Then I would add that part to the "Adaptation"-section.

[reubano]

It would show up in the dependencies section, but that might not be easy and convenient to find for somebody reading the docs.

Agreed! I think it's deserving of its own section (see the table in #18 for an example).

... is the aim of the project to support several frameworks? Or would you rather try to rewrite the models to fit one backend of choice (e.g. all to Keras with Tensorflow-backend)?

The aim is to support whatever model is thrown at it. Most implementations are based on Keras/Tensorflow, but that isn't a requirement. So as long the proper engines and libs are installed, everything should "just work".

Then I would add that part to the "Adaptation"-section.

If someone is more fluent in an engine than what was originally used, they are more than welcome to rewrite it. But I think this aspect is out-of-scope for the documentation.

[tdraebing]

Ok, I added an extra point for the ML framework into the "Prerequisites"-section.

[WGierke]

Thanks for the template! I have a small question: where is the difference between Prerequisites - is porting to Python 3.5 feasible? and Adaptation into Concept to Clinic - Comment on possible problems/solutions for porting the algorithm to Python 3.5+? Should the letter one contain more detailed steps / comments?

[tdraebing]

Yes, the second one should contain detailed steps or comments. The point "Prerequisites - is porting to Python 3.5 feasible?" should be answered with yes/no. It was mainly put there in case the algorithm is not already written in any version of Python. Would that be the case anyway or rather out of scope? If we anyway only plan to use algorithms already implemented in Python, I would suggest removing this point.

[reubano]

@WGierke and @tdraebing I think we can be fine limiting this to Python only. In this case, maybe change Programming Lang to Python Version? And the is porting to Python 3.5 feasible? would be in case the algorithm is written in 2.7.

[reubano]

Ok, I added an extra point for the ML framework into the "Prerequisites"-section.

Nice! I think the free text box for the ML details would be better structured as a table. That way we can ensure to capture all of the information. I.e.:

key	value
ML engine	pytorch
engine-version	0.1.10+ac9245a
ML backend	N/A

those keys were just the first thing I came up with, so feel free to change them if there are other (more fitting) terms to use instead.

[tdraebing]

I removed the question of feasibility for now, since this might also be commented on in the section dealing with adapting the model to our needs. I also changed part of the dependency section into a table layout.

[lamby]

Hey @reubano What do you think - is this ready to commit?

[reubano]

LGTM