Merge branch 'main' into tdee

CONDUCT.md

@@ -6,21 +6,21 @@ In the interest of fostering an open and welcoming environment, we as contributo
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment include:
+### Behaviors that contributes to creating a positive environment include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using kind and inclusive language.  
+- Valuing and appreciating different views and opinions.  
+- Give and accept constructive feedback.  
+- Focusing on the collective good and growth of the team.  
+- Showing compassion and understanding toward others in the community.  
 
-Examples of unacceptable behavior by participants include:
+### unacceptable behaviors by participants include:
+
+- Using sexualized language or imagery or making unwelcome sexual advances or inappropriate gestures.  
+- Engaging in harassment, whether conducted publicly or privately.  
+- Sharing someone’s personal details, such as their physical or email address, without their explicit consent.  
+- Exhibiting any behavior that could reasonably be regarded as unprofessional or inappropriate in a professional context.  
 
-* The use of sexualized language or imagery and unwelcome sexual attention or advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Our Responsibilities
 
@@ -34,10 +34,16 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 
+## Procedure for reporting and dealing with unacceptable behaviour
+
+First strike - A written slack notice that outlines the violation of the team contract.
+Second strike - Reach out to the lab instructor or TAs of the issues with the teammate.
+
+
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant homepage](http://contributor-covenant.org/version/1/4), version 1.4.

CONTRIBUTING.md

@@ -42,14 +42,19 @@ If you are proposing a feature:
 
 Ready to contribute? Here's how to set up `healthsciencecalculator` for local development.
 
-1. Download a copy of `healthsciencecalculator` locally.
-2. Install `healthsciencecalculator` using `poetry`:
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/UBC-MDS/HealthScienceCalculator.git
+   cd healthsciencecalculator
+   ```
+3. Install `healthsciencecalculator` using `poetry`:
 
     ```console
     $ poetry install
     ```
 
-3. Use `git` (or similar) to create a branch for local development and make your changes:
+4. Use `git` (or similar) to create a branch for local development and make your changes:
 
     ```console
     $ git checkout -b name-of-your-bugfix-or-feature
@@ -59,13 +64,91 @@ Ready to contribute? Here's how to set up `healthsciencecalculator` for local de
 
 5. Commit your changes and open a pull request.
 
-## Pull Request Guidelines
+### Documentation
+
+We welcome:
+
+- Fixed typos
+- Improved explanations
+- New examples
+- Better organization
+- Translations
+
+## Style Guidelines
+
+- Code: Follow PEP 8 and project-specific conventions and NumPy-style docstrings
+- Commit messages: Follow conventional commits format
+- Documentation: Clear, concise, and complete
+- Tests: Unit tests for new features, regression tests for bugs
+
+## Development Process
+
+1. Make your changes in your feature branch
+2. Write or update tests as needed
+3. Update documentation to reflect any changes
+4. Run the test suite:
+   ```bash
+   poetry run pytest
+   poetry run pytest --cov=healthsciencecalculator
+   ```
+5. Run the linting checks:
+   ```bash
+   poetry run flake8
+   poetry run black .
+   poetry run mypy .
+   ```
+
+## Pull Request Process
+
+1. Update the README.md with details of significant changes
+2. Ensure all tests pass and code meets quality standards
+3. Update the documentation if needed. 
+
+  Example of good Numpy docstring:
+  ```python
+  def 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.
+
+    Parameters
+    ----------
+    weight : float
+        Weight in kilograms
+    height : float
+        Height in meters
+
+    Returns
+    -------
+    BMIResult
+        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
+    """
+
+  ```
+
+4. Link any relevant issues in the PR description
+5. Request review from maintainers
+
+### PR Checklist
+- [ ] Tests added/updated and passing
+- [ ] Documentation updated
+- [ ] Code follows project style guidelines
+- [ ] Commits are properly formatted and descriptive
+- [ ] Changes are described in CHANGELOG.md
 
-Before you submit a pull request, check that it meets these guidelines:
 
-1. The pull request should include additional tests if appropriate.
-2. If the pull request adds functionality, the docs should be updated.
-3. The pull request should work for all currently supported operating systems and versions of Python.
 
 ## Code of Conduct
 

README.md

@@ -1,6 +1,45 @@
 # healthsciencecalculator
 
-Calculates basic health indexes
+## Summary 
+
+This package healthsciencecalculator.py is designed to provide tools for calculating and analyzing important health metrics. It aims to support health professionals, researchers, and fitness enthusiasts by offering reliable functions to convert relevant units, compute Total Daily Energy Expenditure (TDEE), Basal Metabolic Rate (BMR), and Body Mass Index (BMI).
+
+## Functions 
+
+get_tdee
+
+    Description: Calculates Total Daily Energy Expenditure (TDEE) based on BMR and activity level.
+
+    Inputs: Weight, height, age, sex, and activity level.
+
+get_bmi
+
+    Description: Calculates Body Mass Index (BMI) and provides category classification.
+
+    Inputs: Weight and height.
+
+get_bmr
+
+    Description: Computes Basal Metabolic Rate (BMR) using the Harris-Benedict equation.
+
+    Inputs: Weight, height, age, and sex.
+
+convert_units
+
+    Description: convert between various health-related units such as weight (kg to lbs), temperature (Celsius to Fahrenheit), and length (cm to inches). This function simplifies converting clinical data for international research or patient records.
+
+
+## Python Ecosystem Fit
+
+The healthsciencecalculator.py package fits well within the broader Python ecosystem, complementing existing data science and health analysis libraries. There are several Python packages with similar functionalities, such as: 
+
+[`health-indicator](https://pypi.org/project/health-indicator/)
+    This package collects health indices like BMI and health indicators like birth rate
+
+[`health-records 0.0.7`]https://pypi.org/project/health-records/)
+    This package maintains personal health records in a text file that can be privately stored in your computer.
+
+The healthsciencecalculator.py package is unique in that it performs health-related calculations with high accuracy and precision, tailored specifically for healthcare professionals and data analysts.
 
 ## Installation
 
@@ -10,7 +49,18 @@ $ pip install healthsciencecalculator
 
 ## Usage
 
-- TODO
+
+After installation, you can start using the various functions provided by the package. 
+
+
+
+
+## Contributors
+
+Forgive Agbesi
+Hala Arar
+Jiayi Li
+Tengwei Wang
 
 ## Contributing
 
@@ -23,3 +73,6 @@ Interested in contributing? Check out the contributing guidelines. Please note t
 ## Credits
 
 `healthsciencecalculator` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
+
+## Contributors
+Forgive Agbesi, Jiayi Li, Hala Arar, Tengwei Wang

src/healthsciencecalculator/bmr.py

@@ -0,0 +1,38 @@
+#import
+def bmr(weight, height, age, sex):
+    """
+    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.
+
+    Parameters
+    ----------
+    weight : float
+        Weight of the individual in kilograms.
+    height : float
+        Height of the individual in centimeters.
+    age : int
+        Age of the individual in years.
+    sex : str
+        Biological sex of the individual. Accepted values are "male" or "female".
+
+    Returns
+    -------
+    float
+        The estimated BMR value in calories per day.
+
+    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)
+
+    Examples
+    --------
+    >>> bmr(70, 175, 25, "male")
+    1668.872
+    >>> bmr(60, 165, 30, "female")
+    1392.247
+    """
+

src/healthsciencecalculator/healthsciencecalculator.py

@@ -40,6 +40,39 @@ def get_bmi(
     return
 
 
+def unit_convert(value: float, input_unit: str, ouput_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
+
+    Parameters
+    ----------
+    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.
+    
+
+    Returns
+    -------
+    float
+        The output value in desired unit.
+
+    Examples
+    --------
+    >>> unit_convert(1, "m", "cm")
+    100
+    """
+
 
 def get_tdee(
     bmr: float, 
@@ -64,7 +97,4 @@ def get_tdee(
     >>> print(f"TDEE: {tdee:.2f} kcal/day")
     TDEE: 2310.00 kcal/day  # Example output, actual value depends on implementation
     """
-    pass
-
-
-
+    pass