{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# **Tutorial on `healthsciencecalculator` Package usage**\n", "\n", "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.\n", "\n", "## **Setting Up Your Environment**\n", "Before diving into calculations, ensure your package is installed and properly imported. We'll begin by loading the package and defining our dataset.\n" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "import sys\n", "sys.path.append(\"../src/healthsciencecalculator\")\n", "\n", "import pandas as pd \n", "from healthsciencecalculator import get_bmi, get_bmr, get_tdee, BMIResult,unit_convert" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Create sample data" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "\n", "## **Sample dataset**\n", "test_data = [\n", " {\"weight\": 70.0, \"height\": 1.75, \"age\": 25, \"sex\": \"male\", \"activity_level\": \"moderately active\"},\n", " {\"weight\": 55.0, \"height\": 1.62, \"age\": 30, \"sex\": \"female\", \"activity_level\": \"lightly active\"},\n", " {\"weight\": 90.0, \"height\": 1.80, \"age\": 40, \"sex\": \"male\", \"activity_level\": \"very active\"},\n", " {\"weight\": 68.0, \"height\": 1.65, \"age\": 28, \"sex\": \"female\", \"activity_level\": \"sedentary\"},\n", " {\"weight\": 75.0, \"height\": 1.70, \"age\": 35, \"sex\": \"male\", \"activity_level\": \"extra active\"},\n", "]\n", "\n", "test_df = pd.DataFrame(test_data) \n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## **`get_bmi` Function**\n", "\n", "### Description\n", "Calculates Body Mass Index (BMI) and classifies it into standard health categories.\n", "\n", "### Parameters\n", "| Parameter | Type | Description | Constraints |\n", "|-----------|--------|-------------------------------|---------------------------|\n", "| `weight` | float | Weight in kilograms (kg) | Must be a positive number |\n", "| `height` | float | Height in meters (m) | Must be a positive number |\n", "\n", "### Returns\n", "`BMIResult` dataclass containing:\n", "- `bmi` (float): BMI value rounded to 1 decimal\n", "- `category` (str): Health classification:\n", " - Underweight: <18.5\n", " - Healthy: 18.5-24.9\n", " - Overweight: 25-29.9\n", " - Class 1 obesity: 30-34.9\n", " - Class 2 obesity: 35-39.9\n", " - Class 3 obesity: ≥40\n", "\n", "### Raises\n", "- `TypeError`: Non-numeric inputs\n", "- `ValueError`: Non-positive inputs" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Usage Examples\n", "\n", "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.\n", "\n", "Below, I will provide examples for some of the categories." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Healthy" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "BMIResult(bmi=22.9, category='healthy')\n", "BMI: 22.9\n", "Category: healthy\n" ] } ], "source": [ "from healthsciencecalculator import get_bmi\n", "\n", "# Test case: {\"weight\": 70.0, \"height\": 1.75, ...}\n", "result = get_bmi(weight=70.0, height=1.75)\n", "print(result) # Output: BMIResult(bmi=22.9, category='healthy')\n", "print(\"BMI:\", result.bmi)\n", "print(\"Category:\", result.category)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Underweight" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "BMIResult(bmi=12.1, category='underweight')\n", "BMI: 12.1\n", "Category: underweight\n" ] } ], "source": [ "# Test case: {\"weight\": 35.0, \"height\": 1.70, ...}\n", "result = get_bmi(weight=35.0, height=1.70)\n", "print(result) # Output: BMIResult(bmi=12.1, category='underweight')\n", "print(\"BMI:\", result.bmi)\n", "print(\"Category:\", result.category)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Overweight\n" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "BMIResult(bmi=25.0, category='overweight')\n", "BMI: 25.0\n", "Category: overweight\n" ] } ], "source": [ "# Test case: {\"weight\": 68.0, \"height\": 1.65, ...}\n", "result = get_bmi(weight=68.0, height=1.65)\n", "print(result) # Output: BMIResult(bmi=25.0, category='overweight')\n", "print(\"BMI:\", result.bmi)\n", "print(\"Category:\", result.category)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Applying On Dataframe\n", "\n", "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." ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
weightheightagesexactivity_levelbmicategory
070.01.7525malemoderately active22.9healthy
155.01.6230femalelightly active21.0healthy
290.01.8040malevery active27.8overweight
368.01.6528femalesedentary25.0overweight
475.01.7035maleextra active26.0overweight
\n", "
" ], "text/plain": [ " weight height age sex activity_level bmi category\n", "0 70.0 1.75 25 male moderately active 22.9 healthy\n", "1 55.0 1.62 30 female lightly active 21.0 healthy\n", "2 90.0 1.80 40 male very active 27.8 overweight\n", "3 68.0 1.65 28 female sedentary 25.0 overweight\n", "4 75.0 1.70 35 male extra active 26.0 overweight" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "test_df['bmi'] = test_df.apply(lambda x: get_bmi(x['weight'], x['height']).bmi, axis=1)\n", "test_df['category'] = test_df.apply(lambda x: get_bmi(x['weight'], x['height']).category, axis=1)\n", "\n", "\n", "test_df" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## **`unit_convert` Function**\n", "\n", "### Description\n", "Converts values from one unit to another.\n", "\n", "### Parameters\n", "| Parameter | Type | Description | \n", "|-----------|--------|-------------------------------|\n", "| `value` | float | The numeric value to be converted. | \n", "| `input_unit` | str | The unit of input value. | \n", "| `output_unit` | str | The desired unit of output value. | " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Supported Units\n", "| Type | Unit |\n", "|-----------|--------------------------|\n", "| `Length` | meter(m), centimeter(cm), foot(feet), inch(inch) |\n", "| `Weight` | kilogram(kg), gram(g), stone(stone), pound(lbs)|\n", "| `Volume` | liter(L), milliliter(mL) |\n", "| `Concentration` | milligram per deciliter(mg/dL), millimole per liter(mmol/L) |\n", "| `Temperature` | celsius(C), fahrenheit(F) |" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example 1: Length" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "3.28\n" ] } ], "source": [ "# meter to foot\n", "length = unit_convert(1,\"m\",\"feet\")\n", "print(length)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example 2: Weight" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "1000.0\n" ] } ], "source": [ "# kilogram to gram\n", "weight = unit_convert(1,\"kg\",\"g\")\n", "print(weight)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example 3: Volume" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "1000.0\n" ] } ], "source": [ "# liter to milliliter\n", "volume = unit_convert(1,\"L\",\"mL\")\n", "print(volume)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example 4: Concentration" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0.06\n" ] } ], "source": [ "# milligram per deciliter to millimole per liter\n", "concentration = unit_convert(1,\"mg/dL\",\"mmol/L\")\n", "print(concentration)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example 5: Temperature" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "33.8\n" ] } ], "source": [ "# Celsius to Fahrenheit\n", "temperature = unit_convert(1,\"C\",\"F\")\n", "print(temperature)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Apply on dataframe\n", "\n", "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" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
weightheightagesexactivity_levelbmicategoryheight_cm
070.01.7525malemoderately active22.9healthy175.0
155.01.6230femalelightly active21.0healthy162.0
290.01.8040malevery active27.8overweight180.0
368.01.6528femalesedentary25.0overweight165.0
475.01.7035maleextra active26.0overweight170.0
\n", "
" ], "text/plain": [ " weight height age sex activity_level bmi category height_cm\n", "0 70.0 1.75 25 male moderately active 22.9 healthy 175.0\n", "1 55.0 1.62 30 female lightly active 21.0 healthy 162.0\n", "2 90.0 1.80 40 male very active 27.8 overweight 180.0\n", "3 68.0 1.65 28 female sedentary 25.0 overweight 165.0\n", "4 75.0 1.70 35 male extra active 26.0 overweight 170.0" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "test_df['height_cm'] = test_df.apply(lambda x: unit_convert(x['height'],'m','cm'),axis=1)\n", "\n", "test_df" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## **`get_bmr` Function**\n", "**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.\n", "\n", "This step highlights how individual factors like age, sex, and height influence calorie needs." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `get_bmr` function applies the **Harris-Benedict equation**, which is different for males and females:\n", "- For males:\n", "\n", " BMR = 88.362 + (13.397 * weight) + (4.799 * height) - (5.677 * age)\n", " \n", "\n", "- For females:\n", "\n", " BMR = 447.593 + (9.247 * weight) + (3.098 * height) - (4.330 * age)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example application for male" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "1724.052" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "male_bmr = get_bmr(weight=70, height=175, age=25, sex=\"male\")\n", "\n", "male_bmr" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example application for female" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "1383.683" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "female_bmr = get_bmr(weight=60, height=165, age=30, sex=\"female\")\n", "\n", "female_bmr" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Apply on dataframe" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
weightheightagesexactivity_levelbmicategoryheight_cmbmr
070.01.7525malemoderately active22.9healthy175.01724.052
155.01.6230femalelightly active21.0healthy162.01328.154
290.01.8040malevery active27.8overweight180.01930.832
368.01.6528femalesedentary25.0overweight165.01466.319
475.01.7035maleextra active26.0overweight170.01710.272
\n", "
" ], "text/plain": [ " weight height age sex activity_level bmi category \\\n", "0 70.0 1.75 25 male moderately active 22.9 healthy \n", "1 55.0 1.62 30 female lightly active 21.0 healthy \n", "2 90.0 1.80 40 male very active 27.8 overweight \n", "3 68.0 1.65 28 female sedentary 25.0 overweight \n", "4 75.0 1.70 35 male extra active 26.0 overweight \n", "\n", " height_cm bmr \n", "0 175.0 1724.052 \n", "1 162.0 1328.154 \n", "2 180.0 1930.832 \n", "3 165.0 1466.319 \n", "4 170.0 1710.272 " ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "test_df['bmr'] = test_df.apply(lambda row: round(get_bmr(row['weight'], \n", " row['height_cm'], row['age'], \n", " row['sex']),3), axis=1)\n", "\n", "\n", "test_df" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### **Notes on parameters:**\n", "\n", "Input height must be in Centimeters.\n", "\n", "Input Weight must be in Kilograms.\n", "\n", "Valid sex values: \"male\" or \"female\".\n", "\n", "Errors for invalid or negative inputs.\n", "\n", "Output is rounded to 3 decimal places." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## **`get_tdee` Function**\n", "\n", "### Description\n", "Calculates Total Daily Energy Expenditure (TDEE) based on BMR and activity level.\n", "\n", "### Parameters\n", "| Parameter | Type | Description | Constraints |\n", "|-----------|--------|-------------------------------|---------------------------|\n", "| `bmr` | float | Basal Metabolic Rate (BMR) in kcal/day | Must be a positive number |\n", "| `activity_level` | str | The activity level of the individual, one of: | 'sedentary', - 'lightly active', - 'moderately active', - 'very active', - 'extra active' |\n", "\n", "### Returns\n", "`tdee` (float): representing the Total Daily Energy Expenditure (TDEE) in kcal/day.\n", "\n", "### Raises\n", "`ValueError`: If bmr is less than or equal to 0 or if activity_level is not recognized.\n", "### Usage Examples\n" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "TDEE for sedentary: 1800.0 kcal/day\n" ] } ], "source": [ "bmr = 1500.0 # Basal Metabolic Rate in kcal/day\n", "activity_level = 'sedentary' # Sedentary lifestyle (little or no exercise)\n", "\n", "# Calculate TDEE\n", "tdee = get_tdee(bmr, activity_level)\n", "print(f\"TDEE for sedentary: {tdee} kcal/day\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Applying on a Dataframe" ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
weightheightagesexactivity_levelbmicategoryheight_cmbmrtdee
070.01.7525malemoderately active22.9healthy175.01724.0522672.28060
155.01.6230femalelightly active21.0healthy162.01328.1541826.21175
290.01.8040malevery active27.8overweight180.01930.8323330.68520
368.01.6528femalesedentary25.0overweight165.01466.3191759.58280
475.01.7035maleextra active26.0overweight170.01710.2723249.51680
\n", "
" ], "text/plain": [ " weight height age sex activity_level bmi category \\\n", "0 70.0 1.75 25 male moderately active 22.9 healthy \n", "1 55.0 1.62 30 female lightly active 21.0 healthy \n", "2 90.0 1.80 40 male very active 27.8 overweight \n", "3 68.0 1.65 28 female sedentary 25.0 overweight \n", "4 75.0 1.70 35 male extra active 26.0 overweight \n", "\n", " height_cm bmr tdee \n", "0 175.0 1724.052 2672.28060 \n", "1 162.0 1328.154 1826.21175 \n", "2 180.0 1930.832 3330.68520 \n", "3 165.0 1466.319 1759.58280 \n", "4 170.0 1710.272 3249.51680 " ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\n", "test_df['tdee'] = test_df.apply(lambda x: get_tdee(x['bmr'], x['activity_level']), axis=1)\n", "\n", "test_df\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [] } ], "metadata": { "kernelspec": { "display_name": "dsci524", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.11" } }, "nbformat": 4, "nbformat_minor": 4 }