equity-aggregator 0.1.7__tar.gz → 0.1.8__tar.gz

{equity_aggregator-0.1.7 → equity_aggregator-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: equity-aggregator
-Version: 0.1.7
+Version: 0.1.8
 Summary: Financial equity data aggregation toolkit
 Project-URL: Homepage, https://github.com/gregorykelleher/equity-aggregator
 Project-URL: Repository, https://github.com/gregorykelleher/equity-aggregator

equity_aggregator-0.1.8/examples/data_integrity_analysis/__init__.py

@@ -0,0 +1,24 @@
+# data_integrity_analysis/__init__.py
+
+"""
+Data Integrity Analysis package for Equity Aggregator.
+
+This package provides comprehensive data quality analysis for canonical equity
+records, examining financial outliers, temporal anomalies, data consistency,
+identifier quality, and completeness metrics.
+
+Usage:
+    python -m examples.data_integrity_analysis
+"""
+
+from .main import main, run_analysis
+from .models import AnalysisSettings, Finding, SectionReport, default_settings
+
+__all__ = [
+    "AnalysisSettings",
+    "Finding",
+    "SectionReport",
+    "default_settings",
+    "main",
+    "run_analysis",
+]

equity_aggregator-0.1.8/examples/data_integrity_analysis/__main__.py

@@ -0,0 +1,6 @@
+# data_integrity_analysis/__main__.py
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

equity_aggregator-0.1.7/examples/data_integrity_analysis.py → equity_aggregator-0.1.8/examples/data_integrity_analysis/analyzers.py

@@ -1,295 +1,27 @@
-# examples/data_integrity_analysis.py
+# data_integrity_analysis/analyzers.py
 
 from collections import Counter, defaultdict
-from collections.abc import Iterable, Sequence
-from dataclasses import dataclass
+from collections.abc import Sequence
 from decimal import Decimal
 from itertools import islice
 from statistics import mean, median, stdev
 
 from equity_aggregator import CanonicalEquity
-from equity_aggregator.storage import load_canonical_equities
 
-
-@dataclass(frozen=True)
-class AnalysisSettings:
-    """Configuration values controlling analysis thresholds."""
-
-    min_sample_size: int = 10
-    mega_cap_threshold: int = 200_000_000_000
-    micro_cap_threshold: int = 300_000_000
-    rare_currency_count: int = 10
-    round_price_threshold: float = 30.0
-    identifier_gap_alert: float = 50.0
-    symbol_length_limit: int = 5
-    duplicate_group_limit: int = 3
-    finding_sample_limit: int = 5
-    dividend_yield_alert: Decimal = Decimal("15")
-    profit_margin_high: Decimal = Decimal("100")
-    profit_margin_low: Decimal = Decimal("-100")
-    price_tolerance: Decimal = Decimal("1.1")
-    price_to_min_factor: Decimal = Decimal("0.9")
-    isin_length: int = 12
-    cusip_length: int = 9
-    lei_length: int = 20
-    penny_stock_threshold: Decimal = Decimal("0.01")
-
-
-def default_settings() -> AnalysisSettings:
-    """
-    Return default analysis thresholds.
-
-    Returns:
-        Default configuration values.
-    """
-    return AnalysisSettings()
-
-
-@dataclass(frozen=True)
-class Finding:
-    """Captures a single insight or anomaly."""
-
-    message: str
-    highlights: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class SectionReport:
-    """Structured results for an analysis section."""
-
-    title: str
-    findings: tuple[Finding, ...]
-
-
-def limit_items(items: Iterable[str], limit: int) -> tuple[str, ...]:
-    """
-    Limit items to specified maximum count.
-
-    Args:
-        items: Items to limit.
-        limit: Maximum count.
-
-    Returns:
-        Limited items.
-    """
-    return tuple(islice(items, limit))
-
-
-def format_equity(eq: CanonicalEquity) -> str:
-    """
-    Format equity as 'Name (SYMBOL)'.
-
-    Args:
-        eq: Canonical equity to format.
-
-    Returns:
-        Formatted equity string.
-    """
-    name = (eq.identity.name or "Unknown")[:40]
-    symbol = eq.identity.symbol or "N/A"
-    return f"{name} ({symbol})"
-
-
-def format_equity_with_figi(eq: CanonicalEquity) -> str:
-    """
-    Format equity as 'Name (SYMBOL) [FIGI]'.
-
-    Args:
-        eq: Canonical equity to format.
-
-    Returns:
-        Formatted equity string with FIGI.
-    """
-    name = (eq.identity.name or "Unknown")[:40]
-    symbol = eq.identity.symbol or "N/A"
-    figi = eq.identity.share_class_figi or "No FIGI"
-    return f"{name} ({symbol}) [{figi}]"
-
-
-def format_currency(value: Decimal | float) -> str:
-    """
-    Format value as currency with thousands separators.
-
-    Args:
-        value: Monetary amount.
-
-    Returns:
-        Formatted currency string.
-    """
-    number = float(value)
-    return f"${int(number):,}" if number.is_integer() else f"${number:,.2f}"
-
-
-def format_percentage(value: float) -> str:
-    """
-    Format value as percentage with one decimal place.
-
-    Args:
-        value: Percentage value.
-
-    Returns:
-        Formatted percentage string.
-    """
-    return f"{value:.1f}%"
-
-
-def format_coverage_table(items: list[tuple[str, int, int]]) -> tuple[str, ...]:
-    """
-    Format coverage data as aligned table rows.
-
-    Args:
-        items: List of (label, count, total) tuples.
-
-    Returns:
-        Formatted table rows.
-    """
-    if not items:
-        return ()
-
-    max_label = max(len(label) for label, _, _ in items)
-    max_count = max(len(f"{count:,}") for _, count, _ in items)
-    max_total = max(len(f"{total:,}") for _, _, total in items)
-
-    return tuple(
-        _format_coverage_row(label, count, total, (max_label, max_count, max_total))
-        for label, count, total in items
-    )
-
-
-def _format_coverage_row(
-    label: str,
-    count: int,
-    total: int,
-    widths: tuple[int, int, int],
-) -> str:
-    """
-    Format a single coverage table row.
-
-    Args:
-        label: Field label.
-        count: Number of populated instances.
-        total: Total number of instances.
-        widths: Column widths (label, count, total).
-
-    Returns:
-        Formatted row string.
-    """
-    max_label, max_count, max_total = widths
-    percentage = (count / total * 100) if total > 0 else 0.0
-    count_str = f"{count:,}".rjust(max_count)
-    total_str = f"{total:,}".rjust(max_total)
-    return (
-        f"{label.ljust(max_label)}  {count_str} / {total_str}  "
-        f"({format_percentage(percentage)})"
-    )
-
-
-def describe_price_vs_max(eq: CanonicalEquity) -> str:
-    """
-    Describe price relative to 52-week maximum.
-
-    Args:
-        eq: Canonical equity.
-
-    Returns:
-        Formatted comparison string.
-    """
-    price = eq.financials.last_price
-    maximum = eq.financials.fifty_two_week_max
-    return f"{format_equity(eq)} -> price {price} vs max {maximum}"
-
-
-def describe_price_vs_min(eq: CanonicalEquity) -> str:
-    """
-    Describe price relative to 52-week minimum.
-
-    Args:
-        eq: Canonical equity.
-
-    Returns:
-        Formatted comparison string.
-    """
-    price = eq.financials.last_price
-    minimum = eq.financials.fifty_two_week_min
-    return f"{format_equity(eq)} -> price {price} vs min {minimum}"
-
-
-def describe_range_bounds(eq: CanonicalEquity) -> str:
-    """
-    Describe 52-week price range.
-
-    Args:
-        eq: Canonical equity.
-
-    Returns:
-        Formatted range string.
-    """
-    minimum = eq.financials.fifty_two_week_min
-    maximum = eq.financials.fifty_two_week_max
-    return f"{format_equity(eq)} -> min {minimum}, max {maximum}"
-
-
-def describe_cap_gap(eq: CanonicalEquity) -> str:
-    """
-    Describe market cap without corresponding price.
-
-    Args:
-        eq: Canonical equity.
-
-    Returns:
-        Formatted gap description.
-    """
-    cap_value = eq.financials.market_cap
-    return f"{format_equity(eq)} -> cap {format_currency(cap_value)}, price missing"
-
-
-def score_equity_completeness(equity: CanonicalEquity) -> int:
-    """
-    Calculate completeness score based on populated fields.
-
-    Args:
-        equity: Canonical equity to score.
-
-    Returns:
-        Completeness score (higher is more complete).
-    """
-    identity_score = sum(
-        1
-        for field in (
-            equity.identity.name,
-            equity.identity.isin,
-            equity.identity.cusip,
-            equity.identity.cik,
-            equity.identity.lei,
-        )
-        if field
-    )
-    financial_score = sum(
-        1
-        for field in (
-            equity.financials.sector,
-            equity.financials.last_price,
-            equity.financials.trailing_pe,
-            equity.financials.dividend_yield,
-        )
-        if field
-    )
-    market_cap_bonus = 2 if equity.financials.market_cap else 0
-    return identity_score + financial_score + market_cap_bonus
-
-
-def print_separator(title: str) -> None:
-    """
-    Print formatted section separator.
-
-    Args:
-        title: Section heading.
-    """
-    print()
-    print()
-    print("─" * 80)
-    print(f"  {title.upper()}")
-    print("─" * 80)
+from .formatters import (
+    describe_cap_gap,
+    describe_price_vs_max,
+    describe_price_vs_min,
+    describe_range_bounds,
+    format_coverage_table,
+    format_currency,
+    format_equity,
+    format_equity_with_figi,
+    format_percentage,
+    limit_items,
+    score_equity_completeness,
+)
+from .models import AnalysisSettings, Finding, SectionReport
 
 
 def build_dataset_overview(equities: Sequence[CanonicalEquity]) -> SectionReport:
@@ -1422,9 +1154,7 @@ def detect_cap_without_price(
 def detect_missing_price_and_cap(
     equities: Sequence[CanonicalEquity],
 ) -> tuple[Finding, ...]:
-    """
-    Report equities missing both price and market cap.
-    """
+    """Report equities missing both price and market cap."""
 
     missing = [
         eq
@@ -1509,13 +1239,10 @@ def analyse_cross_field_logic(
     )
     return SectionReport("Cross-field Logic Consistency", findings)
 
-
 def identity_completeness(
     equities: Sequence[CanonicalEquity],
 ) -> tuple[Finding, ...]:
-    """
-    Summarise completion of core identity fields.
-    """
+    """Summarise completion of core identity fields."""
 
     total = len(equities)
     if total == 0:
@@ -1693,120 +1420,3 @@ def analyse_currency_and_geography(
 
     findings = currency_distribution(equities) + geography_proxies(equities)
     return SectionReport("Currency and Geography", findings)
-
-
-def run_analysis(
-    equities: Sequence[CanonicalEquity],
-    settings: AnalysisSettings | None = None,
-) -> tuple[SectionReport, ...]:
-    """
-    Execute complete data integrity analysis suite.
-
-    Args:
-        equities: Equities to analyse.
-        settings: Analysis thresholds (defaults to standard settings).
-
-    Returns:
-        Ordered section reports with findings.
-    """
-    active_settings = settings or default_settings()
-
-    return (
-        build_dataset_overview(equities),
-        analyse_financial_outliers(equities, active_settings),
-        detect_temporal_anomalies(equities, active_settings),
-        detect_extreme_financial_values(equities, active_settings),
-        analyse_data_consistency(equities, active_settings),
-        analyse_identifier_quality(equities, active_settings),
-        analyse_cross_field_logic(equities, active_settings),
-        analyse_data_quality(equities, active_settings),
-        analyse_currency_and_geography(equities),
-    )
-
-
-def render_finding(finding: Finding, *, add_spacing: bool) -> None:
-    """
-    Render finding with message and highlights.
-
-    Args:
-        finding: Finding to render.
-        add_spacing: Whether to add spacing before finding.
-    """
-    if add_spacing:
-        print()
-    print(f"\n  • {finding.message}")
-    if finding.highlights:
-        print()
-        for highlight in finding.highlights:
-            print(f"      {highlight}")
-
-
-def render_reports(reports: Sequence[SectionReport]) -> None:
-    """
-    Render analysis reports to stdout.
-
-    Args:
-        reports: Section reports to render.
-    """
-    for report in reports:
-        print_separator(report.title)
-        if not report.findings:
-            print("\n  ✓ No notable findings in this section.\n")
-            continue
-        for idx, finding in enumerate(report.findings, 1):
-            render_finding(finding, add_spacing=(idx > 1))
-
-
-def print_summary_header(total_equities: int, reports: Sequence[SectionReport]) -> None:
-    """
-    Print analysis summary header.
-
-    Args:
-        total_equities: Total number of equities analysed.
-        reports: Section reports for summary statistics.
-    """
-    total_findings = sum(len(report.findings) for report in reports)
-    sections_with_findings = sum(1 for report in reports if report.findings)
-
-    print("\n" + "=" * 80)
-    print("  EQUITY AGGREGATOR DATA INTEGRITY ANALYSIS")
-    print("=" * 80)
-    print(f"\n  Dataset Size:          {total_equities:,} equities")
-    print(f"  Sections Analysed:     {len(reports)}")
-    print(f"  Sections with Issues:  {sections_with_findings}")
-    print(f"  Total Findings:        {total_findings}")
-    print()
-
-
-def main() -> None:
-    """
-    Run data integrity analysis on stored canonical equities.
-
-    Loads equities from local database and generates comprehensive
-    analysis report covering multiple data quality dimensions.
-    """
-    try:
-        equities = load_canonical_equities(refresh_fn=None)
-    except Exception as exc:  # pragma: no cover - defensive for CLI usage
-        print(f"\n✗ Failed to load canonical equities: {exc}")
-        print(
-            "  Ensure the local database exists at"
-            " ~/Library/Application Support/equity-aggregator/data_store.db\n",
-        )
-        return
-
-    if not equities:
-        print("\n✗ No canonical equities were loaded; aborting analysis.")
-        print("  Run 'equity-aggregator download' to populate the data store.\n")
-        return
-
-    reports = run_analysis(equities, default_settings())
-    print_summary_header(len(equities), reports)
-    render_reports(reports)
-    print("\n" + "=" * 80)
-    print("  Analysis complete.")
-    print("=" * 80 + "\n")
-
-
-if __name__ == "__main__":
-    main()