Expressions - Additory Documentation

What are Expressions?

Expressions are pre-built calculations that you can apply to your data. Additory includes 12 built-in health and fitness expressions that calculate common metrics like BMI, body surface area, and fitness scores.

How to use expressions:

Use add.expression_name(df) to apply calculations
Expressions require specific column names (see examples below)
Results are added as new columns to your dataframe

⚠️ Important: Expressions require specific column names. For example, BMI requires weight_kg and height_m, not generic names like weight or height. See the examples below for the exact column names required by each expression.

🚀 Basic Usage Example

Scenario: You have patient data and want to calculate BMI and body surface area.

Setup: Create sample patient data

import pandas as pd
import additory as add

# Patient data with height and weight
# Note: Expressions require specific column names
patients = pd.DataFrame({
    'patient_id': [1, 2, 3, 4, 5],
    'name': ['John Doe', 'Jane Smith', 'Mike Brown', 'Sarah Lee', 'Tom Wilson'],
    'height_m': [1.75, 1.62, 1.80, 1.68, 1.72],  # meters
    'weight_kg': [70, 58, 85, 62, 75],           # kilograms
    'age_years': [35, 28, 42, 31, 38]
})

print("Original patient data:")
print(patients)

Calculate BMI using expression

# Calculate BMI (Body Mass Index)
result = add.bmi(patients)

print("\nWith BMI calculated:")
print(result)

Output

Original patient data:
   patient_id       name  height_m  weight_kg  age_years
0           1   John Doe      1.75         70         35
1           2  Jane Smith      1.62         58         28
2           3  Mike Brown      1.80         85         42
3           4   Sarah Lee      1.68         62         31
4           5  Tom Wilson      1.72         75         38

With BMI calculated:
   patient_id       name  height_m  weight_kg  age_years        bmi
0           1   John Doe      1.75         70         35  22.857143
1           2  Jane Smith      1.62         58         28  22.095808
2           3  Mike Brown      1.80         85         42  26.234568
3           4   Sarah Lee      1.68         62         31  21.967120
4           5  Tom Wilson      1.72         75         38  25.347394

🎯 Advanced Usage Example

Scenario: You want to calculate multiple health metrics for a comprehensive health assessment.

Setup: Comprehensive health data

import pandas as pd
import additory as add

# Comprehensive health data
# Note: Expressions require specific column names
health_data = pd.DataFrame({
    'patient_id': [1, 2, 3, 4, 5],
    'name': ['John Doe', 'Jane Smith', 'Mike Brown', 'Sarah Lee', 'Tom Wilson'],
    'height_m': [1.75, 1.62, 1.80, 1.68, 1.72],      # meters
    'height_cm': [175, 162, 180, 168, 172],          # centimeters
    'weight_kg': [70, 58, 85, 62, 75],               # kilograms
    'waist_cm': [85, 68, 95, 72, 88],                # centimeters
    'hip_cm': [95, 92, 102, 96, 98],                 # centimeters
    'total_cholesterol': [200, 180, 240, 190, 210],  # mg/dL
    'hdl_cholesterol': [50, 60, 40, 55, 45]          # mg/dL
})

print("Comprehensive health data:")
print(health_data)

Calculate multiple health metrics

# Calculate BMI
result = add.bmi(health_data)

# Calculate Body Surface Area
result = add.bsa(result)

# Calculate Waist-Hip Ratio
result = add.waist_hip_ratio(result)

# Calculate Cholesterol Ratio
result = add.cholesterol_ratio(result)

print("\nWith all health metrics calculated:")
print(result[['name', 'bmi', 'bsa', 'waist_hip_ratio', 'cholesterol_ratio']])

Output

Comprehensive health data:
   patient_id       name  height_m  height_cm  weight_kg  waist_cm  hip_cm  total_cholesterol  hdl_cholesterol
0           1   John Doe      1.75        175         70        85      95                200               50
1           2  Jane Smith      1.62        162         58        68      92                180               60
2           3  Mike Brown      1.80        180         85        95     102                240               40
3           4   Sarah Lee      1.68        168         62        72      96                190               55
4           5  Tom Wilson      1.72        172         75        88      98                210               45

With all health metrics calculated:
        name        bmi       bsa  waist_hip_ratio  cholesterol_ratio
0   John Doe  22.857143  1.834615         0.894737           4.000000
1  Jane Smith  22.100290  1.598847         0.739130           3.000000
2  Mike Brown  26.234568  2.041463         0.931373           6.000000
3   Sarah Lee  21.967120  1.693847         0.750000           3.454545
4  Tom Wilson  25.351541  1.871615         0.897959           4.666667

📚 Complete Expressions List

add.bmi(df)

Body Mass Index - measures body fat based on height and weight

Requires: weight_kg, height_m

add.bsa(df)

Body Surface Area - used in medical dosage calculations

Requires: weight_kg, height_cm

add.waist_hip_ratio(df)

Waist-to-Hip Ratio - indicator of health risk

Requires: waist_cm, hip_cm

add.bmr(df)

Basal Metabolic Rate - calories burned at rest

Requires: weight_kg, height_cm, age_years, gender

add.ideal_body_weight(df)

Ideal body weight based on height and gender

Requires: height_cm, gender

add.blood_pressure_category(df)

Blood pressure category (Normal, Elevated, Hypertension, etc.)

Requires: systolic_bp, diastolic_bp

add.cholesterol_ratio(df)

Total cholesterol to HDL ratio

Requires: total_cholesterol, hdl_cholesterol

add.age_category(df)

Age category (Minor, Young Adult, Adult, Senior, etc.)

Requires: age_years

add.body_fat_percentage(df)

Estimated body fat percentage

Requires: waist_cm, neck_cm, height_cm, hip_cm (females), gender

⚠️ Important Notes

Column Detection: Expressions automatically detect required columns by name.

Missing Columns: If required columns are missing, expressions will show helpful error messages.

Units: Expressions expect standard units (cm for height, kg for weight, etc.).

Medical Disclaimer: These calculations are for informational purposes only and should not replace professional medical advice.

🎯 Quick Reference

Basic expression usage patterns

# Single expression
result = add.bmi(df)

# Chain multiple expressions
result = add.bmi(df)
result = add.bsa(result)
result = add.bmr(result)

# Or chain in one line
result = add.fitness_score(add.bmr(add.bsa(add.bmi(df))))

# Check what expressions are available
print(dir(add))  # Shows all available functions and expressions