seer-pas-sdk 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

seer_pas_sdk/objects/__init__.py

@@ -1,129 +1,3 @@
-import pandas as pd
-
-
-class PlateMap:
-    """
-    Plate map object containing information about samples and corresponding MS data files.
-    """
-
-    def __init__(
-        self,
-        ms_file_name=None,
-        sample_name=None,
-        sample_id=None,
-        well_location=None,
-        nanoparticle=None,
-        nanoparticle_id=None,
-        control=None,
-        control_id=None,
-        instrument_name=None,
-        date_sample_preparation=None,
-        sample_volume=None,
-        peptide_concentration=None,
-        peptide_mass_sample=None,
-        dilution_factor=None,
-        kit_id=None,
-        plate_id=None,
-        plate_name=None,
-    ):
-
-        if not ms_file_name:
-            raise ValueError("MS file name(s) must be provided.")
-
-        self.ms_file_name = ms_file_name
-        self.length = len(ms_file_name)
-
-        self.sample_name = sample_name
-        self.sample_id = sample_id
-        self.well_location = well_location
-        self.nanoparticle = nanoparticle
-        self.nanoparticle_id = nanoparticle_id
-        self.control = control
-        self.control_id = control_id
-        self.instrument_name = instrument_name
-        self.date_sample_preparation = date_sample_preparation
-        self.sample_volume = sample_volume
-        self.peptide_concentration = peptide_concentration
-        self.peptide_mass_sample = peptide_mass_sample
-        self.dilution_factor = dilution_factor
-        self.kit_id = kit_id
-        self.plate_id = plate_id
-        self.plate_name = plate_name
-
-        self.__cols = [
-            "MS file name",
-            "Sample name",
-            "Sample ID",
-            "Well location",
-            "Nanoparticle",
-            "Nanoparticle ID",
-            "Control",
-            "Control ID",
-            "Instrument name",
-            "Date sample preparation",
-            "Sample volume",
-            "Peptide concentration",
-            "Peptide mass sample",
-            "Dilution factor",
-            "Kit ID",
-            "Plate ID",
-            "Plate Name",
-        ]
-
-        self.__attrs = [
-            "ms_file_name",
-            "sample_name",
-            "sample_id",
-            "well_location",
-            "nanoparticle",
-            "nanoparticle_id",
-            "control",
-            "control_id",
-            "instrument_name",
-            "date_sample_preparation",
-            "sample_volume",
-            "peptide_concentration",
-            "peptide_mass_sample",
-            "dilution_factor",
-            "kit_id",
-            "plate_id",
-            "plate_name",
-        ]
-
-        for attr in self.__attrs:
-            if not getattr(self, attr):
-                # Replace falsey values with empty lists
-                setattr(self, attr, [])
-
-            attr_len = len(getattr(self, attr))
-
-            if attr_len > self.length:
-                raise ValueError(
-                    "Parameter lengths must not exceed the number of MS files."
-                )
-
-            elif attr_len < self.length:
-                for i in range(self.length - attr_len):
-                    getattr(self, attr).append(None)
-
-    def to_dict(self):
-        res = {}
-
-        for i in range(len(self.__attrs)):
-            res[self.__cols[i]] = getattr(self, self.__attrs[i])
-
-        for entry in res:
-            res[entry] = {i: res[entry][i] for i in range(len(res[entry]))}
-
-        return res
-
-    def to_df(self):
-        return pd.DataFrame(self.to_dict())
-
-    def to_csv(self, path=None):
-        if not path:
-            return self.to_df().to_csv(index=False)
-        return self.to_df().to_csv(path_or_buf=path, index=False)
-
-    def __repr__(self):
-        return str(self.to_dict())
+from .platemap import PlateMap
+from .groupanalysis import GroupAnalysisPostData
+from .volcanoplot import *

seer_pas_sdk/objects/groupanalysis.py

@@ -0,0 +1,30 @@
+# Filter group analysis data for only the POST
+class GroupAnalysisPostData:
+    """DTO for Group Analysis Saved Results"""
+
+    def __init__(self, data):
+        if "post" not in data:
+            raise ValueError('Invalid data format. Missing "post" key')
+
+        # Safe check if there are proteins vs peptides
+        num_proteins = (
+            data["post"]
+            .get("protein", {"totalFeature": 0})
+            .get("totalFeature", 0)
+        )
+        num_peptides = (
+            data["post"]
+            .get("peptide", {"totalFeature": 0})
+            .get("totalFeature", 0)
+        )
+
+        if num_proteins > 0:
+            self.type = "protein"
+        elif num_peptides > 0:
+            self.type = "peptide"
+        else:
+            raise ValueError(
+                "Invalid data format. No features found in post data"
+            )
+        self.data = data["post"][self.type]["mergedStats"]
+        self.stat_test = data["post"][self.type]["parameters"]["statTest"]

seer_pas_sdk/objects/platemap.py

@@ -0,0 +1,174 @@
+import pandas as pd
+
+
+class PlateMap:
+    """
+    Plate map object containing information about samples and corresponding MS data files.
+    """
+
+    def __init__(
+        self,
+        ms_file_name=None,
+        sample_name=None,
+        sample_id=None,
+        well_location=None,
+        nanoparticle=None,
+        nanoparticle_id=None,
+        control=None,
+        control_id=None,
+        instrument_name=None,
+        date_sample_preparation=None,
+        sample_volume=None,
+        peptide_concentration=None,
+        peptide_mass_sample=None,
+        recon_volume=None,
+        dilution_factor=None,
+        kit_id=None,
+        plate_id=None,
+        plate_name=None,
+        assay_version=None,
+        sample_tube_id=None,
+        method_set_id=None,
+        assay_method_id=None,
+        product="XT",
+    ):
+
+        if not ms_file_name:
+            raise ValueError("MS file name(s) must be provided.")
+
+        self.ms_file_name = ms_file_name
+        self.length = len(ms_file_name)
+
+        self.sample_name = sample_name
+        self.sample_id = sample_id
+        self.well_location = well_location
+        self.nanoparticle = nanoparticle
+        self.nanoparticle_id = nanoparticle_id
+        self.control = control
+        self.control_id = control_id
+        self.instrument_name = instrument_name
+        self.date_sample_preparation = date_sample_preparation
+        self.sample_volume = sample_volume
+        self.peptide_concentration = peptide_concentration
+        self.peptide_mass_sample = peptide_mass_sample
+        self.recon_volume = recon_volume
+        self.dilution_factor = dilution_factor
+        self.kit_id = kit_id
+        self.plate_id = plate_id
+        self.plate_name = plate_name
+        self.assay_version = assay_version
+        self.sample_tube_id = sample_tube_id
+        self.method_set_id = method_set_id
+        self.assay_method_id = assay_method_id
+        self.product = product
+
+        if self.product == "XT":
+            self.__map = {
+                "ms_file_name": "MS file name",
+                "sample_name": "Sample name",
+                "sample_id": "Sample ID",
+                "well_location": "Well location",
+                "nanoparticle": "Nanoparticle",
+                "nanoparticle_id": "Nanoparticle ID",
+                "control": "Control",
+                "control_id": "Control ID",
+                "instrument_name": "Instrument name",
+                "date_sample_preparation": "Date sample preparation",
+                "sample_volume": "Sample volume",
+                "peptide_concentration": "Peptide concentration",
+                "peptide_mass_sample": "Peptide mass sample",
+                "recon_volume": "Recon volume",
+                "dilution_factor": "Dilution factor",
+                "kit_id": "Kit ID",
+                "plate_id": "Plate ID",
+                "plate_name": "Plate Name",
+                "assay_version": "Assay",
+            }
+        else:
+            self.__map = {
+                "ms_file_name": "MS file name",
+                "sample_name": "Sample name",
+                "sample_id": "Sample ID",
+                "well_location": "Well location",
+                "nanoparticle": "Nanoparticle set",
+                "nanoparticle_id": "Nanoparticle set ID",
+                "control_id": "Control ID",
+                "instrument_name": "Instrument ID",
+                "date_sample_preparation": "Date assay initiated",
+                "sample_volume": "Sample volume",
+                "peptide_concentration": "Reconstituted peptide concentration",
+                "peptide_mass_sample": "Recovered peptide mass",
+                "recon_volume": "Reconstitution volume",
+                "plate_id": "Plate ID",
+                "plate_name": "Plate Name",
+                "assay_version": "Assay product",
+                "sample_tube_id": "Sample tube ID",
+                "method_set_id": "Method set ID",
+                "assay_method_id": "Assay method ID",
+            }
+
+        self.__attrs = [
+            "ms_file_name",
+            "sample_name",
+            "sample_id",
+            "well_location",
+            "nanoparticle",
+            "nanoparticle_id",
+            "control",
+            "control_id",
+            "instrument_name",
+            "date_sample_preparation",
+            "sample_volume",
+            "peptide_concentration",
+            "peptide_mass_sample",
+            "recon_volume",
+            "dilution_factor",
+            "kit_id",
+            "plate_id",
+            "plate_name",
+            "assay_version",
+            "sample_tube_id",
+            "method_set_id",
+            "assay_method_id",
+        ]
+
+        for attr in self.__attrs:
+            if not getattr(self, attr):
+                # Replace falsey values with empty lists
+                setattr(self, attr, [])
+
+            attr_len = len(getattr(self, attr))
+
+            if attr_len > self.length:
+                raise ValueError(
+                    "Parameter lengths must not exceed the number of MS files."
+                )
+
+            elif attr_len < self.length:
+                for i in range(self.length - attr_len):
+                    getattr(self, attr).append(None)
+
+    def to_dict(self):
+        res = {}
+
+        supported_cols = self.__map.keys()
+
+        for attr in self.__attrs:
+            if attr in supported_cols:
+                res[self.__map[attr]] = getattr(self, attr)
+
+        for entry in res:
+            res[entry] = {i: res[entry][i] for i in range(len(res[entry]))}
+
+        return res
+
+    def to_df(self):
+        return pd.DataFrame(self.to_dict())
+
+    def to_csv(self, path=None):
+        if not path:
+            return self.to_df().to_csv(index=False)
+        return self.to_df().to_csv(path_or_buf=path, index=False)
+
+    def __repr__(self):
+        return str(self.to_dict())

seer_pas_sdk/objects/volcanoplot.py

@@ -0,0 +1,290 @@
+import numpy as np
+import json
+import pandas as pd
+from typing import List as _List, Dict as _Dict
+from .groupanalysis import GroupAnalysisPostData
+
+
+class VolcanoPlotSettings:
+    """Class to hold the settings information for the Volcano Plot"""
+
+    def __init__(
+        self,
+        significance_threshold: float = 0.05,
+        fold_change_threshold: float = 1,
+        label_by: str = "fold_change",
+    ):
+        """Initialize the VolcanoPlotSettings object
+
+        Args:
+            significance_threshold (float, optional): Cutoff value for the p-value to determine significance. Defaults to 0.05.
+            fold_change_threshold (float, optional): Cutoff value for the fold change to determine significance. Defaults to 1.
+            label_by (str, optional): Metric to sort result data. Defaults to "fold_change".
+
+        Raises:
+            ValueError: "Invalid label_by value, must be one of ['euclidean', 'fold_change', 'significance']"
+        """
+        if label_by not in ["euclidean", "fold_change", "significance"]:
+            raise ValueError(
+                "Invalid label_by value, must be one of ['euclidean', 'fold_change', 'significance']"
+            )
+        self.significance_threshold = significance_threshold
+        self.fold_change_threshold = fold_change_threshold
+        self.label_by = label_by
+
+    @property
+    def values(self):
+        return {
+            "significance_threshold": self.significance_threshold,
+            "fold_change_threshold": self.fold_change_threshold,
+            "label_by": self.label_by,
+        }
+
+    @classmethod
+    def get_settings(cls):
+        return [
+            "significance_threshold",
+            "fold_change_threshold",
+            "label_by",
+        ]
+
+    @classmethod
+    def get_label_by_map(cls):
+        return dict(
+            euclidean="euclideanDistance",
+            fold_change="logFD",
+            significance="negativeLog10P",
+        )
+
+
+class VolcanoPlotBuilder:
+    """
+    Builder class for the Volcano Plot
+    Can be used to reuse the same GroupAnalysisResults data to build multiple Volcano Plots with different settings.
+
+    """
+
+    PROTEIN_GROUP_INDEX = "pg"
+    PEPTIDE_INDEX = "peptide"
+
+    def __init__(
+        self,
+        data: _List[_Dict],
+        significance_threshold: float = 0.05,
+        fold_change_threshold: float = 1,
+        label_by: str = "fold_change",
+    ):
+        """Initialize the VolcanoPlotBuilder object
+
+        Args:
+            data (list[dict]): The complete set of group analysis result data
+            significance_threshold (float, optional): Cutoff value for the p-value to determine significance. Defaults to 0.05.
+            fold_change_threshold (float, optional): Cutoff value for the fold change to determine significance. Defaults to 1.
+            label_by (str, optional): Metric to sort result data. Defaults to "fold_change".
+
+        Raises:
+            ValueError: "Invalid label_by value, must be one of ['euclidean', 'fold_change', 'significance']"
+
+        Returns:
+            None
+        """
+
+        self.settings = VolcanoPlotSettings(
+            significance_threshold=significance_threshold,
+            fold_change_threshold=fold_change_threshold,
+            label_by=label_by,
+        )
+
+        parsed_data = GroupAnalysisPostData(data)
+
+        self.type = parsed_data.type
+        self.stat_test = parsed_data.stat_test
+        self.data = parsed_data.data
+        self.minusLog10PSigValue = -np.log10(
+            self.settings.significance_threshold
+        )
+        self.sort_param = VolcanoPlotSettings.get_label_by_map()[
+            self.settings.label_by
+        ]
+        self.max_logFD, self.max_negative_log10_p = self._get_max_values(
+            self.data
+        )
+        self.protein_gene_map = dict()
+        self.feature_type_index = (
+            self.PROTEIN_GROUP_INDEX
+            if self.type == "protein"
+            else self.PEPTIDE_INDEX
+        )
+        self.volcano_plot = self.build()
+
+    def build(self):
+        """Build the volcano plot
+
+        Returns:
+            list[dict]: sorted volcano plot data
+        """
+        result = []
+        for i, row in enumerate(self.data):
+            result.append(self.build_row(i, row))
+        sorted_result = sorted(
+            result,
+            key=lambda x: (
+                x[self.sort_param]
+                if self.sort_param != "logFD"
+                else np.abs(x[self.sort_param])
+            ),
+            reverse=True,
+        )
+        return sorted_result
+
+    def build_row(self, i, data):
+        """Build a row for the volcano plot
+
+        Args:
+            i (int): The index of the row
+            data (dict): a group analysis result entry
+
+        Returns:
+            dict: The row data
+        """
+        self.protein_gene_map[data[self.feature_type_index]] = data["gene"]
+
+        row = dict(
+            logFD=data["logFD"],
+            negativeLog10P=data["negativeLog10P"],
+            dataIndex=i,
+            rowID=json.dumps(data),
+            gene=data["gene"],
+            group=self.get_contrast_group_string(data),
+            significant=self.get_significance_class(data),
+            euclideanDistance=self.calculate_euclidean_distance(
+                data["logFD"] / self.max_logFD,
+                data["negativeLog10P"] / self.max_negative_log10_p,
+            ),
+        )
+        row[self.type] = data[self.feature_type_index]
+        return row
+
+    def is_significant_point(self, data):
+        return (
+            data["negativeLog10P"] >= self.minusLog10PSigValue
+            and np.abs(data["logFD"]) >= self.settings.fold_change_threshold
+        )
+
+    def get_significance_class(self, data):
+        """Get the significance class
+
+        Args:
+            data (dict): the row data
+
+        Returns:
+            int: 0 if not significant, 1 if (logFD >= 1), -1 if (logFD <= -1)
+        """
+        if not self.is_significant_point(data):
+            return 0
+        elif data["logFD"] >= 1:
+            return 1
+        elif data["logFD"] <= -1:
+            return -1
+
+    def get_contrast_group_string(self, obj):
+        """Get the contrast group string
+
+        Args:
+            obj (dict): The row data
+
+        Returns:
+            str: The contrast group string
+        """
+        if (
+            obj
+            and obj.get("contrastGroup", None)
+            and obj["contrastGroup"].get("G1", None)
+            and obj["contrastGroup"].get("G2", None)
+        ):
+            return "/".join(
+                [obj["contrastGroup"]["G1"], obj["contrastGroup"]["G2"]]
+            )
+
+    def calculate_euclidean_distance(self, x, y):
+        """Calculate the euclidean distance
+
+        Args:
+            x (float): The x value
+            y (float): The y value
+
+        Returns:
+            float: The euclidean distance
+        """
+        return np.sqrt(x**2 + y**2)
+
+    def _get_max_values(self, data):
+        """For euclidean distance, get the max logFD and negativeLog10P values to normalize the data
+
+        Args:
+            data (list[dict]): The complete set of group analysis result data
+
+        Returns:
+            tuple: The max logFD and negativeLog10P values.
+        """
+        max_logFD = -np.inf
+        max_negative_log10_p = -np.inf
+        for row in data:
+            max_logFD = max(max_logFD, row["logFD"])
+            max_negative_log10_p = max(
+                max_negative_log10_p, row["negativeLog10P"]
+            )
+        return max_logFD, max_negative_log10_p
+
+    def update(
+        self,
+        significance_threshold=None,
+        fold_change_threshold=None,
+        label_by=None,
+    ):
+        """Updates the settings and recalculates the volcano plot
+
+        Args:
+            significance_threshold (float, optional): Cutoff value for the p-value to determine significance
+            fold_change_threshold (float, optional): Cutoff value for the fold change to determine significance
+            label_by (str, optional): Metric to sort result data
+
+        Raises:
+            ValueError: "Invalid label_by value, must be one of ['euclidean', 'fold_change', 'significance']"
+
+        Returns:
+            None
+        """
+        if not significance_threshold:
+            significance_threshold = self.settings.significance_threshold
+        if not fold_change_threshold:
+            fold_change_threshold = self.settings.fold_change_threshold
+        if not label_by:
+            label_by = self.settings.label_by
+
+        self.settings = VolcanoPlotSettings(
+            significance_threshold=significance_threshold,
+            fold_change_threshold=fold_change_threshold,
+            label_by=label_by,
+        )
+        self.minusLog10PSigValue = -np.log10(
+            self.settings.significance_threshold
+        )
+        self.sort_param = VolcanoPlotSettings.get_label_by_map()[
+            self.settings.label_by
+        ]
+        self.volcano_plot = self.build()
+
+    def to_df(self):
+        """Convert the volcano plot data to a DataFrame"""
+        return pd.DataFrame(self.volcano_plot)
+
+    def get_significant_rows(self):
+        """Get the significant proteins
+
+        Returns:
+            List: The list of significant proteins
+        """
+        return [
+            row[self.type] for row in self.volcano_plot if row["significant"]
+        ]