From 12cf6eb157fa9aa1da84df1055ad9646100b46d6 Mon Sep 17 00:00:00 2001 From: jalew188 Date: Sat, 15 Jun 2024 10:44:01 +0200 Subject: [PATCH 1/4] #53 ADD docs for viz --- alpharaw/viz/plot_utils.py | 140 +++++++++++++++++++++++++++--- alpharaw/viz/psm_plot.py | 155 ++++++++++++++++++++++++++++++++-- alpharaw/viz/xic_plot_tims.py | 2 + 3 files changed, 279 insertions(+), 18 deletions(-) diff --git a/alpharaw/viz/plot_utils.py b/alpharaw/viz/plot_utils.py index 5b6b8bf..d6282aa 100644 --- a/alpharaw/viz/plot_utils.py +++ b/alpharaw/viz/plot_utils.py @@ -7,14 +7,39 @@ def plot_scatter( - x_values, - y_values, - color, - marker_size, - hovertext, - hovertemplate, - name="", -): + x_values: np.ndarray, + y_values: np.ndarray, + color: str, + marker_size: int, + hovertext: str, + hovertemplate: str, + name: str = "", +) -> go.Scatter: + """ + plotly scatter based on x and y points. + + Parameters + ---------- + x_values : np.ndarray + x values for :class:`go.Scatter` + y_values : np.ndarray + y values for :class:`go.Scatter` + color : str + color name + marker_size : int + marker size of the point (x,y) + hovertext : str + `hovertext` parameter of :class:`go.Scatter` + hovertemplate : str + `hovertemplate` parameter of :class:`go.Scatter` + name : str, optional + `name` parameter of :class:`go.Scatter`, by default '' + + Returns + ------- + go.Scatter + go.Scatter of plotly + """ return go.Scatter( x=x_values, y=y_values, @@ -43,7 +68,34 @@ def plot_line_tims( view_dim: typing.Literal["rt", "im"] = "rt", # or 'im' intensity_scale: float = 1.0, rt_unit: str = "minute", -): +) -> go.Figure: + """ + Plot an XIC line on alphatims `TimsTOF` data + + Parameters + ---------- + tims_data : TimsTOF + The alphatims `TimsTOF` object + tims_raw_indices : np.ndarray + Raw indices on `TimsTOF` object + tims_view_indices : np.array + View indices on `TimsTOF` object + name : str + Display name + legend_group : str + Lines will be grouped by `legend_group` + marker_color : str + Color of the scatter (x, y) + view_dim : "rt", "im", optional + View dimension, "rt" or "im", by default "rt" + rt_unit : str, optional + RT unit, by default "minute" + + Returns + ------- + go.Figure + Line plot + """ x_dimension = alphatims_labels[view_dim] intensities = tims_data.bin_intensities(tims_raw_indices, [x_dimension]) @@ -73,11 +125,42 @@ def plot_line_tims_fast( name: str, legend_group: str, marker_color: str, - view_dim: typing.Literal["rt", "im"] = "rt", # or 'im' + view_dim: typing.Literal["rt", "im"] = "rt", intensity_scale: float = 1.0, rt_unit: str = "minute", add_peak_area=True, -): +) -> go.Figure: + """ + Plot an XIC line on alphatims `TimsTOF` data + + Parameters + ---------- + tims_data : TimsTOF + The alphatims `TimsTOF` object + tims_raw_indices : np.ndarray + Raw indices on `TimsTOF` object + tims_view_indices : np.array + View indices on `TimsTOF` object + name : str + Display name + legend_group : str + Lines will be grouped by `legend_group` + marker_color : str + Color of the scatter (x, y) + view_dim : "rt", "im", optional + View dimension, "rt" or "im", by default "rt" + intensity_scale : float, optional + Intensity scale of mirror plot, by default 1.0 + rt_unit : str, optional + RT unit, by default "minute" + add_peak_area : bool, optional + If add peak area in the hover text, by default True + + Returns + ------- + go.Figure + _description_ + """ x_dimension = alphatims_labels[view_dim] intensities = tims_data.bin_intensities(tims_raw_indices, [x_dimension]) @@ -113,7 +196,35 @@ def plot_line( x_text: str = "RT", other_info: str = "", hovertemplate: str = "%{text}
Intensity: %{y}", -): +) -> go.Scatter: + """ + Plot a line for given x and y points, this is usually for XIC plots. + + Parameters + ---------- + x_values : np.ndarray + x values for :class:`go.Scatter` + y_values : np.ndarray + y values for :class:`go.Scatter` + name : str + Legend name for the plotted line + marker_color : str + Marker color of the point (x,y) + legend_group : str + Different lines can be grouped by the same `legend_group` + x_text : str, optional + Hover text of the x axis, by default "RT" + other_info: str, optional + Other hover information, by default "" + hovertemplate : str, optional + `hovertemplate` parameter of :class:`go.Scatter`, + by default '%{text}
Intensity: %{y}' + + Returns + ------- + go.Scatter + The plotted line + """ return go.Scatter( x=x_values, y=y_values, @@ -136,7 +247,10 @@ def plot_line_df( legend_group: str, marker_color: str, view_dim: str = "rt", # or 'im' -): +) -> go.Figure: + """ + TODO deprecated + """ if view_dim == "rt": tims_sliced_df = tims_sliced_df.groupby("frame_indices", as_index=False).agg( { diff --git a/alpharaw/viz/psm_plot.py b/alpharaw/viz/psm_plot.py index f4b55a3..47f2f40 100644 --- a/alpharaw/viz/psm_plot.py +++ b/alpharaw/viz/psm_plot.py @@ -13,6 +13,24 @@ from .plot_utils import plot_scatter color_map: dict = defaultdict(lambda: "brown") +""" +The colors of different peak annotations. By default: +``` +{ + '-': 'lightgrey', # umnatched peaks + 'a': 'darkskyblue', + 'b': 'blue', + 'c': 'skyblue', + 'x': 'darkred', + 'y': 'red', + 'z': 'deeppink', + 'M': 'purple', # precursor + 'Y': 'orange', + 'B': 'darkgreen', +} +``` +For other annotations, the default color is "brown". +""" color_map.update( { "-": "lightgrey", # umnatched peaks @@ -50,6 +68,55 @@ def plot_multi_psms( query_left_margin: float = 100000.0, query_right_margin: float = 100000.0, ): + """ + Annotate multiple spectra for a peptide in a single plotly go.Figure. + + Parameters + ---------- + spec_masses_list : typing.List[np.ndarray] + The list of peak masses of multiple spectra to be annotated + spec_intens_list : typing.List[np.ndarray] + The list of peak intensities of multiple spectra to be annotated + sequence : str + Peptide sequence + mods : str + Modifications in alphabase format + mod_sites : str + Modification sites in alphabase format + charge : int + Charge state of the precursor + title : str, optional + Plotting title, by default "" + ppm : float, optional + Matching mass tolerance in ppm, by default 20.0 + charged_frag_types : list, optional + Fragment charge states, by default ["b_z1","b_z2","y_z1","y_z2"] + include_fragments : bool, optional + If annotate fragments, by default True + include_precursor_isotopes : bool, optional + If annotate precursor isotopes, by default False + max_isotope : int, optional + Maximal number of isotopes, by default 6 + min_frag_mz : float, optional + Minimal fragment m/z value to annotate, by default 100.0 + plot_unmatched_peaks : bool, optional + If plot unmatched peaks (ion_name='-'), by default True + match_mode : "closest", "highest", optional + Match the closest or highest peak within the matching tolerance, by default "closest" + plot_template : str, optional + Plot template, by default 'plotly_white' + plot_height : int, optional + Plot height, by default 600 + query_left_margin : float, optional + Slice margin to the left mz, by default 100000.0 + query_right_margin : float, optional + Slice martin to the right mz, by default 100000.0 + + Returns + ------- + go.Figure + The annotation plots of multiple spectra + """ plot_df = make_query_df_for_peptide( sequence, mods, @@ -97,6 +164,37 @@ def plot_multi_spectra( plot_template="plotly_white", plot_height=600, ): + """ + Annotate multiple spectra for given queries in a single plotly go.Figure. + + Parameters + ---------- + spec_masses_list : typing.List[np.ndarray] + The list of peak masses of multiple spectra to be annotated + spec_intens_list : typing.List[np.ndarray] + The list of peak intensities of multiple spectra to be annotated + query_masses : np.ndarray + The query m/z values + query_ion_names : typing.List[str] + The query ion names + query_mass_tols : np.ndarray + The query mass tolerance in ppm + title : str, optional + The plot title, by default "" + plot_unmatched_peaks : bool, optional + If plot unmatched peaks (ion_name='-'), by default True + match_mode : "closest", "highest", optional + Match the closest or highest peak within the matching tolerance, by default "closest" + plot_template : str, optional + Plot template, by default 'plotly_white' + plot_height : int, optional + Plot height, by default 600 + + Returns + ------- + go.Figure + The annotation plots of multiple spectra + """ plot_dfs = [] for spec_masses, spec_intens in zip(spec_masses_list, spec_intens_list): plot_dfs.append( @@ -138,16 +236,35 @@ def plot_multi_spectra( class PSM_Plot: + """ + The main class for spectrum annotation of a PSM. It contains three plots: + 1. Ladder plot (`FragCoveragePlot`) for fragment coverage of the peptide. + 2. Peak annotation plot (`PeakPlot`) for the spectrum. + 3. Matching mass error plot (`MassErrPlot`) for the matched peaks. + + + Parameters + ---------- + peak_plot_rows : int, optional + The height (ratio) of peak plot, by default 4 + mass_err_plot_rows : int, optional + The height (ratio) of mass error plot, by default 1 + frag_coverage_plot_rows : int, optional + The height (ratio) of fragment coverage plot, by default 1 + frag_coverage : bool, optional + If plot fragment coverage, by default True + """ + vertical_spacing = 0.05 template = "plotly_white" plot_height = 600 def __init__( self, - peak_plot_rows=4, - mass_err_plot_rows=1, - frag_coverage_plot_rows=1, - frag_coverage=True, + peak_plot_rows: int = 4, + mass_err_plot_rows: int = 1, + frag_coverage_plot_rows: int = 1, + frag_coverage: bool = True, ): specs = [] if frag_coverage: @@ -190,7 +307,35 @@ def __init__( self.frag_cov_row = frag_cov_row self.rows = peak_plot_rows + mass_err_plot_rows + frag_coverage_plot_rows - def plot(self, plot_df, sequence, title, plot_unmatched_peaks=False): + def plot( + self, + plot_df: pd.DataFrame, + sequence: str, + title: str, + plot_unmatched_peaks: bool = False, + ) -> go.Figure: + """ + Main entry of `PSM_Plot` for peak annotation. + + Parameters + ---------- + plot_df : pd.DataFrame + The plot_df can be generated by + :func:`alpharaw.viz.df_utils.make_psm_plot_df_for_peptide`, + :func:`alpharaw.viz.df_utils.make_psm_plot_for_frag_dfs`, or + :func:`alpharaw.viz.df_utils.make_psm_plot_df`. + sequence : str + Peptide sequence, for fragment coverage plot + title : str + Plot title + plot_unmatched_peaks : bool, optional + If plot unmatched peaks with ion_name `-`, by default False + + Returns + ------- + go.Figure + Peak annotation plot in plotly go.Figure + """ if "pcc" in plot_df.columns and len(plot_df) > 0: title = f"{title} (R={plot_df.pcc.values[0]:.3f})" self._init_plot(title) diff --git a/alpharaw/viz/xic_plot_tims.py b/alpharaw/viz/xic_plot_tims.py index 4765bf9..314343c 100644 --- a/alpharaw/viz/xic_plot_tims.py +++ b/alpharaw/viz/xic_plot_tims.py @@ -1,3 +1,5 @@ +# TODO Deprecated + import typing import numpy as np From 7e1a4780adc5c765bada0e06b0cfb19a870cb123 Mon Sep 17 00:00:00 2001 From: jalew188 Date: Sat, 15 Jun 2024 10:54:36 +0200 Subject: [PATCH 2/4] #53 FIX mass_tols are always Da --- alpharaw/viz/psm_plot.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/alpharaw/viz/psm_plot.py b/alpharaw/viz/psm_plot.py index 47f2f40..3e0d6d5 100644 --- a/alpharaw/viz/psm_plot.py +++ b/alpharaw/viz/psm_plot.py @@ -178,7 +178,7 @@ def plot_multi_spectra( query_ion_names : typing.List[str] The query ion names query_mass_tols : np.ndarray - The query mass tolerance in ppm + The query mass tolerance in Da title : str, optional The plot title, by default "" plot_unmatched_peaks : bool, optional From 60897376833aae6f4870e307909496ab9c8f16d8 Mon Sep 17 00:00:00 2001 From: jalew188 Date: Mon, 17 Jun 2024 12:58:25 +0200 Subject: [PATCH 3/4] #53 FIX docs: use init pattern --- alpharaw/viz/psm_plot.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/alpharaw/viz/psm_plot.py b/alpharaw/viz/psm_plot.py index 3e0d6d5..2bb5820 100644 --- a/alpharaw/viz/psm_plot.py +++ b/alpharaw/viz/psm_plot.py @@ -241,18 +241,6 @@ class PSM_Plot: 1. Ladder plot (`FragCoveragePlot`) for fragment coverage of the peptide. 2. Peak annotation plot (`PeakPlot`) for the spectrum. 3. Matching mass error plot (`MassErrPlot`) for the matched peaks. - - - Parameters - ---------- - peak_plot_rows : int, optional - The height (ratio) of peak plot, by default 4 - mass_err_plot_rows : int, optional - The height (ratio) of mass error plot, by default 1 - frag_coverage_plot_rows : int, optional - The height (ratio) of fragment coverage plot, by default 1 - frag_coverage : bool, optional - If plot fragment coverage, by default True """ vertical_spacing = 0.05 @@ -266,6 +254,18 @@ def __init__( frag_coverage_plot_rows: int = 1, frag_coverage: bool = True, ): + """ + Parameters + ---------- + peak_plot_rows : int, optional + The height (ratio) of peak plot, by default 4 + mass_err_plot_rows : int, optional + The height (ratio) of mass error plot, by default 1 + frag_coverage_plot_rows : int, optional + The height (ratio) of fragment coverage plot, by default 1 + frag_coverage : bool, optional + If plot fragment coverage, by default True + """ specs = [] if frag_coverage: specs.append( From 257d96a88edc9de0206a9e63ebd369756df94357 Mon Sep 17 00:00:00 2001 From: jalew188 Date: Tue, 18 Jun 2024 15:27:13 +0200 Subject: [PATCH 4/4] xic_plot_tims.py deprecation --- alpharaw/viz/xic_plot_tims.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/alpharaw/viz/xic_plot_tims.py b/alpharaw/viz/xic_plot_tims.py index 314343c..03207a3 100644 --- a/alpharaw/viz/xic_plot_tims.py +++ b/alpharaw/viz/xic_plot_tims.py @@ -1,6 +1,5 @@ -# TODO Deprecated - import typing +import warnings import numpy as np import pandas as pd @@ -13,6 +12,11 @@ from .plot_utils import plot_line_tims_fast +warnings.warn( + "This module will be deprecated or changed in the future releases", + category=DeprecationWarning, +) + class XIC_Plot_Tims: # hovermode = "x" | "y" | "closest" | False | "x unified" | "y unified"