kpi-formula-t5 0.2.0

A KPI calculation tool

Here’s your KPI Formula Usage Guide formatted in Markdown for your project:

# KPI Formula Usage Guide

## Table of Contents
1. [Installation](#installation)
2. [Basic Usage](#basic-usage)
3. [Data Loading](#data-loading)
4. [Data Operations](#data-operations)
5. [Table Operations](#table-operations)
6. [Data Export](#data-export)
7. [Complete Examples](#complete-examples)
8. [Common Issues](#common-issues)

---

## 1. Installation
```bash
pip install kpi-formula-t5
pip install pandas numpy openpyxl

---

2. Basic Usage

from kpi_formula import DataManager

# Initialize manager
manager = DataManager()

---

3. Data Loading

a) Load from CSV

# Load single CSV file
manager.load_data('sales_data.csv', 'sales')

Example CSV format:

date,product_id,customer_id,sales_amount,quantity
2023-01-01,P001,C1,1000,5
2023-01-02,P002,C2,1200,3

b) Load from DataFrame

import pandas as pd

df = pd.DataFrame({
    'A': [1, 2, 3],
    'B': [4, 5, 6]
})
manager.load_data(df, 'my_data')

---

4. Data Operations

a) Add Calculated Column

# Basic calculation
manager.add_column(
    data_name='sales',
    new_column='unit_price',
    expression='sales_amount / quantity'
)

# Calculation with condition
manager.add_column(
    data_name='sales',
    new_column='total_with_tax',
    expression='sales_amount * 1.1'  # 10% tax
)

b) Compute Operations

# Sum
total = manager.compute(
    data_name='sales',
    columns=['sales_amount'],
    operation='sum'
)

# Average
average = manager.compute(
    data_name='sales',
    columns=['unit_price'],
    operation='mean'
)

Supported operations:

• 'sum': Sum
• 'mean': Average
• 'max': Maximum
• 'min': Minimum
• 'count': Count

---

5. Table Operations

a) Basic Join

# Load two datasets
manager.load_data('sales_data.csv', 'sales')
manager.load_data('customer_data.csv', 'customers')

# Join operation
manager.join(
    left_name='sales',
    right_name='customers',
    left_on='customer_id',
    right_on='customer_id',
    how='left',
    result_name='sales_with_customer'
)

b) Multi-Column Join

manager.join(
    left_name='sales',
    right_name='customers',
    left_on=['customer_id', 'region'],
    right_on=['id', 'region'],
    how='inner',
    result_name='matched_sales'
)

Join Types:

• how='left': Left join
• how='right': Right join
• how='inner': Inner join
• how='outer': Outer join

---

6. Data Export

a) CSV Export

manager.export_data('sales', 'exports/sales.csv')

b) Excel Export

manager.export_data(
    'sales',
    'exports/sales.xlsx',
    format='excel',
    sheet_name='Sales Data'
)

c) JSON Export

manager.export_data(
    'sales',
    'exports/sales.json',
    format='json',
    orient='records'
)

d) Summary Export

manager.export_summary('sales', 'exports/sales_summary.json')

---

7. Complete Examples

from kpi_formula import DataManager

# Initialize
manager = DataManager()

try:
    # 1. Load data
    manager.load_data('sales_data.csv', 'sales')
    manager.load_data('customer_data.csv', 'customers')

    # 2. Add calculated column
    manager.add_column(
        data_name='sales',
        new_column='unit_price',
        expression='sales_amount / quantity'
    )

    # 3. Join data
    manager.join(
        left_name='sales',
        right_name='customers',
        left_on='customer_id',
        right_on='customer_id',
        how='left',
        result_name='full_data'
    )

    # 4. Compute statistics
    total_sales = manager.compute(
        data_name='full_data',
        columns=['sales_amount'],
        operation='sum'
    )
    print(f"Total sales: {total_sales}")

    # 5. Export results
    manager.export_data(
        'full_data',
        'exports/analysis_results.xlsx',
        format='excel',
        sheet_name='Sales Analysis'
    )

except Exception as e:
    print(f"Error: {str(e)}")

---

8. Common Issues

a) Import Errors

Make sure all required dependencies are installed:

pip install pandas numpy openpyxl

b) File Path Errors

Use absolute paths or ensure relative paths are correct:

import os
file_path = os.path.join(os.getcwd(), 'data', 'sales.csv')
manager.load_data(file_path, 'sales')

c) Memory Issues

For large datasets, consider batch processing or sampling:

# Read first 1000 rows
import pandas as pd
df = pd.read_csv('large_file.csv', nrows=1000)
manager.load_data(df, 'sample_data')

d) Data Type Errors

Ensure correct data types:

# Convert data types before loading
df['sales_amount'] = pd.to_numeric(df['sales_amount'], errors='coerce')

---

For more information and updates, please visit our GitHub repository.