Review the API

[ielis]

We want to make using Genophenocorr as simple as possible.

There are several things that can be done:

• create helper functions that need just the most basic input, while letting the user tweak the details, if desired
• show examples in the documentation and in the notebooks
• use meaningful function names, and informative pydoc strings, related to method names should be unambiguous #59, TranscriptAnnotation hgvsc_id #111

We need to review the API when the functionality is finished and we are ready to publish the paper, along with v1.0.0.

@graefea can help with the review.

[ielis]

@graefea I'm adding you here, but please wait with the actual review until we are done with the development. We will keep you updated.

[aslgraefe]

@ielis @pnrobinson @lnrekerle I am activating this issue to start commenting on the gpsea documentation and usability of the code while analysing cohorts (see gpsea-cs repo)

[aslgraefe]

First intuitive comments on the Documentation upon implementation

General first comments

• I think the overall tutorial analysis helped very much to go over an entire enalysis. I liked the references to the user-guide, such as to the Input Data of which we could add more in the analysis.
• As I am a last-year medical student, I had to look up quite a few terms (we never really have statistics in the course of our study). I think humangeneticists and specialised clinicians will have more experience. However, the way you referenced to the main modes of inheritance, we could think about enhancing the glossary to address clinicians that need to update their knowledge on genetics, statistics and/or programming.
• I really liked how you explained the predicates and how to implement them in the cohort analyses. What I am currently (and intuitively) struggling with is the overlap with the statistical tests, see: https://github.com/monarch-initiative/gpsea-cs/issues/37 - which may be resolved with further cohorts.
• your point from above

- create helper functions that need just the most basic input, while letting the user tweak the details, if desired 

could be discussed, to have a kind of logical selection before and after each extra step. This could help create a red line through all the different tests and possibilities GPSEA offers.
--> Generally, I am very excited about this! This is finally something we can do reliable and precise RD analysis with - on different diseases.

Minor Comments
Tutorial:

• Show cohort summary: move the Note below into this section before the output is shown

# Note
#The report can also be displayed directly in a Jupyter notebook by running
IPython.display import HTML, display
display(HTML(report))

• Summarize all variant allele: also here I had a difficult using the command

with open('docs/report/tbx5_all_variants.html', 'w') as fh:  
    _ = fh.write(report)

Instead I used display(HTML(report)) which works easier.

[ielis]

@aslgraefe

regarding your comment on

create helper functions that need just the most basic input, while letting the user tweak the details, if desired

I am not planning to make any major updates to the workflow at this point and we will expect the users to follow the examples from the docs, as I said yesterday. There is more to the analysis than what is in the examples, and I am not sure if it can be simplified even further without losing the "generality".

Regarding the other comments from your post, I think we went through them yesterday. However, please let me know if this is not what you think and if you expect more feedback.

Thank you very much! :)