csrlite 0.1.0__tar.gz → 0.2.0__tar.gz

{csrlite-0.1.0 → csrlite-0.2.0}/MANIFEST.in

@@ -18,6 +18,7 @@ prune docs
 prune data
 prune studies
 prune .github
+prune scripts
 exclude .gitignore
 exclude .pyre_configuration
 exclude _quarto.yml

{csrlite-0.1.0/src/csrlite.egg-info → csrlite-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrlite
-Version: 0.1.0
+Version: 0.2.0
 Summary: A hierarchical YAML-based framework for generating Tables, Listings, and Figures in clinical trials
 Author-email: Clinical Biostatistics Team <biostat@example.com>
 License: MIT
@@ -28,17 +28,17 @@ Provides-Extra: plotting
 Requires-Dist: matplotlib>=3.5.0; extra == "plotting"
 Requires-Dist: plotly>=5.0.0; extra == "plotting"
 Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: black>=22.0.0; extra == "dev"
-Requires-Dist: isort>=5.0.0; extra == "dev"
-Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: pytest>=9.0.1; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.8; extra == "dev"
+Requires-Dist: mypy>=1.19.0; extra == "dev"
+Requires-Dist: quarto>=0.1.0; extra == "dev"
+Requires-Dist: pyre-check>=0.9.18; extra == "dev"
 Requires-Dist: jupyter>=1.1.1; extra == "dev"
 Requires-Dist: jupyter-cache>=1.0.1; extra == "dev"
 Requires-Dist: nbformat>=5.10.4; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
-Requires-Dist: pyre-check>=0.9.18; extra == "dev"
 Provides-Extra: all
 Requires-Dist: rtflite; extra == "all"
 Requires-Dist: matplotlib>=3.5.0; extra == "all"

{csrlite-0.1.0 → csrlite-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "csrlite"
-version = "0.1.0"
+version = "0.2.0"
 description = "A hierarchical YAML-based framework for generating Tables, Listings, and Figures in clinical trials"
 authors = [{name = "Clinical Biostatistics Team", email = "biostat@example.com"}]
 license = {text = "MIT"}
@@ -32,17 +32,17 @@ dependencies = [
 rtf = ["rtflite"]
 plotting = ["matplotlib>=3.5.0", "plotly>=5.0.0"]
 dev = [
-    "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
-    "black>=22.0.0",
-    "isort>=5.0.0",
-    "mypy>=1.0.0",
     "pytest>=9.0.1",
+    "black>=22.0.0",
+    "isort>=7.0.0",
+    "ruff>=0.14.8",
+    "mypy>=1.19.0",
+    "quarto>=0.1.0",
+    "pyre-check>=0.9.18",
     "jupyter>=1.1.1",
     "jupyter-cache>=1.0.1",
     "nbformat>=5.10.4",
-    "ruff>=0.1.0",
-    "pyre-check>=0.9.18",
 ]
 all = ["rtflite", "matplotlib>=3.5.0", "plotly>=5.0.0"]
 

{csrlite-0.1.0 → csrlite-0.2.0}/src/csrlite/__init__.py

@@ -1,18 +1,19 @@
-from .ae.ae_listing import (
-    # AE listing functions
+import logging
+import sys
+
+from .ae.ae_listing import (  # AE listing functions
     ae_listing,
     study_plan_to_ae_listing,
 )
-from .ae.ae_specific import (
-    # AE specific functions
+from .ae.ae_specific import (  # AE specific functions
     ae_specific,
     study_plan_to_ae_specific,
 )
-from .ae.ae_summary import (
-    # AE summary functions
+from .ae.ae_summary import (  # AE summary functions
     ae_summary,
     study_plan_to_ae_summary,
 )
+from .common.config import config
 from .common.count import (
     count_subject,
     count_subject_with_observation,
@@ -21,12 +22,19 @@ from .common.parse import (
     StudyPlanParser,
     parse_filter_to_sql,
 )
-from .common.plan import (
-    # Core classes
+from .common.plan import (  # Core classes
     load_plan,
 )
 from .disposition.disposition import study_plan_to_disposition_summary
 
+# Configure logging
+logging.basicConfig(
+    level=config.logging_level,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stdout,
+)
+logger = logging.getLogger("csrlite")
+
 # Main exports for common usage
 __all__ = [
     # Primary user interface

{csrlite-0.1.0 → csrlite-0.2.0}/src/csrlite/ae/ae_listing.py

@@ -71,6 +71,8 @@ def ae_listing_ard(
         parameter_filter=parameter_filter,
     )
 
+    assert observation_to_filter is not None
+
     # Filter observation to include only subjects in filtered population
     observation_filtered = observation_to_filter.filter(
         pl.col(id_var_name).is_in(population_filtered[id_var_name].to_list())

{csrlite-0.1.0 → csrlite-0.2.0}/src/csrlite/ae/ae_specific.py

@@ -24,8 +24,9 @@ from rtflite import RTFDocument
 from ..common.count import count_subject, count_subject_with_observation
 from ..common.parse import StudyPlanParser
 from ..common.plan import StudyPlan
+from ..common.rtf import create_rtf_table_n_pct
 from ..common.utils import apply_common_filters
-from .ae_utils import create_ae_rtf_table, get_ae_parameter_row_labels, get_ae_parameter_title
+from .ae_utils import get_ae_parameter_row_labels, get_ae_parameter_title
 
 
 def ae_specific_ard(
@@ -80,6 +81,8 @@ def ae_specific_ard(
         parameter_filter=parameter_filter,
     )
 
+    assert observation_to_filter is not None
+
     # Filter observation to include only subjects in filtered population
     observation_filtered = observation_to_filter.filter(
         pl.col(id_var_name).is_in(population_filtered[id_var_name].to_list())
@@ -114,7 +117,9 @@ def ae_specific_ard(
 
     # Get population with event indicator
     pop_with_indicator = population_filtered.with_columns(
-        pl.col(id_var_name).is_in(subjects_with_events[id_var_name]).alias("__has_event__")
+        pl.col(id_var_name)
+        .is_in(subjects_with_events[id_var_name].to_list())
+        .alias("__has_event__")
     )
 
     # Count subjects with and without events using count_subject_with_observation
@@ -129,7 +134,7 @@ def ae_specific_ard(
     )
 
     # Extract 'with' counts
-    n_with = event_counts.filter(pl.col("__has_event__")).select(
+    n_with = event_counts.filter(pl.col("__has_event__") == "true").select(
         [
             pl.lit(n_with_label).alias("__index__"),
             pl.col(group_var_name).cast(pl.String).alias("__group__"),
@@ -138,7 +143,7 @@ def ae_specific_ard(
     )
 
     # Extract 'without' counts
-    n_without = event_counts.filter(~pl.col("__has_event__")).select(
+    n_without = event_counts.filter(pl.col("__has_event__") == "false").select(
         [
             pl.lit(n_without_label).alias("__index__"),
             pl.col(group_var_name).cast(pl.String).alias("__group__"),
@@ -254,7 +259,7 @@ def ae_specific_rtf(
     else:
         col_widths = col_rel_width
 
-    return create_ae_rtf_table(
+    return create_rtf_table_n_pct(
         df=df_rtf,
         col_header_1=col_header_1,
         col_header_2=col_header_2,

{csrlite-0.1.0 → csrlite-0.2.0}/src/csrlite/ae/ae_summary.py

@@ -21,8 +21,8 @@ from rtflite import RTFDocument
 from ..common.count import count_subject, count_subject_with_observation
 from ..common.parse import StudyPlanParser
 from ..common.plan import StudyPlan
+from ..common.rtf import create_rtf_table_n_pct
 from ..common.utils import apply_common_filters
-from .ae_utils import create_ae_rtf_table
 
 
 def study_plan_to_ae_summary(
@@ -258,6 +258,8 @@ def ae_summary_ard(
         observation_filter=observation_filter,
     )
 
+    assert observation_to_filter is not None
+
     # Filter observation data to include only subjects in the filtered population
     # Process all variables in the list
     observation_filtered_list = []
@@ -388,7 +390,7 @@ def ae_summary_rtf(
     else:
         col_widths = col_rel_width
 
-    return create_ae_rtf_table(
+    return create_rtf_table_n_pct(
         df=df_rtf,
         col_header_1=col_header_1,
         col_header_2=col_header_2,

csrlite-0.2.0/src/csrlite/ae/ae_utils.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+
+def get_ae_parameter_title(param: Any, prefix: str = "Participants With") -> str:
+    """
+    Extract title from parameter for ae_* title generation.
+
+    Args:
+        param: Parameter object with terms attribute
+        prefix: Prefix for the title (e.g. "Participants With", "Listing of Participants With")
+
+    Returns:
+        Title string for the analysis
+    """
+    default_suffix = "Adverse Events"
+
+    if not param:
+        return f"{prefix} {default_suffix}"
+
+    # Check for terms attribute
+    if hasattr(param, "terms") and param.terms and isinstance(param.terms, dict):
+        terms = param.terms
+
+        # Preprocess to empty strings (avoiding None)
+        before = terms.get("before", "").title()
+        after = terms.get("after", "").title()
+
+        # Build title and clean up extra spaces
+        title = f"{prefix} {before} {default_suffix} {after}"
+        return " ".join(title.split())  # Remove extra spaces
+
+    # Fallback to default
+    return f"{prefix} {default_suffix}"
+
+
+def get_ae_parameter_row_labels(param: Any) -> tuple[str, str]:
+    """
+    Generate n_with and n_without row labels based on parameter terms.
+
+    Returns:
+        Tuple of (n_with_label, n_without_label)
+    """
+    # Default labels
+    default_with = "    with one or more adverse events"
+    default_without = "    with no adverse events"
+
+    if not param or not hasattr(param, "terms") or not param.terms:
+        return (default_with, default_without)
+
+    terms = param.terms
+    before = terms.get("before", "").lower()
+    after = terms.get("after", "").lower()
+
+    # Build dynamic labels with leading indentation
+    with_label = f"with one or more {before} adverse events {after}"
+    without_label = f"with no {before} adverse events {after}"
+
+    # Clean up extra spaces and add back the 4-space indentation
+    with_label = "    " + " ".join(with_label.split())
+    without_label = "    " + " ".join(without_label.split())
+
+    return (with_label, without_label)

csrlite-0.2.0/src/csrlite/common/config.py

@@ -0,0 +1,34 @@
+# pyre-strict
+"""
+Central configuration for csrlite.
+"""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CsrLiteConfig(BaseModel):
+    """
+    Global configuration for csrlite library.
+    """
+
+    # Column Name Defaults
+    id_col: str = Field(default="USUBJID", description="Subject Identifier Column")
+    group_col: Optional[str] = Field(default=None, description="Treatment Group Column")
+
+    # Missing Value Handling
+    missing_str: str = Field(
+        default="__missing__", description="String to represent missing string values"
+    )
+
+    # Logging
+    logging_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO", description="Default logging level"
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+
+# Global configuration instance
+config = CsrLiteConfig()

csrlite-0.2.0/src/csrlite/common/count.py

@@ -0,0 +1,293 @@
+# pyre-strict
+import polars as pl
+
+from .config import config
+
+
+def _to_pop(
+    population: pl.DataFrame,
+    id: str,
+    group: str,
+    total: bool = True,
+    missing_group: str = "error",
+) -> pl.DataFrame:
+    # prepare data
+    pop = population.select(id, group)
+
+    # validate data
+    if pop[id].is_duplicated().any():
+        raise ValueError(f"The '{id}' column in the population DataFrame is not unique.")
+
+    if missing_group == "error" and pop[group].is_null().any():
+        raise ValueError(
+            f"Missing values found in the '{group}' column of the population DataFrame, "
+            "and 'missing_group' is set to 'error'."
+        )
+
+    # Convert group to Enum for consistent categorical ordering
+    u_pop = pop[group].unique().sort().to_list()
+
+    # handle total column
+    if total:
+        pop_total = pop.with_columns(pl.lit("Total").alias(group))
+        pop = pl.concat([pop, pop_total]).with_columns(
+            pl.col(group).cast(pl.Enum(u_pop + ["Total"]))
+        )
+    else:
+        pop = pop.with_columns(pl.col(group).cast(pl.Enum(u_pop)))
+
+    return pop
+
+
+def count_subject(
+    population: pl.DataFrame,
+    id: str,
+    group: str,
+    total: bool = True,
+    missing_group: str = "error",
+) -> pl.DataFrame:
+    """
+    Counts subjects by group and optionally includes a 'Total' column.
+
+    Args:
+        population (pl.DataFrame): DataFrame containing subject population data.
+        id (str): The name of the subject ID column.
+        group (str): The name of the treatment group column.
+        total (bool, optional): If True, adds a 'Total' group. Defaults to True.
+        missing_group (str, optional): How to handle missing values ("error", "ignore").
+
+    Returns:
+        pl.DataFrame: A DataFrame with subject counts ('n_subj_pop') for each group.
+    """
+
+    pop = _to_pop(
+        population=population,
+        id=id,
+        group=group,
+        total=total,
+        missing_group=missing_group,
+    )
+
+    return pop.group_by(group).agg(pl.len().alias("n_subj_pop")).sort(group)
+
+
+def count_summary_data(
+    population: pl.DataFrame,
+    observation: pl.DataFrame,
+    id: str,
+    group: str,
+    variable: str | list[str],
+    total: bool = True,
+    missing_group: str = "error",
+) -> pl.DataFrame:
+    """
+    Generates numeric summary data (counts and percentages) for observations.
+    Does NOT perform string formatting.
+
+    Returns:
+        pl.DataFrame: DataFrame with columns:
+            - [group]: Group column
+            - [variable]: Variable columns
+            - n_obs: Count of observations
+            - n_subj: Count of unique subjects with observation
+            - n_subj_pop: Total subjects in group
+            - pct_subj: Percentage of subjects (0-100)
+    """
+    # Normalize variable to list
+    if isinstance(variable, str):
+        variables = [variable]
+    else:
+        variables = variable
+
+    # prepare data
+    pop = _to_pop(
+        population=population,
+        id=id,
+        group=group,
+        total=total,
+        missing_group=missing_group,
+    )
+
+    # Select all required columns (id + all variables)
+    obs = observation.select(id, *variables).join(pop, on=id, how="left")
+
+    for var in variables:
+        obs = obs.with_columns(pl.col(var).cast(pl.String).fill_null(config.missing_str))
+
+    # Check for IDs in observation that are not in population
+    if not obs[id].is_in(pop[id].to_list()).all():
+        missing_ids = (
+            obs.filter(~pl.col(id).is_in(pop[id].to_list()))
+            .select(id)
+            .unique()
+            .to_series()
+            .to_list()
+        )
+        raise ValueError(
+            f"Some '{id}' values in the observation DataFrame are not present in the population: "
+            f"{missing_ids}"
+        )
+
+    df_pop = count_subject(
+        population=population,
+        id=id,
+        group=group,
+        total=total,
+        missing_group=missing_group,
+    )
+
+    all_levels_df = []
+
+    # Iterate through hierarchies
+    for i in range(1, len(variables) + 1):
+        current_vars = variables[:i]
+
+        # Aggregation
+        df_obs_counts = obs.group_by(group, *current_vars).agg(
+            pl.len().alias("n_obs"), pl.n_unique(id).alias("n_subj")
+        )
+
+        # Cross join for all combinations
+        unique_groups = df_pop.select(group)
+        unique_variables = obs.select(current_vars).unique()
+        all_combinations = unique_groups.join(unique_variables, how="cross")
+
+        # Join back
+        df_level = (
+            all_combinations.join(df_obs_counts, on=[group, *current_vars], how="left")
+            .join(df_pop, on=group, how="left")
+            .with_columns([pl.col("n_obs").fill_null(0), pl.col("n_subj").fill_null(0)])
+        )
+
+        df_level = df_level.with_columns([pl.col(c).cast(pl.String) for c in current_vars])
+
+        # Add missing columns with "__all__"
+        for var in variables:
+            if var not in df_level.columns:
+                df_level = df_level.with_columns(pl.lit("__all__").cast(pl.String).alias(var))
+
+        all_levels_df.append(df_level)
+
+    # Stack
+    df_obs = pl.concat(all_levels_df, how="diagonal")
+
+    # Calculate percentage
+    df_obs = df_obs.with_columns(pct_subj=(pl.col("n_subj") / pl.col("n_subj_pop") * 100))
+
+    return df_obs
+
+
+def format_summary_table(
+    df: pl.DataFrame,
+    group: str,
+    variable: str | list[str],
+    pct_digit: int = 1,
+    max_n_width: int | None = None,
+) -> pl.DataFrame:
+    """
+    Formats numeric summary data into display strings (e.g., "n ( pct)").
+    Adds indentation and sorting.
+    """
+    if isinstance(variable, str):
+        variables = [variable]
+    else:
+        variables = variable
+
+    df_fmt = df.with_columns(
+        pct_subj_fmt=(
+            pl.when(pl.col("pct_subj").is_null() | pl.col("pct_subj").is_nan())
+            .then(0.0)
+            .otherwise(pl.col("pct_subj"))
+            .round(pct_digit, mode="half_away_from_zero")
+            .cast(pl.String)
+        )
+    )
+
+    if max_n_width is None:
+        max_n_width = df_fmt.select(pl.col("n_subj").cast(pl.String).str.len_chars().max()).item()
+
+    max_pct_width = 3 if pct_digit == 0 else 4 + pct_digit
+
+    df_fmt = df_fmt.with_columns(
+        [
+            pl.col("pct_subj_fmt").str.pad_start(max_pct_width, " "),
+            pl.col("n_subj").cast(pl.String).str.pad_start(max_n_width, " ").alias("n_subj_fmt"),
+        ]
+    ).with_columns(
+        n_pct_subj_fmt=pl.concat_str(
+            [pl.col("n_subj_fmt"), pl.lit(" ("), pl.col("pct_subj_fmt"), pl.lit(")")]
+        )
+    )
+
+    # Sorting Logic
+    sort_exprs = [pl.col(group)]
+    for var in variables:
+        # 0 for __all__, 1 for values, 2 for config.missing_str
+        sort_key_col = f"__sort_key_{var}__"
+        df_fmt = df_fmt.with_columns(
+            pl.when(pl.col(var) == "__all__")
+            .then(0)
+            .when(pl.col(var) == config.missing_str)
+            .then(2)
+            .otherwise(1)
+            .alias(sort_key_col)
+        )
+        sort_exprs.append(pl.col(sort_key_col))
+        sort_exprs.append(pl.col(var))
+
+    df_fmt = df_fmt.sort(sort_exprs).select(pl.exclude(r"^__sort_key_.*$"))
+
+    # Indentation logic
+    if len(variables) > 0:
+        var_expr = (
+            pl.when(pl.col(variables[0]) == config.missing_str)
+            .then(pl.lit("Missing"))
+            .otherwise(pl.col(variables[0]))
+        )
+
+        for i in range(1, len(variables)):
+            var_expr = (
+                pl.when(pl.col(variables[i]) == "__all__")
+                .then(var_expr)
+                .when(pl.col(variables[i]) == config.missing_str)
+                .then(pl.lit(" " * 4 * i) + pl.lit("Missing"))
+                .otherwise(pl.lit(" " * 4 * i) + pl.col(variables[i]))
+            )
+        df_fmt = df_fmt.with_columns(var_expr.alias("__variable__"))
+
+    df_fmt = df_fmt.with_row_index(name="__id__", offset=1)
+    return df_fmt
+
+
+def count_subject_with_observation(
+    population: pl.DataFrame,
+    observation: pl.DataFrame,
+    id: str,
+    group: str,
+    variable: str | list[str],
+    total: bool = True,
+    missing_group: str = "error",
+    pct_digit: int = 1,
+    max_n_width: int | None = None,
+) -> pl.DataFrame:
+    """
+    Legacy wrapper for backward compatibility (mostly for tests that rely on the old signature),
+    but now strictly composing the new functions.
+    """
+    df_raw = count_summary_data(
+        population=population,
+        observation=observation,
+        id=id,
+        group=group,
+        variable=variable,
+        total=total,
+        missing_group=missing_group,
+    )
+
+    return format_summary_table(
+        df=df_raw,
+        group=group,
+        variable=variable,
+        pct_digit=pct_digit,
+        max_n_width=max_n_width,
+    )