conic 0.1.0__tar.gz

conic-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: conic
+Version: 0.1.0
+Summary: CPT/SCPTu Data-Driven Evaluator.
+Author: Francesco Franco
+Author-email: Francesco Franco <ffrancoa97@gmail.com>
+License-Expression: AGPL-3.0-or-later
+Requires-Dist: polars>=1.40.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pytest-benchmark>=5.2.3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <a href="https://github.com/ferrosoft/conic">
+    <img src="https://raw.githubusercontent.com/ferrosoft/conic/main/assets/conic_banner.png" alt="conic logo" width="80%">
+  </a>
+</h1>
+
+##  A Python library for the exploration of CPT/SCPTu profiles
+
+**Conic** (stylized in all lowercase) is a Python library for data-driven analysis of CPT soundings. 
+
+
+## Setup
+
+Install the latest **`conic`** version with:
+
+```sh
+pip install conic
+```
+
+If you use `uv` (recommended) you can add **`conic`** to your environment by using:
+
+```sh
+uv add conic
+```
+
+## Credits
+
+* **`conic`** author and maintainer: Francesco A. Franco ([@ffrancoa]).
+
+* Font used in logo: [Lexend]. Open Font License.
+
+[@ffrancoa]: https://github.com/ffrancoa
+[Lexend]: https://www.lexend.com/
+
+## License
+
+Conic is released under the [Affero General Public License, Version 3.0].
+
+[Affero General Public License, Version 3.0]: https://opensource.org/license/agpl-3-0
+
+---

conic-0.1.0/README.md

@@ -0,0 +1,41 @@
+<h1 align="center">
+  <a href="https://github.com/ferrosoft/conic">
+    <img src="https://raw.githubusercontent.com/ferrosoft/conic/main/assets/conic_banner.png" alt="conic logo" width="80%">
+  </a>
+</h1>
+
+##  A Python library for the exploration of CPT/SCPTu profiles
+
+**Conic** (stylized in all lowercase) is a Python library for data-driven analysis of CPT soundings. 
+
+
+## Setup
+
+Install the latest **`conic`** version with:
+
+```sh
+pip install conic
+```
+
+If you use `uv` (recommended) you can add **`conic`** to your environment by using:
+
+```sh
+uv add conic
+```
+
+## Credits
+
+* **`conic`** author and maintainer: Francesco A. Franco ([@ffrancoa]).
+
+* Font used in logo: [Lexend]. Open Font License.
+
+[@ffrancoa]: https://github.com/ffrancoa
+[Lexend]: https://www.lexend.com/
+
+## License
+
+Conic is released under the [Affero General Public License, Version 3.0].
+
+[Affero General Public License, Version 3.0]: https://opensource.org/license/agpl-3-0
+
+---

conic-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "conic"
+version = "0.1.0"
+description = "CPT/SCPTu Data-Driven Evaluator."
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+authors = [
+    { name = "Francesco Franco", email = "ffrancoa97@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "polars>=1.40.1",
+    "pydantic>=2.13.4",
+    "pytest-benchmark>=5.2.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipython>=9.13.0",
+    "pytest>=9.0.3",
+]

conic-0.1.0/src/conic/_canonical.py

@@ -0,0 +1,26 @@
+COL_DEPTH: str = "Depth (m)"
+COL_QC: str    = "qc (MPa)"
+COL_FS: str    = "fs (kPa)"
+COL_U2: str    = "u2 (kPa)"
+
+COL_U0: str     = "u0 (kPa)"
+COL_SV_TOT: str = "σv tot (kPa)"
+COL_SV_EFF: str = "σv eff (kPa)"
+
+COL_QT: str = "qt (MPa)"
+COL_FR: str = "Fr (%)"
+COL_BQ: str = "Bq (-)"
+
+COL_N: str     = "n (-)"
+COL_QTN: str   = "Qtn (-)"
+COL_IC: str    = "Ic (-)"
+COL_CONVG: str = "convg. (-)"
+
+COL_CD: str = "CD (-)"
+COL_IB: str = "IB (-)"
+
+AREA_RATIO: float  = 0.80
+GAMMA_WATER: float = 9.81
+
+CLEAN_MODE: str = "replace"
+

conic-0.1.0/src/conic/_helpers.py

@@ -0,0 +1,21 @@
+import hashlib
+from io import BytesIO
+from typing import Iterable, cast
+
+import polars as pl
+
+
+def get_missing_columns(
+        data: pl.DataFrame,
+        required_columns: Iterable[str]
+    ) -> set:
+
+    return set(required_columns).difference(data.columns)
+
+def dataframe_fingerprint(data: pl.DataFrame):
+    data_to_bytes = cast(BytesIO, data.write_ipc(file=None)).getvalue()
+    
+    hash_text = hashlib.sha256(data_to_bytes).hexdigest()
+
+    return hash_text[:16]
+

conic-0.1.0/src/conic/config.py

@@ -0,0 +1,137 @@
+import tomllib
+from pathlib import Path
+from typing import Annotated, Literal, Optional, Self, cast
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    NegativeFloat,
+    NonNegativeFloat,
+    PositiveFloat,
+)
+
+from conic._canonical import (
+    AREA_RATIO,
+    COL_BQ,
+    COL_CD,
+    COL_CONVG,
+    COL_DEPTH,
+    COL_FR,
+    COL_FS,
+    COL_IB,
+    COL_IC,
+    COL_N,
+    COL_QC,
+    COL_QT,
+    COL_QTN,
+    COL_SV_EFF,
+    COL_SV_TOT,
+    COL_U0,
+    COL_U2,
+    GAMMA_WATER,
+    CLEAN_MODE
+)
+
+
+type ColumnName = Annotated[str, Field(max_length=50)]
+type UnitRatio = Annotated[float, Field(gt=0.0, le=1.0)]
+type Indicators = list[NegativeFloat]
+type CleanMode = Literal["replace", "remove"]
+
+
+class InputColumns(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    depth: ColumnName = COL_DEPTH
+    qc: ColumnName    = COL_QC
+    fs: ColumnName    = COL_FS
+    u2: ColumnName    = COL_U2
+
+    u0: ColumnName     = COL_U0
+    sv_tot: ColumnName = COL_SV_TOT
+    sv_eff: ColumnName = COL_SV_EFF
+
+class OutputColumns(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    
+    qt: ColumnName = COL_QT
+    fr: ColumnName = COL_FR
+    bq: ColumnName = COL_BQ
+    
+    n: ColumnName     = COL_N
+    qtn: ColumnName   = COL_QTN
+    ic: ColumnName    = COL_IC
+    convg: ColumnName = COL_CONVG
+
+    cd: ColumnName = COL_CD
+    ib: ColumnName = COL_IB
+
+class Columns(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    input: InputColumns = Field(default_factory=InputColumns)
+    output: OutputColumns = Field(default_factory=OutputColumns)
+
+class Parameters(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    area_ratio: UnitRatio = AREA_RATIO
+    gamma_water: PositiveFloat = GAMMA_WATER
+    gamma_soil: Optional[PositiveFloat] = None
+    water_level: Optional[NonNegativeFloat] = None
+
+class Cleansing(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    start_depth: Optional[NonNegativeFloat] = None
+    spacing: Optional[PositiveFloat] = None
+    
+    indicators: Indicators = Field(default_factory=lambda: list())
+    clean_mode: CleanMode = cast(CleanMode, CLEAN_MODE)
+
+class Configurator(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    columns: Columns = Field(default_factory=Columns)
+    parameters: Parameters = Field(default_factory=Parameters)
+    cleansing: Cleansing = Field(default_factory=Cleansing)
+
+    def _with_field(self, submodel_name: str, field_name: str, value: object) -> Self:
+        submodel = getattr(self, submodel_name)
+
+        new_submodel_dict = submodel.model_dump() | {field_name: value}
+        new_submodel = type(submodel)(**new_submodel_dict)
+
+        return self.model_copy(update={submodel_name: new_submodel})
+
+    def with_area_ratio(self, value: UnitRatio) -> Self:
+        return self._with_field("parameters", "area_ratio", value)
+
+    def with_gamma_water(self, value: PositiveFloat) -> Self:
+        return self._with_field("parameters", "gamma_water", value)
+
+    def with_gamma_soil(self, value: Optional[PositiveFloat]) -> Self:
+        return self._with_field("parameters", "gamma_soil", value)
+
+    def with_water_level(self, value: Optional[NonNegativeFloat]) -> Self:
+        return self._with_field("parameters", "water_level", value)
+
+    def with_start_depth(self, value: Optional[NonNegativeFloat]) -> Self:
+        return self._with_field("cleansing", "start_depth", value)
+
+    def with_spacing(self, value: Optional[PositiveFloat]) -> Self:
+        return self._with_field("cleansing", "spacing", value)
+
+    def with_indicators(self, values: list[float]) -> Self:
+        return self._with_field("cleansing", "indicators", values)
+
+    def with_clean_mode(self, value: CleanMode) -> Self:
+        return self._with_field("cleansing", "clean_mode", value)
+
+    @classmethod
+    def from_toml(cls, file_path: Path | str) -> Self:
+        with Path(file_path).open("rb") as file:
+            config = tomllib.load(file)
+        return cls.model_validate(config)
+

conic-0.1.0/src/conic/pipeline.py

@@ -0,0 +1,142 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal, NamedTuple, Self, overload
+
+import polars as pl
+
+from conic import preprocess
+from conic.config import Configurator
+from conic._helpers import dataframe_fingerprint
+
+
+@dataclass(frozen=True, slots=True)
+class Step:
+    name: str
+    apply: Callable[[pl.DataFrame], pl.DataFrame]
+
+@dataclass(frozen=True, slots=True)
+class StepCatalog:
+    config: Configurator
+
+    def adjust_depth_spacing(self) -> Step:
+        function = preprocess.adjust_depth_spacing
+        cleansing = self.config.cleansing
+        columns = self.config.columns
+
+        def callback(data: pl.DataFrame) -> pl.DataFrame:
+            return function(
+                data,
+                start_depth=cleansing.start_depth,
+                spacing=cleansing.spacing,
+                col_depth=columns.input.depth
+            )
+
+        return Step(name=function.__name__, apply=callback)
+
+    def sanitize_dataframe(self) -> Step:
+        function = preprocess.sanitize_dataframe
+        columns = self.config.columns
+
+        def callback(data: pl.DataFrame) -> pl.DataFrame:
+            return function(
+                data,
+                col_depth=columns.input.depth,
+                col_qc=columns.input.qc,
+                col_fs=columns.input.fs,
+                col_u2=columns.input.u2,
+                col_u0=columns.input.u0,
+                col_sv_eff=columns.input.sv_eff,
+                col_sv_tot=columns.input.sv_tot
+            )
+
+        return Step(name=function.__name__, apply=callback)
+
+    def compute_hydrostatic(self) -> Step:
+        function = preprocess.compute_hydrostatic
+        parameters = self.config.parameters
+        columns = self.config.columns
+
+        def callback(data: pl.DataFrame) -> pl.DataFrame:
+            return function(
+                data,
+                water_level=parameters.water_level,
+                gamma_water=parameters.gamma_water,
+                col_depth=columns.input.depth,
+                col_u0=columns.input.u0,
+                override=True
+            )
+
+        return Step(name=function.__name__, apply=callback)
+
+    def clean_by_indicators(self) -> Step:
+        function = preprocess.clean_by_indicators
+        cleansing = self.config.cleansing
+
+        def callback(data: pl.DataFrame) -> pl.DataFrame:
+            return function(
+                data,
+                indicators=cleansing.indicators,
+                mode=cleansing.clean_mode
+            )
+
+        return Step(name=function.__name__, apply=callback)
+
+class PipelineResult(NamedTuple):
+    data: pl.DataFrame
+    metadata: dict[str, object]
+
+@dataclass(frozen=True, slots=True)
+class Pipeliner:
+    config: Configurator
+    steps: tuple[Step, ...]
+
+    @classmethod
+    def default(cls, config: Configurator) -> Self:
+        catalog = StepCatalog(config)
+        
+        steps = (
+            catalog.sanitize_dataframe(),
+            catalog.adjust_depth_spacing(),
+            catalog.clean_by_indicators(),
+            catalog.compute_hydrostatic()
+        )
+
+        return cls(config=config, steps=steps)
+
+    @overload
+    def run(
+            self,
+            inp_data: pl.DataFrame, *,
+            metadata: Literal[False] = False,
+        ) -> pl.DataFrame: ...
+    @overload
+    def run(
+            self,
+            inp_data: pl.DataFrame, *,
+            metadata: Literal[True],
+        ) -> PipelineResult: ...
+    def run(
+            self,
+            inp_data: pl.DataFrame, *,
+            metadata: bool = False
+        ) -> pl.DataFrame | PipelineResult:
+
+        out_data = inp_data
+
+        for step in self.steps:
+            out_data = step.apply(out_data)
+            
+        if not metadata:
+            return out_data
+
+        meta = {
+            "data_hash": dataframe_fingerprint(inp_data),
+            "source_path": None,
+            "config": self.config.model_dump(),
+            "steps": [step.name for step in self.steps],
+            "timestamp_utc": datetime.now(timezone.utc).isoformat
+        }
+
+        return PipelineResult(data=out_data, metadata=meta)
+

conic-0.1.0/src/conic/preprocess.py

@@ -0,0 +1,158 @@
+from typing import Literal, Optional, cast
+
+import polars as pl
+from polars.exceptions import ColumnNotFoundError
+
+from conic._canonical import (
+    COL_DEPTH,
+    COL_FS,
+    COL_QC,
+    COL_SV_EFF,
+    COL_SV_TOT,
+    COL_U0,
+    COL_U2,
+    GAMMA_WATER
+)
+from conic._helpers import get_missing_columns
+
+def compute_hydrostatic(
+        data: pl.DataFrame,
+        water_level: Optional[float] = None, *,
+        gamma_water: float = GAMMA_WATER,
+        col_depth: str = COL_DEPTH,
+        col_u0: str = COL_U0,
+        override: bool = False
+    ) -> pl.DataFrame:
+
+    if col_depth not in data.columns:
+        raise ColumnNotFoundError(
+            f"Depth column is missing in DataFrame: '{col_depth}'."
+        )
+
+    if col_u0 in data.columns and not override:
+        raise ValueError(
+            f"Hydrostatic pressure ({col_u0}) was already included in "
+            f"this DataFrame. Set `override=True` to override."
+        )
+
+    if water_level is None:
+        data_with_u0 = data.with_columns(pl.lit(0.0).alias(col_u0))
+    else:
+        data_with_u0 = data.with_columns(
+            pl.when(pl.col(col_depth) >= water_level)
+            .then((pl.col(col_depth) - water_level) * gamma_water)
+            .otherwise(0.0)
+            .alias(col_u0)
+        )
+
+    return data_with_u0
+
+def adjust_depth_spacing(
+        data: pl.DataFrame, *,
+        start_depth: Optional[float] = None,
+        spacing: Optional[float] = None,
+        digits: int = 3,
+        col_depth: str = COL_DEPTH,
+    ) -> pl.DataFrame:
+
+    if col_depth not in data.columns:
+        raise ColumnNotFoundError(
+            f"Depth column is missing in DataFrame: '{col_depth}'."
+        )
+
+    if (nrows := data.height) < 2:
+        raise ValueError(
+            "DataFrame must have at least 2 rows to infer depth spacing. "
+        )
+
+    if start_depth is None:
+        start_depth = data.item(0, col_depth)
+
+    if spacing is None:
+        mean_spacing = data.get_column(col_depth).diff().mean()
+        spacing = round(cast(float, mean_spacing), digits)
+
+    new_depths = start_depth + pl.int_range(nrows, eager=True) * spacing
+    new_depths = new_depths.round(digits)
+
+    return data.with_columns(new_depths.alias(col_depth))
+
+def sanitize_dataframe(
+        data: pl.DataFrame, *,
+        col_depth: str = COL_DEPTH,
+        col_qc: str = COL_QC,
+        col_fs: str = COL_FS,
+        col_u2: str = COL_U2,
+        col_u0: str = COL_U0,
+        col_sv_eff: str = COL_SV_EFF,
+        col_sv_tot: str = COL_SV_TOT,
+        include_optional: bool = True
+    ) -> pl.DataFrame:
+
+    required_columns = [col_depth, col_qc, col_fs, col_u2]
+    optional_columns = [col_u0, col_sv_eff, col_sv_tot]
+
+    if missing_columns := get_missing_columns(data, required_columns):
+        raise ColumnNotFoundError(
+            f"Missing required columns: '{missing_columns}'."
+        )
+
+    selected_columns = required_columns
+
+    if include_optional:
+        additional_columns = set(optional_columns).intersection(data.columns)
+        selected_columns += list(additional_columns)
+
+    return data.select(selected_columns)
+
+def filter_by_indicators(
+        data: pl.DataFrame,
+        indicators: list[float], *,
+        action: Literal["remove", "select"] = "remove"
+    ) -> pl.DataFrame:
+
+    if action not in ["remove", "select"]:
+        raise ValueError(
+            "Invalid `action` argument. Must be 'remove' or 'select'."
+        )
+
+    expr = pl.selectors.numeric().is_in(indicators)
+    expr = pl.any_horizontal(expr)
+    
+    return data.filter(expr.not_() if action == "remove" else expr)
+
+def split_by_indicators(
+        data: pl.DataFrame,
+        indicators: list[float], *,
+        index_col: str = "_id_"        
+    ) -> tuple[pl.DataFrame, pl.DataFrame]:
+
+    indexed_data = data.with_row_index(index_col)
+
+    rows_with = filter_by_indicators(indexed_data, indicators, action="select")
+    rows_without = filter_by_indicators(indexed_data, indicators)
+    
+    return rows_with, rows_without
+
+def clean_by_indicators(
+        data: pl.DataFrame,
+        indicators: list[float], *,
+        mode: Literal["remove", "replace"] = "replace"
+    ) -> pl.DataFrame:
+
+    if mode not in ["remove", "replace"]:
+        raise ValueError(
+            "Invalid `action` argument. Must be 'remove' or 'replace'."
+        )
+
+    match mode:
+        case "remove":
+            return filter_by_indicators(data, indicators, action="remove")
+        case "replace":
+            return data.with_columns(
+                pl.when(pl.selectors.numeric().is_in(indicators))
+                .then(None)
+                .otherwise(pl.selectors.numeric())
+                .name.keep()
+            )
+