lf-pollywog 0.1.1__py3-none-any.whl

docs/conf.py

@@ -0,0 +1,39 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pollywog"
+copyright = "2025, Arthur Endlein"
+author = "Arthur Endlein"
+release = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+autodoc_member_order = "bysource"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

lf_pollywog-0.1.1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: lf_pollywog
+Version: 0.1.1
+Summary: Python library for working with Leapfrog calculation sets (.lfcalc files)
+Author: Arthur Endlein
+Author-email: Arthur Endlein <endarthur@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/endarthur/pollywog
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: conversion
+Requires-Dist: scikit-learn; extra == "conversion"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: scikit-learn; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# Automating Leapfrog Workflows with Pollywog – An Independent Open-Source Tool
+
+[![DOI](https://zenodo.org/badge/1071742254.svg)](https://doi.org/10.5281/zenodo.17313856)
+
+Professionals using Seequent solutions for geological modeling and resource estimation often work with .lfcalc files. These files can be repetitive to manage and prone to manual errors. This is especially true when dealing with conditional logic, domain-based dilution calculations, or predictive model integration.
+
+Pollywog was developed to support this technical audience. It is a Python package that enables:
+
+- Programmatic reading and writing of .lfcalc files, making calculations more standardized and reproducible
+- Automation of complex workflows, including conditional equations and post-processing of results
+- Integration with machine learning models via scikit-learn, allowing classifiers or regressions to be applied directly within Leapfrog calculations
+- Creation of reusable scripts, which can be versioned and audited, providing greater control over modeling processes
+
+Pollywog aims to reduce time spent on manual tasks, minimize input errors, and increase efficiency in geological modeling.
+
+The documentation includes practical examples and tutorials to help technical teams get started quickly.
+
+If you work with Leapfrog and are looking to optimize your workflows, Pollywog is worth exploring.
+
+Pollywog is still very much a work in progress, so take care in its use and make sure to not have anything important open and not saved in Leapfrog while testing it out. Also, please report any issues you encounter. Suggestions and contributions are very welcome!
+
+## Legal Disclaimer
+
+Pollywog is an independent open-source tool developed to support the automation of workflows involving .lfcalc files used in Leapfrog software by Seequent.
+This tool does not perform reverse engineering, does not modify Leapfrog, and does not access its source code or proprietary libraries. Pollywog operates exclusively on user-generated files and is designed to complement Leapfrog through external automation.
+
+Important:
+- Pollywog is not affiliated with, endorsed by, or sponsored by Seequent or any company associated with Leapfrog
+- Use of this tool does not violate Leapfrog’s license terms or Seequent’s policies
+- Users are encouraged to review Leapfrog’s terms of use before integrating Pollywog into commercial or corporate environments
+- The author is not responsible for any misuse of the tool that may breach Seequent’s licensing terms
+
+
+## Installation
+
+Install from pypi (not available yet, but soon):
+
+```bash
+pip install lf_pollywog
+```
+
+Or install the latest development version from GitHub:
+
+```bash
+pip install git+https://github.com/endarthur/pollywog.git
+```
+
+## Usage
+
+### Reading and Writing `.lfcalc` files
+
+```python
+import pollywog as pw
+calcset = pw.CalcSet.read_lfcalc("path/to/file.lfcalc")
+calcset.to_lfcalc("output.lfcalc")
+```
+
+### Creating a Simple Calculation Set
+
+```python
+from pollywog.core import Number, CalcSet
+calcset = CalcSet([
+    Number(name="Au_final", children=["clamp([Au_est], 0)"]),
+    Number(name="Ag_final", children=["clamp([Ag_est], 0)"])
+])
+calcset.to_lfcalc("postprocessed.lfcalc")
+```
+
+### Converting a scikit-learn model
+
+Currently supports decision trees (both classification and regression) and linear models:
+
+```python
+from pollywog.conversion.sklearn import convert_tree
+from sklearn.tree import DecisionTreeRegressor
+import numpy as np
+X = np.array([[0.2, 1.0, 10], [0.5, 2.0, 20]])
+y = np.array([0.7, 0.8])
+feature_names = ["Cu_final", "Au_final", "Ag_final"]
+reg = DecisionTreeRegressor(max_depth=2)
+reg.fit(X, y)
+recovery_calc = convert_tree(reg, feature_names, "recovery_ml")
+CalcSet([recovery_calc]).to_lfcalc("recovery_ml.lfcalc")
+```
+
+For more advanced workflows (domain dilution, conditional logic, economic value, combining CalcSets, etc.), see the Jupyter notebooks in the `examples/` folder of this repository or the documentation at https://pollywog.readthedocs.io/en/latest/.
+
+## Querying CalcSets
+
+Pollywog provides a powerful query method for filtering items in a `CalcSet`, inspired by pandas' DataFrame.query. You can use Python-like expressions to select items based on their attributes and external variables.
+
+### Syntax
+- Use item attributes (e.g., `name`, `item_type`) in expressions.
+- Reference external variables using `@var` syntax (e.g., `name.startswith(@prefix)`).
+- Supported helpers: `len`, `any`, `all`, `min`, `max`, `sorted`, `re`, `str`.
+
+### Examples
+
+```python
+# Select items whose name starts with 'Au'
+calcset.query('name.startswith("Au")')
+
+# Select items whose name starts with an external variable 'prefix'
+prefix = "Ag"
+calcset.query('name.startswith(@prefix)')
+
+# Select items with more than one child
+calcset.query('len(children) > 1')
+
+# Use regular expressions
+calcset.query('re.match(r"^A", name)')
+```
+
+### Notes
+- External variables (`@var`) are resolved from the caller's scope or passed as keyword arguments.
+- Only items matching the query expression are returned in the new `CalcSet`.
+
+## License
+
+MIT License
+
+<!-- ## Authors
+
+See `AUTHORS` file or repository contributors. -->
+
+## Contributions
+
+Contributions are very welcome!
+If you'd like to collaborate on Pollywog, whether through bug fixes, feature enhancements, new use cases, or documentation, please follow these steps:
+
+- Fork the repository
+- Create a feature branch (git checkout -b feature-name)
+- Make your changes and commit (git commit -m 'Add new feature')
+- Submit a pull request with a clear explanation of your changes
+
+Before contributing, please:
+- Ensure your changes align with the project’s goals
+- Maintain consistent code style
+- Test your modifications whenever possible
+
+Feel free to open an issue if you have questions or suggestions.
+
+## Acknowledgements
+
+Thanks to Debora Roldão for helping with organization of the project, documentation and design, Eduardo Takafuji for the initial discussion of the feasability of this all those years ago and Jessica da Matta for support and sanity checks along the way.

lf_pollywog-0.1.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+docs/conf.py,sha256=p-qpiT0_Angy1mFUQ2Lo9CEmHTYq8btI6oPK4GFw-mw,1330
+lf_pollywog-0.1.1.dist-info/licenses/LICENSE,sha256=MXMNCuTUaZEm8i5kH-5700l4scXAg7OtkK1oJGxAj50,1092
+pollywog/__init__.py,sha256=4eW1G9ffdPHGspw_gNWhjWz1DvJ0IHa5bosou8vR1x4,143
+pollywog/core.py,sha256=NKf5s_9sq1QTP6iXCaUn3zIuekXqHDGBRzyDRqFB5KM,29165
+pollywog/display.py,sha256=qnz2Qnk0nGuvgT9hpYQ4g5jf2WIlib_phLEnDJG7Bas,6861
+pollywog/helpers.py,sha256=o7JHMXYZrzRpTUUObMb-IVN4VAuk_l6fKSvRUpvVIuo,9434
+pollywog/run.py,sha256=N0gvWEgn7OE2pgvomLkPmeyntKUR04MnIM4hPNtmAJo,4241
+pollywog/utils.py,sha256=7zY92xZ5ZuezvrZQ9n5td7FzlYIhZdMEVO5RUg7zKW0,2686
+pollywog/conversion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pollywog/conversion/sklearn.py,sha256=Q7ROJSAp7EQ-gNhGqd1kRtwRtvP_srCpEeeta_tLBuc,6216
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/conftest.py,sha256=9AG2ujuE0JVQTN7FwDKmBd8sr-gTYcaiSHtdKHNygNE,109
+tests/test_conversion.py,sha256=GivwmDLqvWL5X9Oi_g8H9ec1LCwnbAzGokaELx5ABn8,2165
+tests/test_core.py,sha256=q-10Z2pusPiXRol55OUR93pGsZrvHbqCu0S8H-zo7wg,8762
+tests/test_display.py,sha256=hDSZB-F5PsfM7KYCH8GyBZKKJog2UaYatYpCbYHwRrc,2195
+tests/test_helpers.py,sha256=xjAnKbnqEVXr5kTRgbKkWHixYI2uE1SYThA7s48Z9Vg,2700
+tests/test_run.py,sha256=OSvDzzswLhwXvaBZOjK5F80CXpaijVq74hLFf6ro1wU,2419
+tests/test_utils.py,sha256=SyPV_dGTdhaw5c2A0H9Cn69baKzCyMx2L11fYc8HzDo,1120
+lf_pollywog-0.1.1.dist-info/METADATA,sha256=wDtGmHy-9aHhCicXOPXhYcRSJ5KxzExFZAZIRZqKLvU,6924
+lf_pollywog-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lf_pollywog-0.1.1.dist-info/top_level.txt,sha256=lMfdwk0fB3NwCWtYY9MShj6useQfVBas_0dLAoVJcfw,20
+lf_pollywog-0.1.1.dist-info/RECORD,,

lf_pollywog-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lf_pollywog-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arthur Endlein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lf_pollywog-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+docs
+pollywog
+tests

pollywog/__init__.py

@@ -0,0 +1,2 @@
+from .core import CalcSet, Variable, Number, Category, Filter, If, IfRow
+from .helpers import Sum, Average, Product, Normalize, WeightedAverage

pollywog/conversion/sklearn.py

@@ -0,0 +1,154 @@
+from ..core import If, IfRow, Variable, Number, Category
+
+try:
+    import sklearn
+except ImportError:
+    raise ImportError(
+        "scikit-learn is required for conversion. Please install it via 'pip install scikit-learn'."
+    )
+
+
+# Classification and Regression Trees
+
+from sklearn import tree, ensemble
+
+
+def convert_tree(tree_model, feature_names, target_name, flat=False, comment_equation=None, output_type=None):
+    tree_ = tree_model.tree_
+    feature_name = [
+        feature_names[i] if i != tree._tree.TREE_UNDEFINED else "undefined!"
+        for i in tree_.feature
+    ]
+
+    is_classifier = hasattr(tree_model, "classes_")
+    classes = None
+    if is_classifier:
+        classes = tree_model.classes_
+
+    if flat:
+        # Create a flat list of conditions and values
+        conditions = []
+        values = []
+
+        def recurse_flat(node, current_conditions):
+            if tree_.feature[node] != tree._tree.TREE_UNDEFINED:
+                name = feature_name[node]
+                threshold = tree_.threshold[node]
+                left_conditions = current_conditions + [f"[{name}] <= {threshold}"]
+                right_conditions = current_conditions + [f"[{name}] > {threshold}"]
+                recurse_flat(tree_.children_left[node], left_conditions)
+                recurse_flat(tree_.children_right[node], right_conditions)
+            else:
+                value = tree_.value[node][0][0] if not is_classifier else classes[tree_.value[node][0].argmax()]
+                value = f'"{value}"' if isinstance(value, str) else str(value)
+                conditions.append(" and ".join(current_conditions) if current_conditions else "True")
+                values.append(value)
+
+        recurse_flat(0, [])
+        if_rows = [IfRow([cond], [val]) for cond, val in zip(conditions, values)]
+        if_rows = If(if_rows, otherwise=["blank"])
+    else:
+        # Create nested If structure
+        def recurse(node):
+            if tree_.feature[node] != tree._tree.TREE_UNDEFINED:
+                name = feature_name[node]
+                threshold = tree_.threshold[node]
+                left = recurse(tree_.children_left[node])
+                right = recurse(tree_.children_right[node])
+                return If(IfRow(f"[{name}] <= {threshold}", left), right)
+            else:
+                value = tree_.value[node][0][0] if not is_classifier else classes[tree_.value[node][0].argmax()]
+                value = f'"{value}"' if isinstance(value, str) else str(value)
+                return value
+
+        if_rows = recurse(0)
+
+
+    if comment_equation is None:
+        comment_equation = f"Converted from {tree_model.__class__.__name__}"
+
+    if output_type is not None:
+        return output_type(target_name, if_rows, comment_equation=comment_equation)
+
+    if isinstance(tree_model, tree.DecisionTreeRegressor):
+        return Number(target_name, if_rows, comment_equation=comment_equation)
+    elif isinstance(tree_model, tree.DecisionTreeClassifier):
+        return Category(target_name, if_rows, comment_equation=comment_equation)
+    else:
+        raise ValueError("Unsupported tree model type")
+
+def convert_forest(forest_model, feature_names, target_name, flat=False, comment_equation=None):
+    """Convert a RandomForestRegressor or RandomForestClassifier to a Pollywog Number or Category.
+    
+    Args:
+        forest_model: A fitted RandomForestRegressor or RandomForestClassifier from scikit-learn
+        feature_names: List of feature names used in the model
+        target_name: Name of the target variable to create
+        flat: Whether to create flattened if expressions (default: False)
+        comment_equation: Optional comment for the generated equation
+
+    Returns:
+        A Pollywog Number (for regression) or Category (for classification)
+    """
+    if not isinstance(forest_model, (ensemble.RandomForestRegressor, ensemble.RandomForestClassifier)):
+        raise ValueError("forest_model must be a RandomForestRegressor or RandomForestClassifier")
+
+    # Convert each tree in the forest
+    trees = [
+        convert_tree(
+            estimator,
+            feature_names,
+            f"{target_name}_tree_{i}",
+            flat=flat,
+            comment_equation=f"Tree {i} from {forest_model.__class__.__name__}",
+            output_type=Variable
+        )
+        for i, estimator in enumerate(forest_model.estimators_)
+    ]
+
+
+    # Average predictions for regression or majority vote for classification
+    if isinstance(forest_model, ensemble.RandomForestRegressor):
+        # For regression, create an equation that averages the tree outputs
+        tree_outputs = " + ".join([f"[{t.name}]" for t in trees])
+        equation = f"({tree_outputs}) / {len(trees)}"
+        return trees + [Number(
+            target_name,
+            [equation],
+            comment_equation=f"Averaged output from {len(trees)} trees in {forest_model.__class__.__name__}",
+        )]
+    elif isinstance(forest_model, ensemble.RandomForestClassifier):
+        # For classification, create an equation that does majority voting
+        tree_outputs = " + ".join([f"[{t.name}]" for t in trees])
+        equation = f"round(({tree_outputs}) / {len(trees)})"
+        return trees + [Category(
+            target_name,
+            [equation],
+            comment_equation=f"Majority vote from {len(trees)} trees in {forest_model.__class__.__name__}",
+        )]
+
+# Linear Models
+from sklearn import linear_model
+
+
+def convert_linear_model(lm_model, feature_names, target_name):
+    coefs = lm_model.coef_
+    intercept = lm_model.intercept_
+
+    def format_float(val):
+        return f"{float(val):.6f}"
+
+    terms = [format_float(intercept)] if intercept != 0 else []
+    for coef, feature in zip(coefs, feature_names):
+        if coef != 0:
+            terms.append(f"{format_float(coef)} * [{feature}]")
+
+    equation = " + ".join(terms) if terms else "0"
+    return Number(
+        target_name,
+        [equation],
+        comment_equation=f"Converted from {lm_model.__class__.__name__}",
+    )
+
+# Pre Processing
+