phactor 0.2.0__py3-none-any.whl

phactor/pandas.py

@@ -0,0 +1,589 @@
+"""DataFrame converters for Phactor cohort analysis results.
+
+Install with::
+
+    pip install 'phactor[pandas]'
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+try:
+    import pandas as pd
+except ImportError:
+    raise ImportError(
+        "Install phactor[pandas] for DataFrame support: "
+        "pip install 'phactor[pandas]'"
+    ) from None
+
+from phactor.cohorts.models import (
+    AnalyzeCohortsPayload,
+    DemographicBreakdown,
+)
+
+__all__ = [
+    "analyses_to_dataframe",
+    "cohort_groups_to_dataframe",
+    "criteria_groups_to_dataframe",
+    "criterion_impacts_to_dataframe",
+    "demographics_to_dataframe",
+    "geographic_groups_to_dataframe",
+    "site_radius_to_dataframe",
+    "site_distance_bands_to_dataframe",
+]
+
+_DEMOGRAPHIC_CATEGORIES = pd.CategoricalDtype(
+    categories=["age", "gender", "race", "geographic"], ordered=False
+)
+
+_ANALYSES_COLS: dict[str, str] = {
+    "analysis_id": "string",
+    "provider_id": "string",
+    "provider_name": "string",
+    "total_patients": "Int64",
+}
+
+_COHORT_GROUPS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "pathway_index": "int64",
+    "total_patients_in_group": "Int64",
+    "evaluated": "bool",
+}
+
+_CRITERIA_GROUPS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "pathway_index": "int64",
+    "group_kind": "string",
+    "group_name": "string",
+    "total_patients_in_group": "Int64",
+    "evaluated": "bool",
+}
+
+_CRITERION_IMPACTS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "pathway_index": "int64",
+    "group_kind": "string",
+    "group_name": "string",
+    "proposition_index": "int64",
+    "proposition_label": "string",
+    "matching_count": "int64",
+    "excluded_count": "int64",
+    "impact_percentage": "float64",
+}
+
+_DEMOGRAPHICS_COLS: dict[str, str] = {
+    "category": "string",
+    "label": "string",
+    "count": "int64",
+    "percentage": "float64",
+}
+
+_GEOGRAPHIC_GROUPS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "label": "string",
+    "count": "int64",
+    "percentage": "float64",
+}
+
+_SITE_RADIUS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "site_name": "string",
+    "latitude": "float64",
+    "longitude": "float64",
+    "radius_miles": "int64",
+    "count": "int64",
+    "percentage": "float64",
+}
+
+_SITE_DISTANCE_BANDS_COLS: dict[str, str] = {
+    "provider_id": "string",
+    "provider_name": "string",
+    "site_name": "string",
+    "latitude": "float64",
+    "longitude": "float64",
+    "band_label": "string",
+    "min_miles": "int64",
+    "max_miles": "Int64",
+    "count": "int64",
+    "percentage": "float64",
+}
+
+
+def _empty(columns: dict[str, str]) -> pd.DataFrame:
+    """Return an empty DataFrame with the given column names and dtypes."""
+    return pd.DataFrame({col: pd.Series(dtype=dt) for col, dt in columns.items()})
+
+
+def _to_df(rows: list[dict[str, object]], columns: dict[str, str]) -> pd.DataFrame:
+    """Build a DataFrame from rows with explicit dtypes, or an empty schema."""
+    if not rows:
+        return _empty(columns)
+    df: pd.DataFrame = pd.DataFrame(rows).astype(columns)
+    return df
+
+
+def analyses_to_dataframe(payload: AnalyzeCohortsPayload) -> pd.DataFrame:
+    """Convert an ``AnalyzeCohortsPayload`` to a flat DataFrame of provider analyses.
+
+    Each row represents one :class:`~phactor.cohorts.models.ProviderCohortAnalysis`.
+
+    Columns
+    -------
+    analysis_id : string
+        Unique identifier for the analysis.
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    total_patients : Int64
+        Total number of patients in the provider's dataset. Null means the
+        provider request was not evaluated.
+    """
+    rows: list[dict[str, object]] = [
+        {
+            "analysis_id": analysis.id,
+            "provider_id": analysis.provider.id,
+            "provider_name": analysis.provider.name,
+            "total_patients": analysis.total_patients,
+        }
+        for analysis in payload.analyses
+    ]
+    return _to_df(rows, _ANALYSES_COLS)
+
+
+def cohort_groups_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+) -> pd.DataFrame:
+    """Convert pathway-level cohort group results to a flat DataFrame.
+
+    Each row represents one complete cohort pathway. Its
+    ``total_patients_in_group`` value is the net result after combining all
+    inclusion groups and subtracting all exclusion groups.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    pathway_index : int64
+        Zero-based position of the complete pathway in the request.
+    total_patients_in_group : Int64
+        Net matching patient count. Null means the pathway was not evaluated.
+    evaluated : bool
+        Whether the pathway was evaluated.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for pathway_index, pathway in enumerate(analysis.cohort_groups):
+            rows.append(
+                {
+                    "provider_id": analysis.provider.id,
+                    "provider_name": analysis.provider.name,
+                    "pathway_index": pathway_index,
+                    "total_patients_in_group": pathway.total_patients_in_group,
+                    "evaluated": pathway.evaluated,
+                }
+            )
+    return _to_df(rows, _COHORT_GROUPS_COLS)
+
+
+def criteria_groups_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+) -> pd.DataFrame:
+    """Convert nested inclusion and exclusion criteria groups to a flat DataFrame.
+
+    Each row represents one named criteria group inside a complete cohort
+    pathway. ``group_kind`` preserves whether that group includes or excludes
+    patients.
+
+    Criteria-group counts are diagnostic component counts and are not additive:
+    inclusion groups can overlap, and exclusion counts are subtracted from the
+    pathway result. Use :func:`cohort_groups_to_dataframe` for net pathway counts.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    pathway_index : int64
+        Zero-based position of the complete pathway in the request.
+    group_kind : string
+        ``inclusion`` or ``exclusion``.
+    group_name : string
+        Name of the nested criteria group.
+    total_patients_in_group : Int64
+        Matching patient count. Null means the group was not evaluated.
+    evaluated : bool
+        Whether the criteria group was evaluated.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for pathway_index, pathway in enumerate(analysis.cohort_groups):
+            for group_kind, criteria_groups in (
+                ("inclusion", pathway.inclusion_groups),
+                ("exclusion", pathway.exclusion_groups),
+            ):
+                rows.extend(
+                    {
+                        "provider_id": analysis.provider.id,
+                        "provider_name": analysis.provider.name,
+                        "pathway_index": pathway_index,
+                        "group_kind": group_kind,
+                        "group_name": criteria_group.name,
+                        "total_patients_in_group": criteria_group.total_patients_in_group,
+                        "evaluated": criteria_group.evaluated,
+                    }
+                    for criteria_group in criteria_groups
+                )
+    return _to_df(rows, _CRITERIA_GROUPS_COLS)
+
+
+def criterion_impacts_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+    group_name: str | None = None,
+) -> pd.DataFrame:
+    """Convert criterion impact results to a flat DataFrame.
+
+    Each row represents one :class:`~phactor.cohorts.models.CriterionImpact`
+    nested within a cohort group, across all (or a filtered subset of) analyses.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+    group_name:
+        When set, only rows belonging to this cohort group name are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    group_name : string
+        Name of the cohort group containing this criterion.
+    proposition_index : int64
+        Zero-based index of the criterion proposition.
+    proposition_label : string
+        Human-readable label for the criterion proposition.
+    matching_count : int64
+        Number of patients matching this criterion.
+    excluded_count : int64
+        Number of patients excluded by this criterion.
+    impact_percentage : float64
+        Percentage impact of this criterion on the cohort.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for pathway_index, pathway in enumerate(analysis.cohort_groups):
+            for group_kind, criteria_groups in (
+                ("inclusion", pathway.inclusion_groups),
+                ("exclusion", pathway.exclusion_groups),
+            ):
+                for group in criteria_groups:
+                    if group_name is not None and group.name != group_name:
+                        continue
+                    for impact in group.criterion_impacts or []:
+                        rows.append(
+                            {
+                                "provider_id": analysis.provider.id,
+                                "provider_name": analysis.provider.name,
+                                "pathway_index": pathway_index,
+                                "group_kind": group_kind,
+                                "group_name": group.name,
+                                "proposition_index": impact.proposition_index,
+                                "proposition_label": impact.proposition_label,
+                                "matching_count": impact.matching_count,
+                                "excluded_count": impact.excluded_count,
+                                "impact_percentage": impact.impact_percentage,
+                            }
+                        )
+    return _to_df(rows, _CRITERION_IMPACTS_COLS)
+
+
+def demographics_to_dataframe(
+    breakdown: DemographicBreakdown,
+    *,
+    category: str | None = None,
+) -> pd.DataFrame:
+    """Convert a ``DemographicBreakdown`` to a flat DataFrame.
+
+    Works for both per-group breakdowns (``CohortGroupResult.demographic_breakdown``)
+    and combined breakdowns (``ProviderCohortAnalysis.combined_demographic_breakdown``).
+
+    Parameters
+    ----------
+    breakdown:
+        A single demographic breakdown object.
+    category:
+        When set, only rows for this demographic category are included.
+        Must be one of ``"age"``, ``"gender"``, ``"race"``, ``"geographic"``.
+
+    Columns
+    -------
+    category : CategoricalDtype(["age", "gender", "race", "geographic"])
+        The demographic category.
+    label : string
+        The demographic label (e.g. age range ``"18-24"``, gender ``"Male"``).
+    count : int64
+        Number of patients in this demographic bucket.
+    percentage : float64
+        Percentage of patients in this demographic bucket.
+    """
+    rows: list[dict[str, object]] = []
+
+    if category is None or category == "age":
+        for bucket in breakdown.age_distribution or []:
+            rows.append(
+                {
+                    "category": "age",
+                    "label": f"{bucket.range_from}-{bucket.range_to}",
+                    "count": bucket.count,
+                    "percentage": bucket.percentage,
+                }
+            )
+
+    if category is None or category == "gender":
+        for entry in breakdown.gender_distribution or []:
+            rows.append(
+                {
+                    "category": "gender",
+                    "label": entry.label,
+                    "count": entry.count,
+                    "percentage": entry.percentage,
+                }
+            )
+
+    if category is None or category == "race":
+        for entry in breakdown.race_distribution or []:
+            rows.append(
+                {
+                    "category": "race",
+                    "label": entry.label,
+                    "count": entry.count,
+                    "percentage": entry.percentage,
+                }
+            )
+
+    if category is None or category == "geographic":
+        for entry in breakdown.geographic_distribution or []:
+            rows.append(
+                {
+                    "category": "geographic",
+                    "label": entry.label,
+                    "count": entry.count,
+                    "percentage": entry.percentage,
+                }
+            )
+
+    df: pd.DataFrame = (
+        _empty(_DEMOGRAPHICS_COLS) if not rows else pd.DataFrame(rows).astype(_DEMOGRAPHICS_COLS)
+    )
+    df["category"] = df["category"].astype(_DEMOGRAPHIC_CATEGORIES)
+    return df
+
+
+def geographic_groups_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+) -> pd.DataFrame:
+    """Convert geographic group results to a flat DataFrame.
+
+    Each row represents one :class:`~phactor.cohorts.models.GeographicGroup`
+    across all (or a filtered subset of) provider analyses.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    label : string
+        Geographic region label.
+    count : int64
+        Number of patients in this geographic region.
+    percentage : float64
+        Percentage of patients in this geographic region.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for geo_group in analysis.geographic_groups or []:
+            rows.append(
+                {
+                    "provider_id": analysis.provider.id,
+                    "provider_name": analysis.provider.name,
+                    "label": geo_group.label,
+                    "count": geo_group.count,
+                    "percentage": geo_group.percentage,
+                }
+            )
+    return _to_df(rows, _GEOGRAPHIC_GROUPS_COLS)
+
+
+def site_radius_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+) -> pd.DataFrame:
+    """Convert site radius results to a flat DataFrame.
+
+    Each row represents one :class:`~phactor.cohorts.models.SiteRadiusResult`
+    across all (or a filtered subset of) provider analyses.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    site_name : string
+        Name of the clinical site.
+    latitude : float64
+        Latitude coordinate of the site.
+    longitude : float64
+        Longitude coordinate of the site.
+    radius_miles : int64
+        Search radius in miles around the site.
+    count : int64
+        Number of patients within the radius.
+    percentage : float64
+        Percentage of patients within the radius.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for site in analysis.site_radius_results or []:
+            rows.append(
+                {
+                    "provider_id": analysis.provider.id,
+                    "provider_name": analysis.provider.name,
+                    "site_name": site.site_name,
+                    "latitude": site.latitude,
+                    "longitude": site.longitude,
+                    "radius_miles": site.radius_miles,
+                    "count": site.count,
+                    "percentage": site.percentage,
+                }
+            )
+    return _to_df(rows, _SITE_RADIUS_COLS)
+
+
+def site_distance_bands_to_dataframe(
+    payload: AnalyzeCohortsPayload,
+    *,
+    provider_id: str | None = None,
+) -> pd.DataFrame:
+    """Convert site distance band results to a flat DataFrame.
+
+    Each row represents one :class:`~phactor.cohorts.models.DistanceBand` within
+    a :class:`~phactor.cohorts.models.SiteDistanceBandResult`, across all (or a
+    filtered subset of) provider analyses.
+
+    Parameters
+    ----------
+    payload:
+        The full cohort analysis payload.
+    provider_id:
+        When set, only rows belonging to this provider are included.
+
+    Columns
+    -------
+    provider_id : string
+        Unique identifier for the provider.
+    provider_name : string
+        Human-readable provider name.
+    site_name : string
+        Name of the clinical site.
+    latitude : float64
+        Latitude coordinate of the site.
+    longitude : float64
+        Longitude coordinate of the site.
+    band_label : string
+        Human-readable label for the distance band (e.g. ``"0-25 miles"``).
+    min_miles : int64
+        Lower bound of the distance band in miles (inclusive).
+    max_miles : Int64
+        Upper bound of the distance band in miles (inclusive). Nullable —
+        ``pd.NA`` for open-ended bands such as ``"100+ miles"``.
+    count : int64
+        Number of patients within this distance band.
+    percentage : float64
+        Percentage of patients within this distance band.
+    """
+    rows: list[dict[str, object]] = []
+    for analysis in payload.analyses:
+        if provider_id is not None and analysis.provider.id != provider_id:
+            continue
+        for site_result in analysis.site_distance_band_results or []:
+            for band in site_result.bands:
+                rows.append(
+                    {
+                        "provider_id": analysis.provider.id,
+                        "provider_name": analysis.provider.name,
+                        "site_name": site_result.site_name,
+                        "latitude": site_result.latitude,
+                        "longitude": site_result.longitude,
+                        "band_label": band.label,
+                        "min_miles": band.min_miles,
+                        "max_miles": band.max_miles,
+                        "count": band.count,
+                        "percentage": band.percentage,
+                    }
+                )
+    return _to_df(rows, _SITE_DISTANCE_BANDS_COLS)