Analysis API

The analysis module provides tools for analyzing nutrient content, comparing to dietary reference intakes, and calculating nutritional information for recipes.

Nutrient Analysis

class usda_fdc.analysis.analysis.NutrientAnalysis(food, serving_size, nutrients=<factory>, calories_per_serving=0.0, protein_per_serving=0.0, carbs_per_serving=0.0, fat_per_serving=0.0, macronutrient_distribution=<factory>)[source]

Bases: object

Analysis of a food’s nutrient content.

Parameters:

food (Food) –
serving_size (float) –
nutrients (Dict[str, NutrientValue]) –
calories_per_serving (float) –
protein_per_serving (float) –
carbs_per_serving (float) –
fat_per_serving (float) –
macronutrient_distribution (Dict[str, float]) –

food: Food

serving_size: float

nutrients: Dict[str, NutrientValue]

calories_per_serving: float = 0.0

protein_per_serving: float = 0.0

carbs_per_serving: float = 0.0

fat_per_serving: float = 0.0

macronutrient_distribution: Dict[str, float]

get_nutrient(nutrient_id)[source]

Get a nutrient value by ID.

Parameters:: nutrient_id (str) – The nutrient ID or name.
Returns:: The nutrient value, or None if not found.
Return type:: NutrientValue | None

class usda_fdc.analysis.analysis.NutrientValue(nutrient, amount, unit, dri=None, dri_percent=None, dri_type=None)[source]

Bases: object

Represents a nutrient value with additional analysis information.

Parameters:

nutrient (Nutrient) –
amount (float) –
unit (str) –
dri (float | None) –
dri_percent (float | None) –
dri_type (DriType | None) –

nutrient: Nutrient

amount: float

unit: str

dri: float | None = None

dri_percent: float | None = None

dri_type: DriType | None = None

usda_fdc.analysis.analysis.analyze_food(food, serving_size=100.0, dri_type=DriType.RDA, gender=Gender.MALE, age=30)[source]

Analyze the nutrient content of a food.

Parameters:

food (Food) – The food to analyze.
serving_size (float) – The serving size in grams.
dri_type (DriType) – The type of DRI to use for comparison.
gender (Gender) – The gender to use for DRI values.
age (int) – The age to use for DRI values.

Returns:

A NutrientAnalysis object.

Return type:

NutrientAnalysis

usda_fdc.analysis.analysis.analyze_foods(foods, serving_sizes=None, dri_type=DriType.RDA, gender=Gender.MALE, age=30)[source]

Analyze the nutrient content of multiple foods.

Parameters:

foods (List[Food]) – The foods to analyze.
serving_sizes (List[float] | None) – The serving sizes in grams (one per food).
dri_type (DriType) – The type of DRI to use for comparison.
gender (Gender) – The gender to use for DRI values.
age (int) – The age to use for DRI values.

Returns:

A list of NutrientAnalysis objects.

Return type:

List[NutrientAnalysis]

usda_fdc.analysis.analysis.compare_foods(foods, nutrient_ids=None, serving_sizes=None, dri_type=DriType.RDA, gender=Gender.MALE, age=30)[source]

Compare the nutrient content of multiple foods.

Parameters:

foods (List[Food]) – The foods to compare.
nutrient_ids (List[str] | None) – The nutrient IDs to compare.
serving_sizes (List[float] | None) – The serving sizes in grams (one per food).
dri_type (DriType) – The type of DRI to use for comparison.
gender (Gender) – The gender to use for DRI values.
age (int) – The age to use for DRI values.

Returns:

A dictionary mapping nutrient IDs to lists of (food_name, amount, unit) tuples.

Return type:

Dict[str, List[Tuple[str, float, str]]]

Nutrients

class usda_fdc.analysis.nutrients.Nutrient(id, name, display_name, unit, group, usda_id=None)[source]

Bases: object

Represents a nutrient with its properties.

Parameters:

id (str) –
name (str) –
display_name (str) –
unit (Unit) –
group (str) –
usda_id (int | None) –

id

The unique identifier for the nutrient.

Type:: str

name

The name of the nutrient.

Type:: str

display_name

The display name of the nutrient.

Type:: str

unit

The unit used to measure the nutrient.

Type:: usda_fdc.analysis.units.Unit

group

The nutrient group (e.g., macronutrient, vitamin, mineral).

Type:: str

usda_id

The USDA nutrient ID (optional).

Type:: int | None

id: str

name: str

display_name: str

unit: Unit

group: str

usda_id: int | None = None

usda_fdc.analysis.nutrients.NUTRIENTS = Dict[str, Nutrient]: Dictionary of all nutrients by ID.

usda_fdc.analysis.nutrients.NUTRIENT_GROUPS = Dict[str, List[str]]: Dictionary of nutrient groups to lists of nutrient IDs.

Dietary Reference Intakes

class usda_fdc.analysis.dri.DriType(value)[source]

Bases: str, Enum

Types of Dietary Reference Intakes.

RDA = 'rda'

AI = 'ai'

UL = 'ul'

EAR = 'ear'

AMDR = 'amdr'

class usda_fdc.analysis.dri.Gender(value)[source]

Bases: str, Enum

Gender for DRI calculations.

MALE = 'male'

FEMALE = 'female'

usda_fdc.analysis.dri.get_dri(nutrient_id, dri_type=DriType.RDA, gender=Gender.MALE, age=30)[source]

Get the Dietary Reference Intake (DRI) for a nutrient.

Parameters:

nutrient_id (str | int) – The nutrient ID or name.
dri_type (DriType) – The type of DRI to retrieve.
gender (Gender) – The gender to use for the DRI.
age (int) – The age to use for the DRI.

Returns:

The DRI value, or None if not found.

Return type:

float | None

Recipe Analysis

class usda_fdc.analysis.recipe.Recipe(name, ingredients, servings=1, description=None)[source]

Bases: object

Represents a recipe with ingredients.

Parameters:

name (str) –
ingredients (List[Ingredient]) –
servings (int) –
description (str | None) –

name: str

ingredients: List[Ingredient]

servings: int = 1

description: str | None = None

property total_weight_g: float: Get the total weight of the recipe in grams.

get_weight_per_serving()[source]

Get the weight per serving in grams.

Return type:: float

class usda_fdc.analysis.recipe.Ingredient(food, weight_g, description=None)[source]

Bases: object

Represents an ingredient in a recipe.

Parameters:

food (Food) –
weight_g (float) –
description (str | None) –

food: Food

weight_g: float

description: str | None = None

__str__()[source]

String representation of the ingredient.

Return type:: str

class usda_fdc.analysis.recipe.RecipeAnalysis(recipe, per_serving_analysis, ingredient_analyses)[source]

Bases: object

Analysis of a recipe’s nutrient content.

Parameters:

recipe (Recipe) –
per_serving_analysis (NutrientAnalysis) –
ingredient_analyses (List[NutrientAnalysis]) –

recipe: Recipe

per_serving_analysis: NutrientAnalysis

ingredient_analyses: List[NutrientAnalysis]

usda_fdc.analysis.recipe.parse_ingredient(text, client, search_limit=5)[source]

Parse an ingredient description into an Ingredient object.

Parameters:

text (str) – The ingredient description (e.g., “1 cup flour”).
client (FdcClient) – The FDC client to use for food lookup.
search_limit (int) – Maximum number of search results to consider.

Returns:

An Ingredient object, or None if parsing failed.

Return type:

Ingredient | None

usda_fdc.analysis.recipe.create_recipe(name, ingredient_texts, client, servings=1, description=None)[source]

Create a recipe from ingredient descriptions.

Parameters:

name (str) – The name of the recipe.
ingredient_texts (List[str]) – List of ingredient descriptions.
client (FdcClient) – The FDC client to use for food lookup.
servings (int) – The number of servings the recipe makes.
description (str | None) – Optional description of the recipe.

Returns:

A Recipe object.

Return type:

Recipe

usda_fdc.analysis.recipe.analyze_recipe(recipe, dri_type=DriType.RDA, gender=Gender.MALE, age=30)[source]

Analyze the nutrient content of a recipe.

Parameters:

recipe (Recipe) – The recipe to analyze.
dri_type (DriType) – The type of DRI to use for comparison.
gender (Gender) – The gender to use for DRI values.
age (int) – The age to use for DRI values.

Returns:

A RecipeAnalysis object.

Return type:

RecipeAnalysis

Visualization

usda_fdc.analysis.visualization.generate_macronutrient_chart_data(analysis)[source]

Generate data for a macronutrient distribution chart.

Parameters:: analysis (NutrientAnalysis) – The nutrient analysis.
Returns:: A dictionary with chart data.
Return type:: Dict[str, Any]

usda_fdc.analysis.visualization.generate_dri_chart_data(analysis)[source]

Generate data for a DRI comparison chart.

Parameters:: analysis (NutrientAnalysis) – The nutrient analysis.
Returns:: A dictionary with chart data.
Return type:: Dict[str, Any]

usda_fdc.analysis.visualization.generate_html_report(analysis)[source]

Generate an HTML report for a nutrient analysis.

Parameters:: analysis (NutrientAnalysis) – The nutrient analysis.
Returns:: An HTML string.
Return type:: str

Command-Line Interface

usda_fdc.analysis.cli.main()[source]

Main entry point for the CLI.

Return type:: None