A Python module for ensuring structural isomorphism and commutative consistency across data transformations.
This toolkit provides mathematically reversible mappings between pandas.DataFrame, dict, CSV, and JSON formats—preserving data structure, types, and semantics regardless of transformation order.
- Bijective Mappings: Each transformation has a unique and total inverse
- Structure Integrity: Index, column types, and ordering are preserved
- Semantic Equivalence: Original data meaning remains unchanged
- Order-Invariance:
A → B → C≡A → C → B - Round-trip Identity:
T⁻¹ ∘ T(x) = xfor all supported types - Transformation Algebra: Composition, associativity, identity supported
pandas.DataFrame↔dict↔CSV↔JSON- Full interoperability under unified transformation rules
- Automatic type casting and structural validation
df → dict → csv → json → df # Exact round-trip equivalence
dict → csv → json → df → dict # Commutative, isomorphic recovery
These transformations preserve:
- Data fidelity (values and types)
- Index and column structure
- Missing value handling (e.g., NaN ≈ None)
pip install canonical-transformer==1.0.0
import pandas as pd
from canonical_transformer.morphisms import *
from canonical_transformer.isomorphisms import *
# Create sample DataFrame
df = pd.DataFrame({
'id': [1, 2, 3],
'name': ['Alice', 'Bob', 'Charlie'],
'value': [10.5, -20.3, 30.0],
'active': [True, False, True]
})
print("Original DataFrame:")
print(df)
print(f"Shape: {df.shape}, Types: {df.dtypes.tolist()}")
# Core isomorphism example: df → data → df
data_transformed = map_df_to_data(df=df) # data_transformed: dict representation
df_transformed = map_data_to_df(data=data_transformed) # df_transformed: DataFrame reconstructed from dict
print(f"\nIsomorphism check: {df.equals(df_transformed)}") # Should be True
print(f"Data structure preserved: {df.shape == df_transformed.shape}")# Identity morphism: df → data → df (should preserve structure)
df_identity = iD_df(df) # df_identity: DataFrame after identity transformation
print(f"\nIdentity isomorphism check: {df.equals(df_identity)}")
# Validate strict isomorphism (structure + values + types)
is_strict = validate_df_strict_isomorphism(df_ref=df, df=df_identity, option_verbose=True) # is_strict: Boolean for strict isomorphism
print(f"Strict isomorphism: {is_strict}")
# Validate pseudo isomorphism (structure only)
is_pseudo = validate_df_pseudo_isomorphism(df_ref=df, df=df_identity, option_verbose=True) # is_pseudo: Boolean for pseudo isomorphism
print(f"Pseudo isomorphism: {is_pseudo}")# Path 1: df → data → csv → data → df
df_to_csv = map_df_to_csv(df=df, file_folder='data/data-morphism', file_name='dataset-example.csv', encoding='utf-8-sig', option_verbose=True) # df_to_csv: DataFrame from CSV round-trip
print(f"\nPath 1 (df→csv→df) isomorphism: {df.equals(df_to_csv)}")
# Path 2: df → data → json → data → df
df_to_json = map_df_to_json(df=df, file_folder='data/data-morphism', file_name='json-example.json') # df_to_json: DataFrame to JSON transformation
data_json = map_json_to_data(file_folder='data/data-morphism', file_name='json-example.json') # data_json: dict data from JSON file
df_from_json = map_data_to_df(data=data_json) # df_from_json: DataFrame reconstructed from JSON
print(f"Path 2 (df→json→df) isomorphism: {df.equals(df_from_json)}")
# Path 3: df → csv → json → df (demonstrating commutativity)
df_csv = map_csv_to_df(file_folder='data/data-morphism', file_name='dataset-example.csv') # df_csv: DataFrame loaded from CSV
df_csv_json = map_df_to_json(df=df_csv, file_folder='data/data-morphism', file_name='json-from-csv.json') # df_csv_json: JSON transformation of CSV data
df_final = map_json_to_df(file_folder='data/data-morphism', file_name='json-from-csv.json') # df_final: Final DataFrame after full cycle
print(f"Path 3 (df→csv→json→df) isomorphism: {df.equals(df_final)}")# Demonstrate transformation commutativity
# T1: df → data → csv
# T2: df → data → json
# T3: csv → data → json
# All paths should lead to isomorphic results
path1_result = map_csv_to_json(file_folder='data/data-morphism', file_name='dataset-example.csv',
file_folder_json='data/data-morphism', file_name_json='commutative-test.json') # path1_result: JSON file path from CSV path
path2_result = map_df_to_json(df=df, file_folder='data/data-morphism', file_name='commutative-test2.json') # path2_result: JSON file path from DataFrame
# Load both results and compare
result1 = map_json_to_data(file_folder='data/data-morphism', file_name='commutative-test.json') # result1: dict data from path1
result2 = map_json_to_data(file_folder='data/data-morphism', file_name='commutative-test2.json') # result2: dict data from path2
commutative_check = validate_data_isomorphism(data_ref=result1, data=result2) # commutative_check: Boolean for commutativity
print(f"\nCommutative transformation check: {commutative_check}")# Real-world portfolio data transformation
portfolio_df = pd.DataFrame({ # portfolio_df: Original portfolio DataFrame
'ticker': ['AAPL', 'GOOGL', 'MSFT', 'TSLA'],
'shares': [100, 50, 75, 200],
'avg_price': [150.25, 2800.50, 320.75, 850.00],
'sector': ['Technology', 'Technology', 'Technology', 'Automotive']
})
print(f"\nPortfolio DataFrame:")
print(portfolio_df)
# Transform through multiple formats while preserving isomorphism
portfolio_data = map_df_to_data(df=portfolio_df) # portfolio_data: dict representation of portfolio
portfolio_csv = map_data_to_csv(data=portfolio_data, file_folder='data/data-morphism', file_name='portfolio-dataset.csv', encoding='utf-8-sig', option_verbose=True) # portfolio_csv: CSV file path
portfolio_json = map_data_to_json(data=portfolio_data, file_folder='data/data-morphism', file_name='portfolio-json.json', option_verbose=True) # portfolio_json: JSON file path
# Verify round-trip isomorphism
df_from_portfolio = map_csv_to_df(file_folder='data/data-morphism', file_name='portfolio-dataset.csv') # df_from_portfolio: DataFrame reconstructed from CSV
isomorphism_verified = validate_df_pseudo_isomorphism(df_ref=portfolio_df, df=df_from_portfolio, option_verbose=True) # isomorphism_verified: Boolean for isomorphism
print(f"Portfolio isomorphism verified: {isomorphism_verified}")# Prove identity morphism properties
print(f"\n=== Mathematical Properties ===")
# Identity: id ∘ f = f ∘ id = f
id_check1 = df.equals(iD_df(df))
id_check2 = df.equals(iD_df(iD_df(df)))
print(f"Identity property 1: {id_check1}")
print(f"Identity property 2: {id_check2}")
# Associativity: (f ∘ g) ∘ h = f ∘ (g ∘ h)
f = lambda x: map_df_to_data(x)
g = lambda x: map_data_to_csv(x, 'data/data-morphism', 'assoc-test.csv')
h = lambda x: map_csv_to_df('data/data-morphism', 'assoc-test.csv')
# (f ∘ g) ∘ h
left_assoc = h(g(f(df)))
# f ∘ (g ∘ h)
right_assoc = f(h(g(f(df))))
assoc_check = validate_df_pseudo_isomorphism(left_assoc, right_assoc)
print(f"Associativity property: {assoc_check}")
# Commutativity: f ∘ g = g ∘ f (for compatible transformations)
# Note: Not all transformations commute, but isomorphic ones do
print(f"Commutativity: Isomorphic transformations preserve structure regardless of order")- Injectivity: Each input maps to a unique output
- Surjectivity: All outputs can be traced back to inputs
- Bijectivity: Reversible one-to-one mapping
- Order Independence: Transformations commute
- Associativity: Grouping doesn't affect result
- Identity:
T⁻¹ ∘ T = id
- Structure Preservation: Index, type, ordering maintained
- Format Standardization: Consistent formatting across outputs
- Python >= 3.6
- pandas >= 2.2.3
- python-dateutil >= 2.9.0
- pytz >= 2024.2
- typing_extensions >= 4.12.2
- Structural isomorphism guaranteed
- Bidirectional reversible transformations
- Full commutative consistency
- Format and type standardization
- Number formatting utilities
- Sign-preserving float formatting
June Young Park
AI Systems Architect @ LIFE Asset Management
📧 juneyoungpaak@gmail.com
📍 TWO IFC, Yeouido, Seoul
LIFE Asset Management is a hedge fund management firm that integrates value investing and engagement strategies with quantitative modeling and AI infrastructure.
MIT License – see LICENSE file for details.