healthsciencecalculator
=======================

.. py:module:: healthsciencecalculator


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/healthsciencecalculator/healthsciencecalculator/index


Classes
-------

.. autoapisummary::

   healthsciencecalculator.BMIResult


Functions
---------

.. autoapisummary::

   healthsciencecalculator.get_bmi
   healthsciencecalculator.get_bmr
   healthsciencecalculator.get_tdee
   healthsciencecalculator.unit_convert


Package Contents
----------------

.. py:function:: get_bmi(weight: float, height: float) -> BMIResult

   Calculate Body Mass Index (BMI) and return detailed classification information.

   BMI is calculated as weight (kg) divided by height (m) squared.

   :param weight: Weight in kilograms
   :type weight: float
   :param height: Height in meters
   :type height: float

   :returns: A dataclass containing:
             - bmi (float): The calculated BMI value
             - category (str): BMI category, one of:
                 - 'underweight' (BMI < 18.5)
                 - 'healthy' (BMI 18.5-24.9)
                 - 'overweight' (BMI 25-29.9)
                 - 'class 1 obesity' (BMI 30-34.9)
                 - 'class 2 obesity' (BMI 35-39.9)
                 - 'class 3 obesity' (BMI >= 40)
             - risk_level (str): Associated health risk level
   :rtype: BMIResult

   :raises ValueError: If weight or height is not positive
   :raises TypeError: If weight or height is not a number


.. py:function:: get_bmr(weight: float, height: float, age: int, sex: str) -> float

   Computes Basal Metabolic Rate (BMR) using the Harris-Benedict equation.

   The BMR is an estimate of the number of calories your body needs to perform
   basic life-sustaining functions, such as breathing, circulation, and cell production.

   :param weight: Weight of the individual in kilograms.
   :type weight: float
   :param height: Height of the individual in centimeters.
   :type height: float
   :param age: Age of the individual in years.
   :type age: int
   :param sex: Biological sex of the individual. Accepted values are "male" or "female".
   :type sex: str

   :returns: The estimated BMR value in calories per day.
   :rtype: float

   .. rubric:: Notes

   The Harris-Benedict equation is used to calculate BMR:
   - 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)

   .. rubric:: Examples

   >>> get_bmr(70, 175, 25, "male")
   1668.872
   >>> get_bmr(60, 165, 30, "female")
   1392.247


.. py:function:: get_tdee(bmr: float, activity_level: str) -> float

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

   :param bmr: The Basal Metabolic Rate (must be positive).
   :type bmr: float
   :param activity_level: The activity level (allowed values: 'sedentary', 'lightly active',
                          'moderately active', 'very active', 'extra active').
   :type activity_level: str

   :returns: The calculated TDEE (kcal/day).
   :rtype: float

   :raises ValueError: If bmr <= 0 or activity_level is not recognized.

   .. rubric:: Notes

   Sample multipliers (you may choose different ones if needed):
     - sedentary: 1.2
     - lightly active: 1.375
     - moderately active: 1.55
     - very active: 1.725
     - extra active: 1.9


.. py:function:: unit_convert(value: float, input_unit: str, output_unit: str)

   Converts values from one unit to another.

   Supported measurement units:
   - Weight: kg, g, lb, stone
   - Length: m, cm, feet, inch
   - Temperature: C, F
   - Concentration: mg/dL, mmol/L
   - Volume: L, mL

   :param value: The numeric value to be converted.
   :type value: float
   :param input_unit: The unit of input value.
   :type input_unit: str
   :param output_unit: The desired unit of output value.
   :type output_unit: str

   :returns: The output value in desired unit.
   :rtype: float

   .. rubric:: Examples

   >>> unit_convert(1, "m", "cm")
   100


.. py:class:: BMIResult

   .. py:attribute:: bmi
      :type:  float


   .. py:attribute:: category
      :type:  str