DII Calculator

A validated Python implementation of the Dietary Inflammatory Index (DII) for nutritional epidemiology research.

Overview

The Dietary Inflammatory Index (DII) is a literature-derived, population-based scoring system that quantifies the inflammatory potential of an individual's diet. Originally developed by Shivappa et al. (2014), the DII has been used in over 1,000 peer-reviewed studies to examine relationships between diet and chronic disease.

This package provides:

Validated calculations matching the original methodology
All 45 DII food parameters with global reference values
Detailed output showing per-nutrient contributions
Visualization tools for research and publication
Command-line interface for batch processing

Installation

From PyPI (recommended)

pip install dii-calculator

Development installation

git clone https://github.com/strathlab-data/DII.git
cd DII
pip install -e ".[dev]"

Quick Start

import pandas as pd
from dii import calculate_dii

# Load your nutrient intake data
nutrients = pd.read_csv("your_data.csv")

# Calculate DII scores
results = calculate_dii(nutrients, id_column="participant_id")
print(results)

Output:

   participant_id  DII_score
0               1      -2.34
1               2       0.87
2               3       3.12

Methodology

The DII calculation follows a standardized four-step process for each nutrient:

Step 1: Z-score

z = (intake - global_mean) / global_sd

Where global_mean and global_sd are population-level statistics derived from 11 worldwide dietary datasets.

Step 2: Centered Percentile

percentile = 2 × Φ(z) - 1

Where Φ is the cumulative distribution function of the standard normal distribution. This transforms z-scores to the range [-1, +1].

Step 3: Weighted Contribution

contribution = percentile × inflammatory_weight

The inflammatory weight (range: -0.785 to +0.373) was derived from a systematic review of 1,943 peer-reviewed articles examining relationships between dietary factors and six inflammatory biomarkers: IL-1β, IL-4, IL-6, IL-10, TNF-α, and CRP.

Step 4: Total DII Score

DII = Σ contributions

Sum all nutrient contributions. Missing nutrients are excluded (not imputed).

Interpretation

DII Score Range	Category	Interpretation
< -4	Strongly anti-inflammatory	Diet rich in anti-inflammatory foods
-4 to -1	Anti-inflammatory	Generally healthy dietary pattern
-1 to +1	Neutral	Mixed dietary pattern
+1 to +4	Pro-inflammatory	Diet may promote inflammation
> +4	Strongly pro-inflammatory	Diet dominated by pro-inflammatory foods

Theoretical range: approximately -8.87 (maximally anti-inflammatory) to +7.98 (maximally pro-inflammatory) when all 45 nutrients are available.

Input Requirements

Data Format

Your input should be a pandas DataFrame with:

One row per participant/observation
Columns named to match the DII nutrient names exactly
Numeric values representing daily intake

Data Types

All nutrient values should be numeric. The package uses float64 precision internally for reproducibility. Non-numeric values are coerced to NaN with a warning.

Units Reference

⚠️ Units are critical for accurate DII calculation. Common errors include using mg instead of g for caffeine.

Macronutrients

Nutrient	Column Name	Unit	Global Mean	Global SD
Energy	`Energy`	kcal/day	2056	338
Carbohydrate	`Carbohydrate`	g/day	272.2	40
Protein	`Protein`	g/day	79.4	13.9
Total fat	`Total fat`	g/day	71.4	19.4
Fiber	`Fiber`	g/day	18.8	4.9

Fatty Acids

Nutrient	Column Name	Unit	Global Mean	Global SD
Saturated fat	`Saturated fat`	g/day	28.6	8
MUFA	`MUFA`	g/day	27	6.1
PUFA	`PUFA`	g/day	13.88	3.76
Trans fat	`Trans fat`	g/day	3.15	3.75
n-3 fatty acid	`n-3 fatty acid`	g/day	1.06	1.06
n-6 fatty acid	`n-6 fatty acid`	g/day	10.8	7.5
Cholesterol	`Cholesterol`	mg/day	279.4	51.2

Vitamins

Nutrient	Column Name	Unit	Global Mean	Global SD
Vitamin A	`Vitamin A`	RE/day	983.9	518.6
Vitamin B6	`vitamin B6`	mg/day	1.47	0.74
Vitamin B12	`vitamin B12`	µg/day	5.15	2.7
Vitamin C	`Vitamin C`	mg/day	118.2	43.46
Vitamin D	`Vitamin D`	µg/day	6.26	2.21
Vitamin E	`Vitamin E`	mg/day	8.73	1.49
Thiamin	`Thiamin`	mg/day	1.7	0.66
Riboflavin	`Riboflavin`	mg/day	1.7	0.79
Niacin	`Niacin`	mg/day	25.9	11.77
Folic acid	`Folic acid`	µg/day	273	70.7
Beta-carotene	`Beta-carotene`	µg/day	3718	1720

Minerals

Nutrient	Column Name	Unit	Global Mean	Global SD
Iron	`Iron`	mg/day	13.35	3.71
Magnesium	`Magnesium`	mg/day	310.1	139.4
Selenium	`Selenium`	µg/day	67	25.1
Zinc	`Zinc`	mg/day	9.84	2.19

Other Components

Nutrient	Column Name	Unit	Global Mean	Global SD
Alcohol	`Alcohol`	g/day	13.98	3.72
Caffeine	`Caffeine`	g/day ⚠️	8.05	6.67
Green/black tea	`Green/black tea`	g/day	1.69	1.53

Flavonoids

Nutrient	Column Name	Unit	Global Mean	Global SD
Flavan-3-ol	`Flavan-3-ol`	mg/day	95.8	85.9
Flavones	`Flavones`	mg/day	1.55	0.07
Flavonols	`Flavonols`	mg/day	17.7	6.79
Flavonones	`Flavonones`	mg/day	11.7	3.82
Anthocyanidins	`Anthocyanidins`	mg/day	18.05	21.14
Isoflavones	`Isoflavones`	mg/day	1.2	0.2

Spices & Herbs

Nutrient	Column Name	Unit	Global Mean	Global SD
Garlic	`Garlic`	g/day	4.35	2.9
Ginger	`Ginger`	g/day	59	63.2
Onion	`Onion`	g/day	35.9	18.4
Pepper	`Pepper`	g/day	10	7.07
Turmeric	`Turmeric`	mg/day	533.6	754.3
Saffron	`Saffron`	g/day	0.37	1.78
Eugenol	`Eugenol`	mg/day	0.01	0.08
Thyme/oregano	`Thyme/oregano`	mg/day	0.33	0.99
Rosemary	`Rosemary`	mg/day	1	15

Missing Data

Nutrients not in your data are automatically excluded from the DII sum
Individual missing values (NaN) for specific participants are excluded for that participant
A warning is issued if less than 25% of nutrients (11/45) are available
More nutrients = more accurate DII scores

Features

Detailed Output

Get per-nutrient contributions to understand what's driving each score:

detailed = calculate_dii(nutrients, detailed=True)

# View all columns
print(detailed.columns.tolist())
# ['Fiber', 'Fiber_zscore', 'Fiber_percentile', 'Fiber_contribution', 
#  'Alcohol', 'Alcohol_zscore', ... , 'DII_score']

# Examine contributions
contrib_cols = [c for c in detailed.columns if c.endswith('_contribution')]
print(detailed[contrib_cols].describe())

Visualization

Three turn-key visualization functions are included in the package (using matplotlib):

from dii import (
    plot_dii_distribution,
    plot_nutrient_contributions,
    plot_dii_categories_pie,
)

# Distribution histogram with category coloring
plot_dii_distribution(results, save_path="dii_distribution.png")

# Horizontal bar chart of nutrient contributions
plot_nutrient_contributions(detailed.iloc[0], save_path="contributions.png")

# Pie chart of DII categories
plot_dii_categories_pie(results, save_path="categories.png")

Command-Line Interface

# Basic usage
dii input.csv -o results.csv

# With detailed output
dii input.csv -o results.csv --detailed

# Specify ID column
dii input.csv -o results.csv --id-column participant_id

# List all supported nutrients with units
dii --nutrients

# Show help
dii --help

Templates

Ready-to-use templates are provided in the templates/ folder:

File	Description
`input_template.csv`	Empty CSV with all 45 nutrient columns
`analysis_template.ipynb`	Jupyter notebook workflow
`TEMPLATE_README.md`	Complete unit reference guide

Validation

Methodology

This implementation was validated against three independent sources:

Original R code from study statistician Jeanette M. Andrade, PhD, RDN (University of Florida)
Independent verification by Jiyan Aslan Ceylan (University of Florida, June 2025)
Cross-validation with the dietaryindex R package by Jiada (James) Zhan

Results

Metric	Value
Sample size	13,580 NHANES participants
Mean absolute error	< 1×10⁻¹⁰
Maximum absolute error	< 1×10⁻⁹
Pearson correlation	1.000000

Synthetic Test Cases

Three validation rows with mathematically-derived expected values are included in the sample data:

SEQN	Description	Expected DII	Calculated DII	Absolute Error
1	All nutrients at global mean	0.000000	0.000000	< 1×10⁻¹⁰
2	Maximally anti-inflammatory	-7.004394	-7.004394	< 1×10⁻⁹
3	Maximally pro-inflammatory	+7.004394	+7.004394	< 1×10⁻⁹

Precision

All calculations use IEEE 754 double precision (numpy.float64)
Infinity values from edge cases are converted to NaN
Validation tolerance: 1×10⁻¹⁰

For detailed validation results, see examples/validation.ipynb.

API Reference

Core Functions

`calculate_dii(nutrient_data, reference_df=None, id_column=None, detailed=False, validate_bounds=True)`

Calculate DII scores for a DataFrame of nutrient intakes.

Parameters:

nutrient_data (pd.DataFrame): Input data with nutrient columns
reference_df (pd.DataFrame, optional): Custom reference table
id_column (str, optional): Column name for participant IDs
detailed (bool): Return per-nutrient breakdown
validate_bounds (bool): Warn about extreme values

Returns: pd.DataFrame with DII scores

`get_available_nutrients()`

Returns a list of all 45 DII nutrient names.

`load_reference_table(custom_path=None)`

Load the DII reference table with weights and global statistics.

Visualization Functions

`plot_dii_distribution(dii_scores, title=..., save_path=None, show=True)`

Create a histogram of DII scores colored by inflammatory category.

`plot_nutrient_contributions(detailed_row, save_path=None, show=True)`

Create a horizontal bar chart showing each nutrient's contribution.

`plot_dii_categories_pie(dii_scores, save_path=None, show=True)`

Create a pie chart of anti-inflammatory, neutral, and pro-inflammatory categories.

Citation

If you use this package in your research, please cite both the software and the original methodology:

Software Citation

@software{clark_strath_2025_dii,
  author       = {Clark, Ted and Strath, Larissa},
  title        = {{dii-calculator: Dietary Inflammatory Index Calculator for Python}},
  year         = {2025},
  version      = {1.0.12},
  url          = {https://github.com/strathlab-data/DII},
  note         = {Python package validated against dietaryindex R package}
}

Methodology Citation

@article{shivappa2014dii,
  author    = {Shivappa, Nitin and Steck, Susan E. and Hurley, Thomas G. and 
               Hussey, James R. and H{\'e}bert, James R.},
  title     = {Designing and developing a literature-derived, population-based 
               dietary inflammatory index},
  journal   = {Public Health Nutrition},
  year      = {2014},
  volume    = {17},
  number    = {8},
  pages     = {1689--1696},
  doi       = {10.1017/S1368980013002115}
}

See also CITATION.cff for machine-readable citation information.

References

Shivappa N, Steck SE, Hurley TG, Hussey JR, Hébert JR. Designing and developing a literature-derived, population-based dietary inflammatory index. Public Health Nutr. 2014;17(8):1689-1696. doi:10.1017/S1368980013002115
Zhan J, Hodge RA, Dunlop AL, et al. Dietaryindex: a user-friendly and versatile R package for standardizing dietary pattern analysis in epidemiological and clinical studies. Am J Clin Nutr. 2024. doi:10.1016/j.ajcnut.2024.08.021

License

MIT License — see LICENSE for details.

Authors

Ted Clark — University of Florida
Email: tedclark94@gmail.com
Larissa Strath, PhD — University of Florida
Email: larissastrath@ufl.edu
ORCID: 0000-0002-9616-0177

Department of Health Outcomes and Biomedical Informatics, College of Medicine

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Acknowledgments

Dr. Jeanette M. Andrade (University of Florida) for providing the original R validation code
Jiyan Aslan Ceylan (University of Florida) for independent validation review
Jiada (James) Zhan for the dietaryindex R package

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github/workflows		.github/workflows
data		data
docs		docs
examples		examples
src/dii		src/dii
templates		templates
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.cfg		setup.cfg

License

strathlab-data/DII

Folders and files

Latest commit

History

Repository files navigation

DII Calculator

Overview

Installation

From PyPI (recommended)

Development installation

Quick Start

Methodology

Step 1: Z-score

Step 2: Centered Percentile

Step 3: Weighted Contribution

Step 4: Total DII Score

Interpretation

Input Requirements

Data Format

Data Types

Units Reference

Macronutrients

Fatty Acids

Vitamins

Minerals

Other Components

Flavonoids

Spices & Herbs

Missing Data

Features

Detailed Output

Visualization

Command-Line Interface

Templates

Validation

Methodology

Results

Synthetic Test Cases

Precision

API Reference

Core Functions

calculate_dii(nutrient_data, reference_df=None, id_column=None, detailed=False, validate_bounds=True)

get_available_nutrients()

load_reference_table(custom_path=None)

Visualization Functions

plot_dii_distribution(dii_scores, title=..., save_path=None, show=True)

plot_nutrient_contributions(detailed_row, save_path=None, show=True)

plot_dii_categories_pie(dii_scores, save_path=None, show=True)

Citation

Software Citation

Methodology Citation

References

License

Authors

Contributing

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Languages

`calculate_dii(nutrient_data, reference_df=None, id_column=None, detailed=False, validate_bounds=True)`

`get_available_nutrients()`

`load_reference_table(custom_path=None)`

`plot_dii_distribution(dii_scores, title=..., save_path=None, show=True)`

`plot_nutrient_contributions(detailed_row, save_path=None, show=True)`

`plot_dii_categories_pie(dii_scores, save_path=None, show=True)`

Packages