txgraffiti.logic

txgraffiti.logic.properties

Logical components for symbolic reasoning over dataframes.

This module defines core classes used for automated conjecturing, including:

Property: symbolic numeric expressions over DataFrame columns.
Predicate: boolean-valued expressions that support logical algebra.
Inequality: a comparison between Property objects.
Conjecture: logical implications between Predicate expressions.

All expressions can be evaluated on a pandas DataFrame row-wise.

txgraffiti.logic.properties.Constant(c)[source]

Create a constant-valued Property.

Parameters:: c (Number) – The constant value to use.
Returns:: A Property that returns c for every row in the DataFrame.
Return type:: Property

Examples

>>> import pandas as pd
>>> from txgraffiti.logic import Constant
>>> df = pd.DataFrame({"x": [1, 2, 3]})
>>> p = Constant(7)
>>> p(df).tolist()
[7, 7, 7]

class txgraffiti.logic.properties.Property(name, func)[source]

Bases: object

A symbolic property representing a real-valued function on a pandas DataFrame.

Properties can be combined with arithmetic operators (+, -, *, /, etc.) and compared using inequality operators (<, <=, ==, !=, >=, >).

Parameters:

name (str) – A symbolic name for the property.
func (Callable[[pd.DataFrame], pd.Series]) – A function that computes the property row-wise from a DataFrame.

Examples

from txgraffiti.logic import Property >>> deg = Property(“deg”, lambda df: df[“degree”]) >>> 2 * deg + 3 <Property ((2 * deg) + 3)>

func: Callable[[DataFrame], Series]

name: str

txgraffiti.logic.predicates

class txgraffiti.logic.predicates.Predicate(name, func)[source]

Bases: object

A boolean-valued expression on a DataFrame.

Predicates support logical operations including AND (&), OR (|), XOR (^), NOT (~), and implication via .implies() or >>.

Parameters:

name (str) – The symbolic name of the predicate.
func (Callable[[pd.DataFrame], pd.Series]) – A function that evaluates to a boolean Series row-wise.

_and_terms

Flattened AND operands, used internally.

Type:: list[Predicate], optional

_or_terms

Flattened OR operands, used internally.

Type:: list[Predicate], optional

_neg_operand

The negated operand, if this predicate is a negation.

Type:: Predicate, optional

Examples

from txgraffiti.logic import Predicate >>> even = Predicate(“even”, lambda df: df[“n”] % 2 == 0) >>> gt_5 = Predicate(“>5”, lambda df: df[“n”] > 5) >>> even & gt_5 <Predicate (even) ∧ (>5)>

func: Callable[[DataFrame], Series]

implies(other, *, as_conjecture=False)[source]

Logical implication: self → other.

Parameters:

other (Predicate) – The consequence.
as_conjecture (bool, optional) – If True, returns a Conjecture. If False, returns a Predicate equivalent to ¬self ∨ other.

Returns:

The implication formula.

Return type:

Predicate or Conjecture

name: str

txgraffiti.logic.inequalities

Logical components for symbolic reasoning over dataframes.

This module defines core classes used for automated conjecturing, including:

Property: symbolic numeric expressions over DataFrame columns.
Predicate: boolean-valued expressions that support logical algebra.
Inequality: a comparison between Property objects.
Conjecture: logical implications between Predicate expressions.

All expressions can be evaluated on a pandas DataFrame row-wise.

class txgraffiti.logic.inequalities.Inequality(lhs, op, rhs)[source]

Bases: Predicate

A comparison between two Property expressions.

Constructed automatically when using operators like p1 < p2.

Parameters:

lhs (Property) – The left-hand side of the inequality.
op (str) – The comparison operator. One of {“<”, “<=”, “>”, “>=”, “==”, “!=”}.
rhs (Property) – The right-hand side of the inequality.

lhs

Left operand.

Type:: Property

rhs

Right operand.

Type:: Property

op

The operator used.

Type:: str

Examples

>>> from txgraffiti import Property
>>> p1 = Property('alpha', lambda df: df['alpha'])
>>> p2 = Property('beta', lambda df: df['beta'])
>>> p1 < p2
<Predicate alpha < beta>

slack(df)[source]

Compute the slack of the inequality on a DataFrame.

Slack is defined as: - rhs - lhs for “<”, “<=”, “≤” - lhs - rhs for “>”, “>=”

Parameters:: df (pd.DataFrame) – The data on which to evaluate the slack.
Returns:: The row-wise slack values.
Return type:: pd.Series

touch_count(df)[source]

Count how many rows satisfy the inequality with equality.

Parameters:: df (pd.DataFrame) – The data to evaluate.
Returns:: The number of rows where slack is exactly zero.
Return type:: int

txgraffiti.logic.conjectures

class txgraffiti.logic.conjectures.Conjecture(hypothesis, conclusion)[source]

Bases: Predicate

A logical implication between two predicates.

Represents a rule of the form: (hypothesis) → (conclusion).

Parameters:

hypothesis (Predicate) – The antecedent of the implication.
conclusion (Predicate) – The consequent of the implication.

Examples

>>> from txgraffiti.logic import KnowledgeTable, Conjecture
>>> df = KnowledgeTable({
...     'alpha': [1, 2, 3],
...     'beta': [3, 1, 1],
...     'connected': [True, True, True],
...     'tree': [False, False, True],
... })
>>> alpha = df.alpha
>>> beta = df.beta
>>> connected = df.connected
>>> conj = Conjecture(connected, beta >= alpha - 2)
>>> conj.is_true(df)
True

accuracy(df)[source]

Compute the conditional accuracy of the conjecture.

This is defined as the fraction of rows satisfying the conclusion among those satisfying the hypothesis.

Parameters:: df (pd.DataFrame) – The data to evaluate.
Returns:: The accuracy of the conjecture.
Return type:: float

contrapositive()[source]

Return the contrapositive: ¬(conclusion) → ¬(hypothesis).

Return type:: Conjecture

counterexamples(df)[source]

Return the rows that violate the conjecture.

Parameters:: df (pd.DataFrame) – The data to search.
Returns:: Subset of rows where the implication fails.
Return type:: pd.DataFrame

is_true(df)[source]

Check if the conjecture holds on all rows of the DataFrame.

Parameters:: df (pd.DataFrame) – The data to evaluate.
Returns:: True if all rows satisfy the implication.
Return type:: bool

txgraffiti.logic.tables

class txgraffiti.logic.tables.KnowledgeTable(data=None, index=None, columns=None, dtype=None, copy=None)[source]

Bases: DataFrame

A pandas DataFrame subclass that “lifts” its columns into TxGraffiti Properties and Predicates, preserving the subclass through most DataFrame operations.

Parameters:

*args – Passed through to pandas.DataFrame. See pandas.DataFrame for supported parameters.
**kwargs – Passed through to pandas.DataFrame. See pandas.DataFrame for supported parameters.

<column_name>

If a column is boolean, kt.<column_name> returns a txgraffiti.logic.predicates.Predicate that masks the DataFrame on that column. Otherwise it returns a txgraffiti.logic.properties.Property on that column.

Type:: Property or Predicate

to_session(object_symbol='G', base=TRUE)[source]: Create a ConjecturePlayground for this table.

Notes

We implement the pandas _constructor hook so that methods like df.loc[…], .assign(), etc., return a KnowledgeTable again.
Only existing column names are intercepted in __getattr__; all other attributes fall back to the normal DataFrame API.

Examples

>>> import pandas as pd
>>> from txgraffiti.logic.tables import KnowledgeTable
>>> df = pd.DataFrame({
...     'alpha':     [1, 2, 3],
...     'connected': [True, False, True],
... })
>>> kt = KnowledgeTable(df)
>>> # Numeric column lifts to Property:
>>> prop = kt.alpha
>>> print(prop(df))
0    1
1    2
2    3
Name: alpha, dtype: int64

>>> # Boolean column lifts to Predicate:
>>> pred = kt.connected
>>> print(pred(df))
0     True
1    False
2     True
Name: connected, dtype: bool

>>> # Start a conjecturing session:
>>> session = kt.to_session(object_symbol="G", base=kt.connected)
>>> session  
<txgraffiti.playground.conjecture.ConjecturePlayground object at ...>

auto_wrap()[source]

to_session(object_symbol='G', base=<Predicate True>)[source]

Create a ConjecturePlayground session from this table.

Parameters:

object_symbol (str, optional) – The symbol to use for the “object” in generated conjectures (default is "G").
base (Predicate, optional) – A base hypothesis to conjoin with any user‐provided hypothesis (default is TRUE, i.e. no restriction).

Returns:

An instance of txgraffiti.playground.conjecture.ConjecturePlayground initialized with this table.

Return type:

ConjecturePlayground