scientific-computing-system 1.6.2__py3-none-any.whl

cds/data_analysis/dataset.py

@@ -0,0 +1,122 @@
+"""Pure Python DataFrame-like structure for structured data analysis."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeAlias
+
+# A cell value in a DataSet row. Tabular data here is expected to be scalar
+# primitives — numbers, strings, booleans, or null — rather than nested
+# containers, which keeps column extraction and aggregation type-safe.
+Scalar: TypeAlias = int | float | str | bool | None
+
+# A single row maps column name -> cell value.
+Row: TypeAlias = dict[str, Scalar]
+
+
+class DataSet:
+    """A lightweight, pure Python 'DataFrame' for structured data.
+
+    Data is stored internally as a list of dictionaries where keys are column names.
+    """
+
+    def __init__(self, data: list[Row]):
+        """Store ``data`` and derive column names from the first row's keys."""
+        self.data = data
+        self._columns = list(data[0].keys()) if data else []
+
+    @property
+    def columns(self) -> list[str]:
+        """Return the list of column names."""
+        return self._columns
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Return (rows, columns) tuple."""
+        return len(self.data), len(self._columns)
+
+    def __len__(self) -> int:
+        """Return the number of rows."""
+        return len(self.data)
+
+    def __getitem__(self, idx: int) -> Row:
+        """Return the row at integer index ``idx``."""
+        return self.data[idx]
+
+    def column(self, name: str) -> list[Scalar]:
+        """Extract a single column as a list."""
+        if name not in self._columns:
+            raise ValueError(f"Column '{name}' not found. Available: {self._columns}")
+        return [row[name] for row in self.data]
+
+    def filter(self, predicate: Callable[[Row], bool]) -> DataSet:
+        """Filter the dataset based on a predicate function."""
+        filtered_data = [row for row in self.data if predicate(row)]
+        return DataSet(filtered_data)
+
+    def head(self, n: int = 5) -> DataSet:
+        """Return the first n rows."""
+        return DataSet(self.data[:n])
+
+    def tail(self, n: int = 5) -> DataSet:
+        """Return the last n rows."""
+        return DataSet(self.data[-n:])
+
+    def select(self, *names: str) -> DataSet:
+        """Select a subset of columns."""
+        for name in names:
+            if name not in self._columns:
+                raise ValueError(f"Column '{name}' not found.")
+
+        new_data = [{name: row[name] for name in names} for row in self.data]
+        return DataSet(new_data)
+
+    def group_by(self, column_name: str) -> DataGroup:
+        """Group data by a specific column for aggregation."""
+        if column_name not in self._columns:
+            raise ValueError(f"Column '{column_name}' not found.")
+
+        groups: dict[Scalar, list[Row]] = {}
+        for row in self.data:
+            key = row[column_name]
+            if key not in groups:
+                groups[key] = []
+            groups[key].append(row)
+
+        return DataGroup(groups, column_name)
+
+    def to_list(self) -> list[Row]:
+        """Export data as a list of dictionaries."""
+        return [row.copy() for row in self.data]
+
+    def __repr__(self) -> str:
+        """Return a compact ``DataSet(rows=..., cols=...)`` summary."""
+        if not self.data:
+            return "DataSet(empty)"
+        return f"DataSet(rows={len(self.data)}, cols={len(self._columns)})"
+
+
+class DataGroup:
+    """Helper class for grouped data aggregations."""
+
+    def __init__(self, groups: dict[Scalar, list[Row]], group_col: str):
+        """Store the grouped rows and the name of the grouping column."""
+        self.groups = groups
+        self.group_col = group_col
+
+    def mean(self, numeric_col: str) -> dict[Scalar, float]:
+        """Calculate the mean of a numeric column for each group."""
+        result: dict[Scalar, float] = {}
+        for key, rows in self.groups.items():
+            values: list[float] = [
+                float(v) for row in rows if isinstance((v := row.get(numeric_col)), (int, float))
+            ]
+            if values:
+                result[key] = sum(values) / len(values)
+            else:
+                result[key] = 0.0
+        return result
+
+    def count(self) -> dict[Scalar, int]:
+        """Count the number of rows in each group."""
+        return {key: len(rows) for key, rows in self.groups.items()}

cds/data_analysis/loader.py

@@ -0,0 +1,75 @@
+"""Simple CSV loader — no pandas dependency."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class DataTable:
+    """In-memory tabular data: a header row plus a list of string rows."""
+
+    headers: list[str] = field(default_factory=list)
+    rows: list[list[str]] = field(default_factory=list)
+
+    @property
+    def n_rows(self) -> int:
+        """Number of data rows (excluding the header)."""
+        return len(self.rows)
+
+    @property
+    def n_cols(self) -> int:
+        """Number of columns (i.e. number of header entries)."""
+        return len(self.headers)
+
+    def column(self, name: str) -> list[str]:
+        """Return all values in the column identified by `name`."""
+        idx = self.headers.index(name)
+        return [row[idx] for row in self.rows]
+
+    def column_as_float(self, name: str) -> list[float]:
+        """Return a column as floats; raises ValueError if a cell is non-numeric."""
+        return [float(v) for v in self.column(name)]
+
+    def head(self, n: int = 5) -> list[list[str]]:
+        """Return the first `n` rows (default 5) for quick inspection."""
+        return self.rows[:n]
+
+    def describe(self) -> dict[str, dict[str, float]]:
+        """Quick summary stats for numeric columns."""
+        from cds.stats.descriptive import mean, median, stdev
+
+        result: dict[str, dict[str, float]] = {}
+        for h in self.headers:
+            try:
+                vals = self.column_as_float(h)
+                result[h] = {
+                    "count": len(vals),
+                    "mean": mean(vals),
+                    "std": stdev(vals),
+                    "min": min(vals),
+                    "median": median(vals),
+                    "max": max(vals),
+                }
+            except (ValueError, TypeError):
+                # Non-numeric column — skip aggregation, keep prior result.
+                pass
+        return result
+
+
+def load_csv(path: str | Path) -> DataTable:
+    """Load a CSV file into a DataTable.
+
+    The first row is treated as headers; remaining rows are stored as strings.
+    Raises FileNotFoundError if `path` does not exist.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"no such file: {p}")
+    with open(p, newline="") as f:
+        reader = csv.reader(f)
+        headers = next(reader)
+        rows = list(reader)
+    return DataTable(headers=headers, rows=rows)

cds/data_analysis/pandas_io.py

@@ -0,0 +1,108 @@
+"""Pandas interoperability bridge for :class:`cds.data_analysis.DataSet`.
+
+This module is **optional**: pandas is imported lazily, so the core package
+remains zero-dependency. Install the extra with ``pip install ".[pandas]"``
+(or ``[all]``). Importing this module without pandas installed raises a clear
+``ImportError`` with install guidance.
+
+The bridge converts between CDS's pure-Python :class:`DataSet` (a list of
+row dicts) and a pandas ``DataFrame``, letting users who already live in the
+pandas ecosystem move data in both directions without rewriting pipelines.
+
+Design notes:
+- Conversions are lossless for the scalar types :class:`DataSet` supports
+  (``int | float | str | bool | None``).
+- ``None`` cells map to ``NaN`` in pandas and back, matching pandas convention.
+- Column order is preserved from the source on both directions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cds.data_analysis.dataset import DataSet, Row
+
+if TYPE_CHECKING:
+    # Imported only under TYPE_CHECKING so the module imports cleanly when
+    # pandas is absent; the real import happens inside the functions.
+    import pandas as pd
+
+
+_PANDAS_INSTALL_HINT = (
+    "pandas is an optional dependency. Install it with "
+    "`pip install scientific-computing-system[pandas]` "
+    "(or `pip install pandas`)."
+)
+
+
+def _require_pandas() -> Any:
+    """Import and return the ``pandas`` module, raising a helpful error if absent."""
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover - exercised only without pandas
+        raise ImportError(_PANDAS_INSTALL_HINT) from exc
+    return pd
+
+
+def to_dataframe(ds: DataSet) -> pd.DataFrame:
+    """Convert a :class:`DataSet` to a pandas ``DataFrame``.
+
+    Each row dict becomes a DataFrame row; column order follows
+    ``ds.columns``. ``None`` values are preserved as-is (pandas renders them
+    as ``NaN`` in numeric columns).
+
+    Args:
+        ds: a CDS :class:`DataSet`.
+
+    Returns:
+        A pandas ``DataFrame`` with the same rows and columns.
+
+    Raises:
+        ImportError: if pandas is not installed.
+    """
+    pandas_module = _require_pandas()
+    rows = ds.to_list()
+    columns = ds.columns
+    # The DataFrame constructor is typed as returning Any in the stubs; assign
+    # to an annotated local so the return type is pinned without a cast.
+    df: pd.DataFrame = pandas_module.DataFrame(rows, columns=columns if columns else None)
+    return df
+
+
+def from_dataframe(df: pd.DataFrame) -> DataSet:
+    """Convert a pandas ``DataFrame`` to a :class:`DataSet`.
+
+    Each DataFrame row becomes a row dict keyed by column name. pandas
+    ``NaN`` values are converted to ``None`` to match :class:`DataSet`'s
+    scalar type contract.
+
+    Args:
+        df: a pandas ``DataFrame``.
+
+    Returns:
+        A CDS :class:`DataSet` with the same data.
+
+    Raises:
+        ImportError: if pandas is not installed.
+    """
+    pandas_module = _require_pandas()
+    rows: list[Row] = []
+    # .to_dict(orient="records") yields plain dicts; NaN -> NaN (float).
+    # We normalize NaN to None to honor the DataSet scalar contract.
+    raw_records = df.to_dict(orient="records")
+    for record in raw_records:
+        row: Row = {}
+        for key, value in record.items():
+            # pd.isna handles both scalar NaN and None, but raises on arrays.
+            # Values here are scalars from a DataFrame cell.
+            try:
+                is_na = bool(pandas_module.isna(value))
+            except (TypeError, ValueError):  # pragma: no cover - defensive
+                # pd.isna raises only on array-like inputs. DataSet's Row
+                # contract restricts cells to scalars (int|float|str|bool|None),
+                # so this branch is unreachable for conforming data; kept as a
+                # guard against malformed/foreign rows slipping through.
+                is_na = value is None
+            row[str(key)] = None if is_na else value
+        rows.append(row)
+    return DataSet(rows)

cds/data_analysis/transform.py

@@ -0,0 +1,36 @@
+"""Data transformations."""
+
+from __future__ import annotations
+
+from cds.stats.descriptive import mean, stdev
+
+
+def normalize(data: list[float]) -> list[float]:
+    """Min-max normalization to [0, 1]."""
+    lo, hi = min(data), max(data)
+    rng = hi - lo
+    if rng == 0:
+        return [0.0] * len(data)
+    return [(x - lo) / rng for x in data]
+
+
+def z_score(data: list[float]) -> list[float]:
+    """Standardize to mean=0, std=1."""
+    m = mean(data)
+    s = stdev(data)
+    if s == 0:
+        return [0.0] * len(data)
+    return [(x - m) / s for x in data]
+
+
+def moving_average(data: list[float], window: int = 3) -> list[float]:
+    """Trailing moving average with the given window size (>= 1)."""
+
+    if window < 1:
+        raise ValueError("window must be >= 1")
+    result = []
+    for i in range(len(data)):
+        start = max(0, i - window + 1)
+        chunk = data[start : i + 1]
+        result.append(sum(chunk) / len(chunk))
+    return result

cds/data_analysis/viz.py

@@ -0,0 +1,88 @@
+"""Pure Python ASCII visualization tools for structured data."""
+
+from __future__ import annotations
+
+
+def plot_bar(data: dict[str, float], title: str = "Bar Chart", width: int = 50) -> str:
+    """Generate an ASCII bar chart from a dictionary.
+
+    Args:
+        data: Mapping from label to numeric value.
+        title: Chart title.
+        width: Maximum bar width in characters.
+    """
+    if not data:
+        return "No data to plot."
+
+    vals = list(data.values())
+    max_val = max(vals)
+    min_val = min(vals)
+
+    lines = [f"\n[bold]{title}[/]", "─" * len(title)]
+
+    # Simple normalization logic that respects 0 as a baseline
+    limit = max(abs(max_val), abs(min_val), 1e-10)
+
+    for label, val in data.items():
+        # Calculate bar length relative to the largest absolute value
+        bar_len = int((abs(val) / limit) * width)
+        if val >= 0:
+            bar = "█" * bar_len
+            suffix = f" (+{val:.2f})"
+        else:
+            # Represent negative values with a different character or notation
+            bar = "░" * bar_len
+            suffix = f" ({val:.2f})"
+
+        lines.append(f"{label:<15} | {bar}{suffix}")
+
+    return "\n".join(lines)
+
+
+def plot_line(
+    y_values: list[float], title: str = "Line Plot", height: int = 10, width: int = 60
+) -> str:
+    """Generate a simple ASCII line plot.
+
+    Args:
+        y_values: List of numeric values.
+        title: Plot title.
+        height: Number of rows.
+        width: Number of columns (will sample data to fit).
+    """
+    if not y_values:
+        return "No data to plot."
+
+    # Guard: width must be at least 2; otherwise stride below divides by zero.
+    eff_width = max(2, width)
+
+    # Sample/Interpolate to fit width
+    if len(y_values) > eff_width:
+        indices = [int(i * (len(y_values) - 1) / (eff_width - 1)) for i in range(eff_width)]
+        sampled = [y_values[i] for i in indices]
+    else:
+        sampled = y_values
+        eff_width = len(y_values)
+
+    max_y = max(sampled)
+    min_y = min(sampled)
+    y_range = max_y - min_y if max_y != min_y else 1.0
+
+    # Create grid
+    grid = [[" " for _ in range(eff_width)] for _ in range(height)]
+
+    for x, y in enumerate(sampled):
+        # Calculate row (inverted because row 0 is top)
+        norm_y = (y - min_y) / y_range
+        row = height - 1 - int(norm_y * (height - 1))
+        grid[row][x] = "•"
+
+    lines = [f"\n[bold]{title}[/]", "─" * len(title)]
+    for grid_row in grid:
+        lines.append("".join(grid_row))
+
+    min_y_str = f"{min_y:.2f}"
+    max_y_str = f"{max_y:.2f}"
+
+    lines.append(f"min: {min_y_str:<{eff_width // 2}}max: {max_y_str:>{eff_width // 2}}")
+    return "\n".join(lines)

cds/diffeq/__init__.py

@@ -0,0 +1,29 @@
+"""Ordinary differential equation solvers — Euler, RK4, RK45, implicit methods."""
+
+from cds.diffeq._implicit import (
+    backward_euler,
+    backward_euler_system,
+    trapezoid_method,
+    trapezoid_method_system,
+)
+from cds.diffeq.solvers import (
+    ODESolution,
+    euler_method,
+    midpoint_method,
+    rk4,
+    rk45,
+    solve_system,
+)
+
+__all__ = [
+    "ODESolution",
+    "backward_euler",
+    "backward_euler_system",
+    "euler_method",
+    "midpoint_method",
+    "rk4",
+    "rk45",
+    "solve_system",
+    "trapezoid_method",
+    "trapezoid_method_system",
+]