P2GX · ielis · Jan 28, 2025 · Jan 16, 2025 · Jan 17, 2025 · Jan 17, 2025
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,6 +3,7 @@
 import os
 import sys
 
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -63,7 +64,7 @@
 # The short X.Y version.
 version = u'0.9'
 # The full version, including alpha/beta/rc tags.
-release = u'0.9.2'
+release = u'0.9.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -217,4 +218,4 @@
 copybutton_exclude = '.linenos, .gp, .go'
 
 # -- Sphinx Dark Mode setup --------------------------------------------------
-# default_dark_mode = False
+# default_dark_mode = False
diff --git a/docs/img/tutorial/tbx5_protein_diagram.png b/docs/img/tutorial/tbx5_protein_diagram.png
diff --git a/docs/report/tbx5_truncating_vs_missense.csv b/docs/report/tbx5_truncating_vs_missense.csv
@@ -1,19 +1,18 @@
-Allele group,Missense,Missense,Truncating,Truncating,,
-,Count,Percent,Count,Percent,Corrected p values,p values
-Ventricular septal defect [HP:0001629],31/60,52%,29/29,100%,9.550859422122477e-06,5.618152601248516e-07
-Hypoplasia of the radius [HP:0002984],30/62,48%,10/27,37%,1.0,0.3614379675325876
-Atrial septal defect [HP:0001631],42/44,95%,38/38,100%,1.0,0.49653718759409815
-Secundum atrial septal defect [HP:0001684],14/35,40%,13/40,32%,1.0,0.6304400561799244
-Abnormal cardiac septum morphology [HP:0001671],62/62,100%,50/50,100%,1.0,1.0
-Abnormal hand morphology [HP:0005922],53/53,100%,41/41,100%,1.0,1.0
-Abnormal atrial septum morphology [HP:0011994],43/43,100%,38/38,100%,1.0,1.0
-Abnormal cardiac atrium morphology [HP:0005120],43/43,100%,38/38,100%,1.0,1.0
-Abnormal appendicular skeleton morphology [HP:0011844],64/64,100%,60/60,100%,1.0,1.0
-Aplasia/hypoplasia of the extremities [HP:0009815],55/55,100%,44/44,100%,1.0,1.0
-Aplasia/hypoplasia involving the skeleton [HP:0009115],56/56,100%,45/45,100%,1.0,1.0
-Aplasia/hypoplasia involving bones of the upper limbs [HP:0006496],55/55,100%,44/44,100%,1.0,1.0
-Aplasia/hypoplasia involving bones of the extremities [HP:0045060],55/55,100%,44/44,100%,1.0,1.0
-Abnormal long bone morphology [HP:0011314],44/44,100%,19/19,100%,1.0,1.0
-Abnormal finger morphology [HP:0001167],36/36,100%,56/56,100%,1.0,1.0
-Abnormal digit morphology [HP:0011297],38/38,100%,59/59,100%,1.0,1.0
-Abnormal thumb morphology [HP:0001172],30/30,100%,56/56,100%,1.0,1.0
+,Missense,Truncating,Corrected p values,p values
+Ventricular septal defect [HP:0001629],31/60 (52%),29/29 (100%),9.550859422122477e-06,5.618152601248516e-07
+Hypoplasia of the radius [HP:0002984],30/62 (48%),10/27 (37%),1.0,0.3614379675325876
+Atrial septal defect [HP:0001631],42/44 (95%),38/38 (100%),1.0,0.49653718759409815
+Secundum atrial septal defect [HP:0001684],14/35 (40%),13/40 (32%),1.0,0.6304400561799244
+Abnormal thumb morphology [HP:0001172],30/30 (100%),56/56 (100%),1.0,1.0
+Abnormal finger morphology [HP:0001167],36/36 (100%),56/56 (100%),1.0,1.0
+Abnormal digit morphology [HP:0011297],38/38 (100%),59/59 (100%),1.0,1.0
+Abnormal atrial septum morphology [HP:0011994],43/43 (100%),38/38 (100%),1.0,1.0
+Abnormal cardiac atrium morphology [HP:0005120],43/43 (100%),38/38 (100%),1.0,1.0
+Abnormal long bone morphology [HP:0011314],44/44 (100%),19/19 (100%),1.0,1.0
+Abnormal hand morphology [HP:0005922],53/53 (100%),41/41 (100%),1.0,1.0
+Aplasia/hypoplasia of the extremities [HP:0009815],55/55 (100%),44/44 (100%),1.0,1.0
+Aplasia/hypoplasia involving bones of the upper limbs [HP:0006496],55/55 (100%),44/44 (100%),1.0,1.0
+Aplasia/hypoplasia involving bones of the extremities [HP:0045060],55/55 (100%),44/44 (100%),1.0,1.0
+Aplasia/hypoplasia involving the skeleton [HP:0009115],56/56 (100%),45/45 (100%),1.0,1.0
+Abnormal cardiac septum morphology [HP:0001671],62/62 (100%),50/50 (100%),1.0,1.0
+Abnormal appendicular skeleton morphology [HP:0011844],64/64 (100%),60/60 (100%),1.0,1.0
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -166,32 +166,17 @@ the most common HPO terms, variants, diseases, and variant effects:
 Plot distribution of variants with respect to the protein sequence
 ------------------------------------------------------------------
 
-We can also show the distribution of variants with respect to the encoded protein.
-We first obtain ``tx_coordinates`` (:class:`~gpsea.model.TranscriptCoordinates`)
-with genomic coordinates of the transcript, including e.g. untranslated regions or exons:
+We can use :class:`~gpsea.view.CohortArtist` to plot the distribution of variants
+with respect to the encoded protein on
+a Matplotlib `Axes <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html>`_:
 
->>> from gpsea.preprocessing import configure_default_tx_coordinate_service
->>> tx_service = configure_default_tx_coordinate_service(genome_build="GRCh38.p13")
->>> tx_coordinates = tx_service.fetch(tx_id)
-
-
-and we also get ``protein_meta`` (:class:`~gpsea.model.ProteinMetadata`)
-with the domains and regions of the encoded protein:
-
->>> from gpsea.preprocessing import configure_default_protein_metadata_service
->>> pms = configure_default_protein_metadata_service()
->>> protein_meta = pms.annotate(px_id)
-
-Now we can plot a diagram of the mutations on the protein:
-
->>> from gpsea.view import ProteinVisualizer
 >>> import matplotlib.pyplot as plt
+>>> from gpsea.view import configure_default_cohort_artist
+>>> cohort_artist = configure_default_cohort_artist()
 >>> fig, ax = plt.subplots(figsize=(15, 8))
->>> visualizer = ProteinVisualizer()
->>> visualizer.draw_protein_diagram(
-...     tx_coordinates,
-...     protein_meta,
-...     cohort,
+>>> cohort_artist.draw_protein(
+...     cohort=cohort,
+...     protein_id=px_id,
 ...     ax=ax,
 ... )
 

diff --git a/docs/user-guide/analyses/partitioning/genotype/allele_count.rst b/docs/user-guide/analyses/partitioning/genotype/allele_count.rst
@@ -61,7 +61,7 @@ based on presence of zero or one *EGFR* mutation allele:
 ...     target=affects_egfr,
 ... )
 >>> gt_clf.class_labels
-('0', '1')
+('0 alleles', '1 allele')
 
 The ``allele_count`` needs two inputs.
 The ``counts`` takes a tuple of the target allele counts,
@@ -102,9 +102,9 @@ and we will compare the individuals with one allele with those with two alleles:
 ...     target=affects_lmna,
 ... )
 >>> gt_clf.class_labels
-('1', '2')
+('1 allele', '2 alleles')
 
 
 The classifier assigns the individuals into one of two classes:
 those with one *LMNA* variant allele and those with two *LMNA* variant alleles.
-Any cohort member with other allele counts (e.g. `0` or `3`) is ignored.
+Any cohort member with other allele counts (e.g. `0 allele` or `3 alleles`) is ignored.
diff --git a/docs/user-guide/analyses/phenotype-scores.rst b/docs/user-guide/analyses/phenotype-scores.rst
@@ -39,10 +39,10 @@ This is a non-parametric test that compares the medians of the two classes to de
 >>> r = stats.mannwhitneyu(x=class1, y=class2, alternative = 'two-sided')
 >>> p_value = r.pvalue
 >>> float(p_value)
-6.348081479150902e-06
+6.348081479150...e-06
 
 
-p value of `6.348081479150901e-06` suggests a significant difference between the classes.
+p value of `6.348081479150e-06` suggests a significant difference between the classes.
 
 
 ****************
@@ -73,7 +73,7 @@ from a `JSON file <https://github.com/monarch-initiative/gpsea/tree/main/docs/co
 The cohort was prepared from phenopackets as described in :ref:`create-a-cohort` section,
 and then serialized as a JSON file following the instructions in :ref:`cohort-persistence` section.
 
-.. 
+..
    Prepare the JSON file by running the tests in `tests/tests/test_generate_doc_cohorts.py`.
 
 >>> import json
@@ -99,8 +99,8 @@ Genotype predicate
 ------------------
 
 *Jordan et al.* compare phenotype of individuals harboring point mutations
-with the individuals carrying loss of function mutations. 
-Let's create a predicate for testing if the variant 
+with the individuals carrying loss of function mutations.
+Let's create a predicate for testing if the variant
 is a point mutation or a loss of function mutation.
 
 In this example, the point mutation is a mutation that meets the following conditions:
@@ -158,7 +158,7 @@ As far as GPSEA framework is concerned, the phenotype score must be a floating p
 or a `NaN` value if the score cannot be computed for an individual.
 This is the essence of the :class:`~gpsea.analysis.pscore.PhenotypeScorer` class.
 
-GPSEA ships with several builtin phenotype scorers which can be used as  
+GPSEA ships with several builtin phenotype scorers which can be used as
 
 +------------------------------------------------------------+---------------------------------------------+
 | Name                                                       | Description                                 |
@@ -189,7 +189,7 @@ from the following 5 categories:
 
 For example, an individual with a congenital heart defect would be assigned a score of `1`,
 an individual with congenital heart defect and a renal anomaly would be assigned a score of `2`,
-and so on. If an individual had two heart defects (e.g., atrial septal defect and ventricular septal defect), 
+and so on. If an individual had two heart defects (e.g., atrial septal defect and ventricular septal defect),
 a score of 1 (not 2) would be assigned for the heart defect category.
 
 The :class:`~gpsea.analysis.pscore.CountingPhenotypeScorer` automatizes this scoring method
@@ -245,7 +245,7 @@ We will put the final analysis together into :class:`~gpsea.analysis.pscore.Phen
 
 >>> from gpsea.analysis.pscore import PhenotypeScoreAnalysis
 >>> score_analysis = PhenotypeScoreAnalysis(
-...     score_statistic=score_statistic,   
+...     score_statistic=score_statistic,
 ... )
 
 
@@ -265,8 +265,8 @@ In case of the *RERE* cohort, the analysis shows a significant difference
 between the number of structural defects in individuals
 with point vs. loss-of-function mutations.
 
->>> result.pval
-0.012074957610483744
+>>> result.pval # doctest: +ELLIPSIS
+0.0120749576...
 
 
 To explore further, we can access a data frame with genotype categories and phenotype counts:

diff --git a/docs/user-guide/analyses/report/rere_phenotype_score_boxplot.png b/docs/user-guide/analyses/report/rere_phenotype_score_boxplot.png
diff --git a/docs/user-guide/analyses/report/tbx5_frameshift.csv b/docs/user-guide/analyses/report/tbx5_frameshift.csv
@@ -1,26 +1,25 @@
-Allele group,Frameshift,Frameshift,Other,Other,,
-,Count,Percent,Count,Percent,Corrected p values,p values
-Ventricular septal defect [HP:0001629],19/19,100%,42/71,59%,0.005806240832840839,0.00024192670136836828
-Absent thumb [HP:0009777],14/31,45%,18/100,18%,0.04456405819223913,0.0037136715160199273
-Secundum atrial septal defect [HP:0001684],4/22,18%,23/55,42%,0.4065940176561687,0.06544319142266644
-Triphalangeal thumb [HP:0001199],13/32,41%,23/99,23%,0.4065940176561687,0.06932119159387057
-Muscular ventricular septal defect [HP:0011623],6/25,24%,8/84,10%,0.4065940176561687,0.08470708701170182
-Short thumb [HP:0009778],8/30,27%,25/69,36%,1.0,0.4870099714553749
-Absent radius [HP:0003974],6/25,24%,9/43,21%,1.0,0.7703831604944444
-Atrial septal defect [HP:0001631],20/20,100%,63/65,97%,1.0,1.0
-Abnormal atrial septum morphology [HP:0011994],20/20,100%,64/64,100%,1.0,1.0
-Abnormal cardiac septum morphology [HP:0001671],28/28,100%,89/89,100%,1.0,1.0
-Abnormal cardiac atrium morphology [HP:0005120],20/20,100%,64/64,100%,1.0,1.0
-Hypoplasia of the radius [HP:0002984],6/14,43%,34/75,45%,1.0,1.0
-Abnormal appendicular skeleton morphology [HP:0011844],34/34,100%,93/93,100%,1.0,1.0
-Aplasia/hypoplasia of the extremities [HP:0009815],22/22,100%,78/78,100%,1.0,1.0
-Aplasia/hypoplasia involving the skeleton [HP:0009115],23/23,100%,80/80,100%,1.0,1.0
-Aplasia/hypoplasia involving bones of the upper limbs [HP:0006496],22/22,100%,78/78,100%,1.0,1.0
-Aplasia/hypoplasia involving bones of the extremities [HP:0045060],22/22,100%,78/78,100%,1.0,1.0
-Abnormal long bone morphology [HP:0011314],13/13,100%,50/50,100%,1.0,1.0
-Abnormal hand morphology [HP:0005922],20/20,100%,75/75,100%,1.0,1.0
-Abnormal thumb morphology [HP:0001172],31/31,100%,58/58,100%,1.0,1.0
-Abnormal finger morphology [HP:0001167],31/31,100%,64/64,100%,1.0,1.0
-Abnormal digit morphology [HP:0011297],33/33,100%,67/67,100%,1.0,1.0
-Aplasia/Hypoplasia of fingers [HP:0006265],19/19,100%,44/44,100%,1.0,1.0
-Aplasia/hypoplasia involving bones of the hand [HP:0005927],19/19,100%,44/44,100%,1.0,1.0
+,Frameshift,Other,Corrected p values,p values
+Ventricular septal defect [HP:0001629],19/19 (100%),42/71 (59%),0.005806240832840839,0.00024192670136836828
+Absent thumb [HP:0009777],14/31 (45%),18/100 (18%),0.04456405819223913,0.0037136715160199273
+Secundum atrial septal defect [HP:0001684],4/22 (18%),23/55 (42%),0.4065940176561687,0.06544319142266644
+Triphalangeal thumb [HP:0001199],13/32 (41%),23/99 (23%),0.4065940176561687,0.06932119159387057
+Muscular ventricular septal defect [HP:0011623],6/25 (24%),8/84 (10%),0.4065940176561687,0.08470708701170182
+Short thumb [HP:0009778],8/30 (27%),25/69 (36%),1.0,0.4870099714553749
+Absent radius [HP:0003974],6/25 (24%),9/43 (21%),1.0,0.7703831604944444
+Abnormal long bone morphology [HP:0011314],13/13 (100%),50/50 (100%),1.0,1.0
+Aplasia/Hypoplasia of fingers [HP:0006265],19/19 (100%),44/44 (100%),1.0,1.0
+Aplasia/hypoplasia involving bones of the hand [HP:0005927],19/19 (100%),44/44 (100%),1.0,1.0
+Atrial septal defect [HP:0001631],20/20 (100%),63/65 (97%),1.0,1.0
+Abnormal atrial septum morphology [HP:0011994],20/20 (100%),64/64 (100%),1.0,1.0
+Abnormal cardiac atrium morphology [HP:0005120],20/20 (100%),64/64 (100%),1.0,1.0
+Abnormal hand morphology [HP:0005922],20/20 (100%),75/75 (100%),1.0,1.0
+Aplasia/hypoplasia of the extremities [HP:0009815],22/22 (100%),78/78 (100%),1.0,1.0
+Aplasia/hypoplasia involving bones of the upper limbs [HP:0006496],22/22 (100%),78/78 (100%),1.0,1.0
+Aplasia/hypoplasia involving bones of the extremities [HP:0045060],22/22 (100%),78/78 (100%),1.0,1.0
+Aplasia/hypoplasia involving the skeleton [HP:0009115],23/23 (100%),80/80 (100%),1.0,1.0
+Abnormal cardiac septum morphology [HP:0001671],28/28 (100%),89/89 (100%),1.0,1.0
+Abnormal thumb morphology [HP:0001172],31/31 (100%),58/58 (100%),1.0,1.0
+Abnormal finger morphology [HP:0001167],31/31 (100%),64/64 (100%),1.0,1.0
+Abnormal digit morphology [HP:0011297],33/33 (100%),67/67 (100%),1.0,1.0
+Abnormal appendicular skeleton morphology [HP:0011844],34/34 (100%),93/93 (100%),1.0,1.0
+Hypoplasia of the radius [HP:0002984],6/14 (43%),34/75 (45%),1.0,1.0
diff --git a/docs/user-guide/analyses/report/umod_km_curves.png b/docs/user-guide/analyses/report/umod_km_curves.png
diff --git a/docs/user-guide/analyses/survival.rst b/docs/user-guide/analyses/survival.rst
@@ -27,7 +27,7 @@ from a `JSON file <https://github.com/monarch-initiative/gpsea/tree/main/docs/co
 The cohort was prepared from phenopackets as described in :ref:`create-a-cohort` section,
 and then serialized as a JSON file following the instructions in :ref:`cohort-persistence` section.
 
-.. 
+..
    Prepare the JSON file by running the tests in `tests/tests/test_generate_doc_cohorts.py`.
 
 >>> import json
@@ -127,7 +127,7 @@ We execute the analysis by running
 ... )
 
 >>> result.pval
-0.06200425830044376
+0.062004258300...
 
 
 Kaplan-Meier curves
@@ -145,13 +145,13 @@ We can plot Kaplan-Meier curves:
 ... )
 >>> _ = ax.xaxis.set(
 ...     # Show X axis in years ...
-...     major_formatter=mpl.ticker.FuncFormatter(lambda x, pos: f"{x / Age.DAYS_IN_YEAR:.0f}"),  
+...     major_formatter=mpl.ticker.FuncFormatter(lambda x, pos: f"{x / Age.DAYS_IN_YEAR:.0f}"),
 ...     # ... with a tick for every decade
 ...     major_locator=mpl.ticker.MultipleLocator(10 * Age.DAYS_IN_YEAR),
 ... )
 >>> _ = ax.set(
 ...     xlabel=endpoint.name + " [years]",
-...     ylabel="Empirical survival",
+...     ylabel="Event-free proportion",
 ... )
 >>> _ = ax.grid(axis="y")
 
@@ -164,7 +164,7 @@ We can plot Kaplan-Meier curves:
    :hide:
 
    >>> if _overwrite: fig.savefig('docs/user-guide/analyses/report/umod_km_curves.png')
-   
+
 
 Raw data
 --------
@@ -174,7 +174,7 @@ The `result` includes the survival values for all cohort members:
 >>> survivals = result.data.sort_index()
 >>> survivals.head()  # doctest: +NORMALIZE_WHITESPACE
                           genotype    phenotype
-patient_id                                                                        
+patient_id
 AII.1[PMID_22034507_AII_1]       0    Survival(value=18262.5, is_censored=True)
 AII.2[PMID_22034507_AII_2]       0    None
 AII.3[PMID_22034507_AII_3]       0    Survival(value=16436.25, is_censored=True)

diff --git a/docs/user-guide/exploratory.rst b/docs/user-guide/exploratory.rst
@@ -78,11 +78,11 @@ Then we choose the transcript and protein identifiers, and we fetch the correspo
 
 >>> from gpsea.preprocessing import configure_default_tx_coordinate_service, configure_default_protein_metadata_service
 >>> tx_id = "NM_181486.4"
->>> pt_id = "NP_852259.1"
+>>> px_id = "NP_852259.1"
 >>> tx_service = configure_default_tx_coordinate_service(genome_build="GRCh38.p13")
 >>> tx_coordinates = tx_service.fetch(tx_id)
 >>> pm_service = configure_default_protein_metadata_service()
->>> protein_meta = pm_service.annotate(pt_id)
+>>> protein_meta = pm_service.annotate(px_id)
 
 
 Last, we load HPO `v2024-07-01` to use in the exploratory analysis:
@@ -148,7 +148,7 @@ This code will produce the following table on the basis of a cohort of individua
 with variants in the *TBX5* gene:
 
 >>> from gpsea.view import ProteinVariantViewer
->>> cpd_viewer = ProteinVariantViewer(tx_id=tx_id, protein_metadata=protein_meta)
+>>> cpd_viewer = ProteinVariantViewer(protein_metadata=protein_meta, tx_id=tx_id)
 >>> report = cpd_viewer.process(cohort)
 >>> report  # doctest: +SKIP
 
@@ -164,20 +164,59 @@ with variants in the *TBX5* gene:
 Plot distribution of variants with respect to the protein sequence
 ------------------------------------------------------------------
 
-We use Matplotlib to plot the distribution of variants on a protein diagram:
+Cohort artist
+^^^^^^^^^^^^^
+
+The simplest way to plot the variant distribution is to use the :class:`~gpsea.view.CohortArtist` API:
 
 >>> import matplotlib.pyplot as plt
+>>> from gpsea.view import configure_default_cohort_artist
+>>> cohort_artist = configure_default_cohort_artist()
+>>> fig, ax = plt.subplots(figsize=(15, 8))
+>>> cohort_artist.draw_protein(
+...     cohort=cohort,
+...     protein_id=px_id,
+...     ax=ax,
+... )
+
+
+.. image:: img/TBX5_protein_diagram.from_artist.png
+   :alt: TBX5 protein diagram
+   :align: center
+   :width: 600px
+
+.. doctest:: exploratory
+    :hide:
+
+    >>> if _overwrite:
+    ...     fig.tight_layout()
+    ...     fig.savefig('docs/user-guide/img/TBX5_protein_diagram.from_artist.png')
+
+The :func:`~gpsea.view.configure_default_cohort_artist` function gets the default artist
+which we use to plot the diagram with the variant distribution across the protein sequence
+on Matplotlib axes.
+
+
+Protein visualizer
+^^^^^^^^^^^^^^^^^^
+
+Sometimes, however, things do not work out-of-the-box, e.g. because protein metadata
+is not available from Uniprot (the default), and we may need to use the lower-level components.
+
+The :class:`~gpsea.view.ProteinVisualizer` takes cohort and the protein metadata
+to plot the distribution of variants on a protein diagram:
+
 >>> from gpsea.view import ProteinVisualizer
 >>> fig, ax = plt.subplots(figsize=(15, 8))
 >>> visualizer = ProteinVisualizer()
->>> visualizer.draw_protein_diagram(
-...     tx_coordinates,
-...     protein_meta,
-...     cohort,
+>>> visualizer.draw_protein(
+...     cohort=cohort,
+...     protein_metadata=protein_meta,
 ...     ax=ax,
 ... )
 
-.. image:: img/TBX5_protein_diagram.png
+
+.. image:: img/TBX5_protein_diagram.from_protein_visualizer.png
    :alt: TBX5 protein diagram
    :align: center
    :width: 600px
@@ -187,5 +226,4 @@ We use Matplotlib to plot the distribution of variants on a protein diagram:
 
     >>> if _overwrite:
     ...     fig.tight_layout()
-    ...     fig.savefig('docs/user-guide/img/TBX5_protein_diagram.png')
-
+    ...     fig.savefig('docs/user-guide/img/TBX5_protein_diagram.from_protein_visualizer.png')
diff --git a/docs/user-guide/img/TBX5_protein_diagram.from_artist.png b/docs/user-guide/img/TBX5_protein_diagram.from_artist.png
diff --git a/docs/user-guide/img/TBX5_protein_diagram.from_protein_visualizer.png b/docs/user-guide/img/TBX5_protein_diagram.from_protein_visualizer.png
diff --git a/docs/user-guide/img/TBX5_protein_diagram.png b/docs/user-guide/img/TBX5_protein_diagram.png