Tutorial on `healthsciencecalculator` Package usage

In this tutorial, we will demonstrate how to use the functions provided in your package to analyze health metrics for a small dataset of individuals. By the end of this tutorial, you will know how to calculate Body Mass Index (BMI), Basal Metabolic Rate (BMR), and Total Daily Energy Expenditure (TDEE). This step-by-step guide includes explanations alongside code examples to help you understand how to use the package effectively.

Setting Up Your Environment

Before diving into calculations, ensure your package is installed and properly imported. We’ll begin by loading the package and defining our dataset.

import sys
sys.path.append("../src/healthsciencecalculator")

import pandas as pd 
from healthsciencecalculator import get_bmi, get_bmr, get_tdee, BMIResult,unit_convert

---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
Cell In[1], line 5
      2 sys.path.append("../src/healthsciencecalculator")
      4 import pandas as pd 
----> 5 from healthsciencecalculator import get_bmi, get_bmr, get_tdee, BMIResult,unit_convert

ImportError: cannot import name 'BMIResult' from 'healthsciencecalculator' (/home/docs/checkouts/readthedocs.org/user_builds/healthsciencecalculator/checkouts/latest/src/healthsciencecalculator/__init__.py)

Create sample data

## **Sample dataset**
test_data = [
    {"weight": 70.0, "height": 1.75, "age": 25, "sex": "male", "activity_level": "moderately active"},
    {"weight": 55.0, "height": 1.62, "age": 30, "sex": "female", "activity_level": "lightly active"},
    {"weight": 90.0, "height": 1.80, "age": 40, "sex": "male", "activity_level": "very active"},
    {"weight": 68.0, "height": 1.65, "age": 28, "sex": "female", "activity_level": "sedentary"},
    {"weight": 75.0, "height": 1.70, "age": 35, "sex": "male", "activity_level": "extra active"},
]

test_df = pd.DataFrame(test_data)  

Our dataset consists of five individuals, each with attributes like weight, height, age, sex, and activity level. We will use these attributes to calculate various health metrics. The functions provided in healthsciencecalculator make these calculations straightforward and reusable.

`get_bmi` Function

Description

Calculates Body Mass Index (BMI) and classifies it into standard health categories.

Parameters

Parameter	Type	Description	Constraints
`weight`	float	Weight in kilograms (kg)	Must be a positive number
`height`	float	Height in meters (m)	Must be a positive number

Returns

BMIResult dataclass containing:

bmi (float): BMI value rounded to 1 decimal
category (str): Health classification:
- Underweight: <18.5
- Healthy: 18.5-24.9
- Overweight: 25-29.9
- Class 1 obesity: 30-34.9
- Class 2 obesity: 35-39.9
- Class 3 obesity: ≥40

Raises

TypeError: Non-numeric inputs
ValueError: Non-positive inputs

Usage Examples

Our Health Science Calculator can be used separately. For example, if you just want to calculate the BMI for one person, you can do that by just calling the get_bmi function, and manually input each person’s height and weight in m and kg as specified above. In return, you will get a BMIResult class, which you can retrieve the specs individually with .bmi for bmi and .category for category.

Below, I will provide examples for some of the categories.

Healthy

from healthsciencecalculator import get_bmi

# Test case: {"weight": 70.0, "height": 1.75, ...}
result = get_bmi(weight=70.0, height=1.75)
print(result)  # Output: BMIResult(bmi=22.9, category='healthy')
print("BMI:", result.bmi)
print("Category:", result.category)

BMIResult(bmi=22.9, category='healthy')
BMI: 22.9
Category: healthy

Underweight

# Test case: {"weight": 35.0, "height": 1.70, ...}
result = get_bmi(weight=35.0, height=1.70)
print(result) # Output: BMIResult(bmi=12.1, category='underweight')
print("BMI:", result.bmi)
print("Category:", result.category)

BMIResult(bmi=12.1, category='underweight')
BMI: 12.1
Category: underweight

Overweight

# Test case: {"weight": 68.0, "height": 1.65, ...}
result = get_bmi(weight=68.0, height=1.65)
print(result)  # Output: BMIResult(bmi=25.0, category='overweight')
print("BMI:", result.bmi)
print("Category:", result.category)

BMIResult(bmi=25.0, category='overweight')
BMI: 25.0
Category: overweight

Applying On Dataframe

Similarly, the Health Science Calculator functions can be applied to a dataframe of your choosing. In the start, we have provided with you with a test data frame. Below, we will demostrate how to apply it and get extra BMI information columns on it.

test_df['bmi'] = test_df.apply(lambda x: get_bmi(x['weight'], x['height']).bmi, axis=1)
test_df['category'] = test_df.apply(lambda x: get_bmi(x['weight'], x['height']).category, axis=1)


test_df

	weight	height	age	sex	activity_level	bmi	category
0	70.0	1.75	25	male	moderately active	22.9	healthy
1	55.0	1.62	30	female	lightly active	21.0	healthy
2	90.0	1.80	40	male	very active	27.8	overweight
3	68.0	1.65	28	female	sedentary	25.0	overweight
4	75.0	1.70	35	male	extra active	26.0	overweight

`unit_convert` Function

Description

Converts values from one unit to another.

Parameters

Parameter	Type	Description
`value`	float	The numeric value to be converted.
`input_unit`	str	The unit of input value.
`output_unit`	str	The desired unit of output value.

Supported Units

Type	Unit
`Length`	meter(m), centimeter(cm), foot(feet), inch(inch)
`Weight`	kilogram(kg), gram(g), stone(stone), pound(lbs)
`Volume`	liter(L), milliliter(mL)
`Concentration`	milligram per deciliter(mg/dL), millimole per liter(mmol/L)
`Temperature`	celsius(C), fahrenheit(F)

Example 1: Length

# meter to foot
length = unit_convert(1,"m","feet")
print(length)

3.28

Example 2: Weight

# kilogram to gram
weight = unit_convert(1,"kg","g")
print(weight)

1000.0

Example 3: Volume

# liter to milliliter
volume = unit_convert(1,"L","mL")
print(volume)

1000.0

Example 4: Concentration

# milligram per deciliter to millimole per liter
concentration = unit_convert(1,"mg/dL","mmol/L")
print(concentration)

0.06

Example 5: Temperature

# Celsius to Fahrenheit
temperature = unit_convert(1,"C","F")
print(temperature)

33.8

Apply on dataframe

Just like the BMI function, this can be applied on dataframes. Since we will be working on BMR which require height in centimeters, let’s convert height in test date above from meters to centermeters in a new column

test_df['height_cm'] = test_df.apply(lambda x: unit_convert(x['height'],'m','cm'),axis=1)

test_df

	weight	height	age	sex	activity_level	bmi	category	height_cm
0	70.0	1.75	25	male	moderately active	22.9	healthy	175.0
1	55.0	1.62	30	female	lightly active	21.0	healthy	162.0
2	90.0	1.80	40	male	very active	27.8	overweight	180.0
3	68.0	1.65	28	female	sedentary	25.0	overweight	165.0
4	75.0	1.70	35	male	extra active	26.0	overweight	170.0

`get_bmr` Function

Basal Metabolic Rate (BMR) represents the number of calories an individual burns at rest to maintain vital functions like breathing and circulation. We will calculate BMR using the get_bmr function.

This step highlights how individual factors like age, sex, and height influence calorie needs.

The get_bmr function applies the Harris-Benedict equation, which is different for males and females:

For males:

BMR = 88.362 + (13.397 * weight) + (4.799 * height) - (5.677 * age)
For females:

BMR = 447.593 + (9.247 * weight) + (3.098 * height) - (4.330 * age)

Example application for male

male_bmr = get_bmr(weight=70, height=175, age=25, sex="male")

male_bmr

1724.052

Example application for female

female_bmr = get_bmr(weight=60, height=165, age=30, sex="female")

female_bmr

1383.683

Apply on dataframe

test_df['bmr'] = test_df.apply(lambda row: round(get_bmr(row['weight'], 
                                                         row['height_cm'], row['age'], 
                                                         row['sex']),3), axis=1)


test_df

	weight	height	age	sex	activity_level	bmi	category	height_cm	bmr
0	70.0	1.75	25	male	moderately active	22.9	healthy	175.0	1724.052
1	55.0	1.62	30	female	lightly active	21.0	healthy	162.0	1328.154
2	90.0	1.80	40	male	very active	27.8	overweight	180.0	1930.832
3	68.0	1.65	28	female	sedentary	25.0	overweight	165.0	1466.319
4	75.0	1.70	35	male	extra active	26.0	overweight	170.0	1710.272

Notes on parameters:

Input height must be in Centimeters.

Input Weight must be in Kilograms.

Valid sex values: “male” or “female”.

Errors for invalid or negative inputs.

Output is rounded to 3 decimal places.

`get_tdee` Function

Description

Calculates Total Daily Energy Expenditure (TDEE) based on BMR and activity level.

Parameters

Parameter	Type	Description	Constraints
`bmr`	float	Basal Metabolic Rate (BMR) in kcal/day	Must be a positive number
`activity_level`	str	The activity level of the individual, one of:	‘sedentary’, - ‘lightly active’, - ‘moderately active’, - ‘very active’, - ‘extra active’

Returns

tdee (float): representing the Total Daily Energy Expenditure (TDEE) in kcal/day.

Raises

ValueError: If bmr is less than or equal to 0 or if activity_level is not recognized.

Usage Examples

bmr = 1500.0  # Basal Metabolic Rate in kcal/day
activity_level = 'sedentary'  # Sedentary lifestyle (little or no exercise)

# Calculate TDEE
tdee = get_tdee(bmr, activity_level)
print(f"TDEE for sedentary: {tdee} kcal/day")

TDEE for sedentary: 1800.0 kcal/day

Applying on a Dataframe

test_df['tdee'] = test_df.apply(lambda x: get_tdee(x['bmr'], x['activity_level']), axis=1)

test_df

	weight	height	age	sex	activity_level	bmi	category	height_cm	bmr	tdee
0	70.0	1.75	25	male	moderately active	22.9	healthy	175.0	1724.052	2672.28060
1	55.0	1.62	30	female	lightly active	21.0	healthy	162.0	1328.154	1826.21175
2	90.0	1.80	40	male	very active	27.8	overweight	180.0	1930.832	3330.68520
3	68.0	1.65	28	female	sedentary	25.0	overweight	165.0	1466.319	1759.58280
4	75.0	1.70	35	male	extra active	26.0	overweight	170.0	1710.272	3249.51680

Tutorial on healthsciencecalculator Package usage

Setting Up Your Environment

Create sample data

get_bmi Function

Description

Parameters

Returns

Raises

Usage Examples

Healthy

Underweight

Overweight

Applying On Dataframe

unit_convert Function

Description

Parameters

Supported Units

Example 1: Length

Example 2: Weight

Example 3: Volume

Example 4: Concentration

Example 5: Temperature

Apply on dataframe

get_bmr Function

Example application for male

Example application for female

Apply on dataframe

Notes on parameters:

get_tdee Function

Description

Parameters

Returns

Raises

Usage Examples

Applying on a Dataframe

Tutorial on `healthsciencecalculator` Package usage

`get_bmi` Function

`unit_convert` Function

`get_bmr` Function

`get_tdee` Function