brutus / boozelib

a Python module to calculate blood alcohol levels

boozelib

VERSION: 0.7.0

A Python module containing a couple of tools to calculate the blood alcohol content of people.

It's at home at GitHub: https://github.com/brutus/boozelib/.

As a side note: I created this library mainly to have a very simple module to try different Python testing and packaging best practice. This is in no way a serious medical approach and also accepts a rather big level of abstraction. Depending on your use case, this might be okay; but I would not deem it fit for serious health and / or legal stuff 😉 🍻

Install

You can install it from PyPi, it is known as boozelib and has no dependencies:

pip install --user boozelib

Usage

The two main functions are:

• get_blood_alcohol_content(age, weight, height, sex, volume, percent)

  Return the blood alcohol contents raise (per mill) for a person after a drink.

  Given a drink containing volume (ml) of percent (vol/vol) alcohol, for a person with age (years), weight (kg) and height (cm) — using a formular for "female body types" if sex is true.

• get_blood_alcohol_degradation(age, weight, height, sex, minutes=1, degradation=None)

  Return the alcohol degradation (per mill) for a person over minutes.

  For a person with age (years), weight (kg) and height (cm), using the formular for "female body types" if sex is true, over the given minutes. If degradation is not set, ALCOHOL_DEGRADATION is used as default.

This uses some constants and one variable you might want to review:

• ALCOHOL_DEGRADATION: the default value for alcohol degradation; meaning the amount of alcohol (in gram) your body is degrading per minute, per kilogram body weight. This is usually a value between 0.0017 and 0.0025 (about 0.1—0.2 per thousand per hour).

Examples

Return the blood alcohol contents raise (per mill) for a person after a drink:

from boozelib import get_blood_alcohol_content

get_blood_alcohol_content(
	age=32, weight=48, height=162, sex=True, volume=500, percent=4.9
)
# ⇒ 0.5480779730398769

And to calculate alcohol degradation:

from boozelib import get_blood_alcohol_degradation

get_blood_alcohol_degradation(
	age=32, weight=48, height=162, sex=True, minutes=60
)
# ⇒ 0.20133476560648536

You can change the default for alcohol degradation globally via setting boozelib.ALCOHOL_DEGRADATION. Or change the value for alcohol degradation per call:

get_blood_alcohol_degradation(
	age=32, weight=48, height=162, sex=True, minutes=60, degradation=0.002
)
# ⇒ 0.16106781248518828

Documentation

See the source or the documentation for more information and the used formulas.

Development Setup

Poetry is used to manage a virtual environment for the development setup.

A Makefile is provided, that collects some common tasks. You have to run the following once, to setup your environment:

make setup

Testing

nox is used as a test runner (with ward as the framework). If you have the development environment activated, you can just run:

make tests

If something fails, please get in touch.

Thanks and Contributions

• Big hugs to Mathilda for hanging around and helping me figuring out all that math and biology stuff.

If you find bugs, issues or anything else, please use the issue tracker on GitHub. Issues and PRs are welcome ❤️

boozelib's Issues

Help with documentation

Thank you for creating this library! I'm having some trouble understanding the concepts of BAC "raise" and "degradation". Can you please help me understand if/how I can use your library to model the following scenario:

- 1. Drink 1st beer (5%, 350ml), 6:00 - 6:30pm
- 2. Drink 2nd beer (5%, 350ml), 6:30 - 7:00pm
- 3. Drink 3rd beer (5%, 350ml), 7:00 - 7:15pm
- Finally, I want to calculate my BAC at 8:00pm and again at 8:30pm.

Thanks in advance for any help you can offer! :)

Alcohol degradation too high?

The source code and documentation tells that Alcohol degradation average is 0.15 g/kg per hour (0.0025 per minute).

boozelib/src/boozelib.py

Line 84 in afead01

ALCOHOL_DEGRADATION: float = 0.0025 #: for kg body weight per minute (g)

This seems too high, most sources say that alcohol is eliminated from body about 0.1 g/kg.

Roughly one gram of alcohol per ten kilograms of bodyweight is metabolised in one hour in the case of an adult in normal condition.
https://www.mycalculators.net/health/alcohol-calculator/how-long-does-alcohol-stay-in-your-system

Although rates vary widely, the “average” metabolic capacity to remove alcohol is about 170 to 240 g per day for a person with a body weight of 70 kg. This would be equivalent to an average metabolic rate of about 7 g/hr - -
https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3484320/

However, the page
https://www.nutrientsreview.com/alcohol/absorption-metabolism-elimination-factors.html
says The average alcohol elimination rate in mild and moderate drinkers is estimated to 0.015 g/100 mL blood/hour.
Maybe the invalid value 0.15 has been derived from the code here?

AttributeError: module 'boozelib' has no attribute 'get_blood_alcohol_degradation'

See details here: https://gist.github.com/nikhilmaddirala/f28b81b4ac829e8b7f5d515368fd4897

Initial Update

The bot created this issue to inform you that pyup.io has been set up on this repo.
Once you have closed it, the bot will open pull requests for updates as soon as they are available.