sai-pg 1.0.0__py3-none-any.whl

sai/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html

sai/__main__.py

@@ -0,0 +1,73 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html
+
+
+import argparse
+from sai.parsers.score_parser import add_score_parser
+from sai.parsers.outlier_parser import add_outlier_parser
+from sai.parsers.plot_parser import add_plot_parser
+
+
+def _set_sigpipe_handler() -> None:
+    """
+    Sets the signal handler for SIGPIPE signals on POSIX systems.
+
+    """
+    import os
+    import signal
+
+    if os.name == "posix":
+        # Set signal handler for SIGPIPE to quietly kill the program.
+        signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+
+def _sai_cli_parser() -> argparse.ArgumentParser:
+    """
+    Initializes and configures the command-line interface parser
+    for sai.
+
+    Returns
+    -------
+    top_parser : argparse.ArgumentParser
+        A configured command-line interface parser.
+    """
+    top_parser = argparse.ArgumentParser()
+    subparsers = top_parser.add_subparsers(dest="subcommand")
+    subparsers.required = True
+
+    add_score_parser(subparsers)
+    add_outlier_parser(subparsers)
+    add_plot_parser(subparsers)
+
+    return top_parser
+
+
+def main(arg_list: list = None) -> None:
+    """
+    Main entry for sai.
+
+    Parameters
+    ----------
+    arg_list : list, optional
+        A list containing arguments for sai. Default: None.
+    """
+    _set_sigpipe_handler()
+    parser = _sai_cli_parser()
+    args = parser.parse_args(arg_list)
+    args.runner(args)

sai/parsers/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html

sai/parsers/argument_validation.py

@@ -0,0 +1,169 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html
+
+
+import argparse
+import os
+import re
+
+
+def positive_int(value: str) -> int:
+    """
+    Validates if the provided string represents a positive integer.
+
+    Parameters
+    ----------
+    value : str
+        The value to validate.
+
+    Returns
+    -------
+    int
+        The validated positive integer.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If the value is not a valid integer or positive integer.
+    """
+    if value is not None:
+        try:
+            value = int(value)
+        except ValueError:
+            raise argparse.ArgumentTypeError(f"{value} is not a valid integer")
+        if value <= 0:
+            raise argparse.ArgumentTypeError(f"{value} is not a positive integer")
+    return value
+
+
+def positive_number(value: str) -> float:
+    """
+    Validates if the provided string represents a positive number.
+
+    Parameters
+    ----------
+    value : str
+        The value to validate.
+
+    Returns
+    -------
+    float
+        The validated positive number.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If the value is not a valid number or positive number.
+    """
+    if value is not None:
+        try:
+            value = float(value)
+        except ValueError:
+            raise argparse.ArgumentTypeError(f"{value} is not a valid number")
+        if value <= 0:
+            raise argparse.ArgumentTypeError(f"{value} is not a positive number")
+    return value
+
+
+def between_zero_and_one(value: str) -> float:
+    """
+    Validates if the provided string represents a number between 0 and 1 (inclusive).
+
+    Parameters
+    ----------
+    value : str
+        The value to validate.
+
+    Returns
+    -------
+    float
+        The validated number between 0 and 1.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If the value is not a valid number or is not between 0 and 1.
+    """
+    if value is not None:
+        try:
+            value = float(value)
+        except ValueError:
+            raise argparse.ArgumentTypeError(f"{value} is not a valid number")
+        if not (0 <= value <= 1):
+            raise argparse.ArgumentTypeError(
+                f"{value} is not between 0 and 1 (inclusive)"
+            )
+    return value
+
+
+def existed_file(value: str) -> str:
+    """
+    Validates if the provided string is a path to an existing file.
+
+    Parameters
+    ----------
+    value : str
+        The path to validate.
+
+    Returns
+    -------
+    str
+        The validated file path.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If the file does not exist.
+    """
+    if value is not None:
+        if not os.path.isfile(value):
+            raise argparse.ArgumentTypeError(f"{value} is not found")
+    return value
+
+
+def validate_stat_type(value: str) -> str:
+    """
+    Validate the input `stat_type`.
+
+    Parameters
+    ----------
+    value : str
+        The statistic type to validate. Must be either:
+        - "U" : Compute the U statistic.
+        - "QXX" : Compute the Q statistic, where "XX" is a one or two-digit integer
+          representing the quantile percentage (e.g., "Q95" for 95th quantile).
+
+    Returns
+    -------
+    str
+        The validated `stat_type`, either "U" or "QXX".
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If the input does not match the expected format ("U" or "QXX").
+    """
+    if re.fullmatch(
+        r"[UQ]\d{2}", value
+    ):  # Matches U or Q followed by exactly two digits
+        return value
+    else:
+        raise argparse.ArgumentTypeError(
+            f"Invalid --stat-type: {value}. Must be 'UXX' or 'QXX' (e.g., 'U05' for x > 0.05, 'Q95' for quantile = 0.95)."
+        )

sai/parsers/outlier_parser.py

@@ -0,0 +1,76 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html
+
+
+import argparse
+from sai.parsers.argument_validation import existed_file
+from sai.parsers.argument_validation import between_zero_and_one
+from sai.sai import outlier
+
+
+def _run_outlier(args: argparse.Namespace) -> None:
+    """
+    Runs the outlier detection process based on command-line arguments.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed command-line arguments containing input score file,
+        output file, quantile threshold, and stat type.
+    """
+    # Call the outlier function with parsed arguments
+    outlier(
+        score_file=args.score,
+        output=args.output,
+        quantile=args.quantile,
+    )
+
+
+def add_outlier_parser(subparsers: argparse.ArgumentParser) -> None:
+    """
+    Initializes and configures the command-line interface parser
+    for the outlier subcommand.
+
+    Parameters
+    ----------
+    subparsers : argparse.ArgumentParser
+        A command-line interface parser to be configured.
+    """
+    parser = subparsers.add_parser(
+        "outlier", help="Detect and output outlier rows based on quantile thresholds."
+    )
+    parser.add_argument(
+        "--score",
+        type=existed_file,
+        required=True,
+        help="Path to the input score file.",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        required=True,
+        help="Path to save the output file.",
+    )
+    parser.add_argument(
+        "--quantile",
+        type=between_zero_and_one,
+        default=0.99,
+        help="Quantile threshold for outlier detection, between 0 and 1. Default: 0.99.",
+    )
+    parser.set_defaults(runner=_run_outlier)

sai/parsers/plot_parser.py

@@ -0,0 +1,152 @@
+# Copyright 2025 Xin Huang
+#
+# GNU General Public License v3.0
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, please see
+#
+#    https://www.gnu.org/licenses/gpl-3.0.en.html
+
+
+import argparse
+from sai.parsers.argument_validation import positive_int
+from sai.parsers.argument_validation import positive_number
+from sai.parsers.argument_validation import existed_file
+from sai.sai import plot
+
+
+def _run_plot(args: argparse.Namespace) -> None:
+    """
+    Runs the plotting process based on command-line arguments.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed command-line arguments containing input files, output file,
+        xlabel, ylabel, title, figsize_x, figsize_y, dpi, alpha,
+        marker_size, marker_color, and marker_style.
+    """
+    plot(
+        u_file=args.u_file,
+        q_file=args.q_file,
+        output=args.output,
+        xlabel=args.xlabel,
+        ylabel=args.ylabel,
+        title=args.title,
+        figsize_x=args.figsize_x,
+        figsize_y=args.figsize_y,
+        dpi=args.dpi,
+        alpha=args.alpha,
+        marker_size=args.marker_size,
+        marker_color=args.marker_color,
+        marker_style=args.marker_style,
+    )
+
+
+def add_plot_parser(subparsers: argparse.ArgumentParser) -> None:
+    """
+    Initializes and configures the command-line interface parser
+    for the plot subcommand.
+
+    Parameters
+    ----------
+    subparsers : argparse.ArgumentParser
+        A command-line interface parser to be configured.
+    """
+    parser = subparsers.add_parser(
+        "plot", help="Generate a scatter plot of U vs Q statistics."
+    )
+    parser.add_argument(
+        "--u-file",
+        dest="u_file",
+        type=existed_file,
+        required=True,
+        help="Path to the U score/outlier file.",
+    )
+    parser.add_argument(
+        "--q-file",
+        dest="q_file",
+        type=existed_file,
+        required=True,
+        help="Path to the Q score/outlier file.",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        required=True,
+        help="Path to save the output plot file. The format depends on the file extension (e.g., `.png`, `.pdf`).",
+    )
+    parser.add_argument(
+        "--xlabel",
+        type=str,
+        default="Q Statistic",
+        help="Label for the X-axis. Default: Q Statistic.",
+    )
+    parser.add_argument(
+        "--ylabel",
+        type=str,
+        default="U Statistic",
+        help="Label for the Y-axis. Default: U Statistic.",
+    )
+    parser.add_argument(
+        "--title",
+        type=str,
+        default="Scatter Plot of U vs Q",
+        help="Title of the plot. Default: Scatter Plot of U vs Q.",
+    )
+    parser.add_argument(
+        "--figsize-x",
+        type=positive_number,
+        default=6,
+        help="Width of the figure (in inches). Default: 6.",
+    )
+    parser.add_argument(
+        "--figsize-y",
+        type=positive_number,
+        default=6,
+        help="Height of the figure (in inches). Default: 6.",
+    )
+    parser.add_argument(
+        "--dpi",
+        type=positive_int,
+        default=300,
+        help="Resolution of the saved plot. Default: 300.",
+    )
+    parser.add_argument(
+        "--alpha",
+        type=positive_number,
+        default=0.6,
+        help="Transparency level of scatter points. Default: 0.6.",
+    )
+    parser.add_argument(
+        "--marker-size",
+        dest="marker_size",
+        type=positive_number,
+        default=20,
+        help="Size of the scatter plot markers. See matplotlib.pyplot.scatter. Default: 20.",
+    )
+    parser.add_argument(
+        "--marker-color",
+        dest="marker_color",
+        type=str,
+        default="blue",
+        help="Color of the markers. See matplotlib.pyplot.scatter. Default: blue.",
+    )
+    parser.add_argument(
+        "--marker-style",
+        dest="marker_style",
+        type=str,
+        default="o",
+        help="Shape of the markers. See matplotlib.pyplot.scatter. Default: o.",
+    )
+    parser.set_defaults(runner=_run_plot)