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, nutrients=<factory>, dri_type=DriType.RDA, gender=Gender.MALE, serving_size=100.0, calories_per_serving=0.0, macronutrient_distribution=<factory>)[source]

Bases: object

Represents the nutrient analysis of a food.

Parameters:

food (Food) –
nutrients (Dict[str, NutrientValue]) –
dri_type (DriType) –
gender (Gender) –
serving_size (float) –
calories_per_serving (float) –
macronutrient_distribution (Dict[str, float]) –

food

The food being analyzed.

Type:: usda_fdc.models.Food

nutrients

The nutrient values.

Type:: Dict[str, usda_fdc.analysis.analysis.NutrientValue]

dri_type

The type of DRI used for comparison.

Type:: usda_fdc.analysis.dri.DriType

gender

The gender used for DRI comparison.

Type:: usda_fdc.analysis.dri.Gender

serving_size

The serving size in grams.

Type:: float

calories_per_serving

The calories per serving.

Type:: float

macronutrient_distribution

The distribution of macronutrients.

Type:: Dict[str, float]

food: Food

nutrients: Dict[str, NutrientValue]

dri_type: DriType = 'rda'

gender: Gender = 'male'

serving_size: float = 100.0

calories_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.
Returns:: The nutrient value if available, None otherwise.
Return type:: NutrientValue | None

get_nutrients_by_group(group)[source]

Get nutrient values by group.

Parameters:: group (str) – The nutrient group.
Returns:: A dictionary of nutrient IDs to nutrient values.
Return type:: Dict[str, NutrientValue]

get_macronutrients()[source]

Get macronutrient values.

Returns:: A dictionary of nutrient IDs to nutrient values.
Return type:: Dict[str, NutrientValue]

get_vitamins()[source]

Get vitamin values.

Returns:: A dictionary of nutrient IDs to nutrient values.
Return type:: Dict[str, NutrientValue]

get_minerals()[source]

Get mineral values.

Returns:: A dictionary of nutrient IDs to nutrient values.
Return type:: Dict[str, NutrientValue]

get_amino_acids()[source]

Get amino acid values.

Returns:: A dictionary of nutrient IDs to nutrient values.
Return type:: Dict[str, NutrientValue]

get_nutrient_density(nutrient_id)[source]

Get the nutrient density (amount per calorie).

Parameters:: nutrient_id (str) – The nutrient ID.
Returns:: The nutrient density if available, None otherwise.
Return type:: float | None

to_dict()[source]

Convert the analysis to a dictionary.

Returns:: A dictionary representation of the analysis.
Return type:: Dict[str, Any]

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

Bases: object

Represents a nutrient value with its properties.

Parameters:

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

nutrient

The nutrient.

Type:: usda_fdc.analysis.nutrients.Nutrient

amount

The amount of the nutrient.

Type:: float

unit

The unit of the amount.

Type:: str

dri_percent

The percentage of the DRI (if available).

Type:: float | None

nutrient: Nutrient

amount: float

unit: str

dri_percent: float | None = None

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

Analyze the nutrient content of a food.

Parameters:

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

Returns:

A NutrientAnalysis object.

Return type:

NutrientAnalysis

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

Analyze the nutrient content of multiple foods.

Parameters:

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

Returns:

A list of NutrientAnalysis objects.

Return type:

List[NutrientAnalysis]

usda_fdc.analysis.analysis.compare_foods(foods, nutrient_ids=None, serving_sizes=None)[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 (all if None).
serving_sizes (List[float] | None) – The serving sizes in grams (one per food).

Returns:

A dictionary mapping nutrient IDs to lists of (food description, 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.DietaryReferenceIntakes(dri_type=DriType.RDA, gender=Gender.MALE)[source]

Bases: object

Provides access to Dietary Reference Intakes (DRI) data.

Parameters:

dri_type (DriType) –
gender (Gender) –

data: The loaded DRI data.

metadata: Metadata about the DRI data.

__init__(dri_type=DriType.RDA, gender=Gender.MALE)[source]

Initialize DietaryReferenceIntakes.

Parameters:

dri_type (DriType) – The type of DRI to load (RDA, AI, or UL).
gender (Gender) – The gender to load data for (only applicable for RDA and AI).

get_dri(nutrient_id)[source]

Get the DRI value for a nutrient.

Parameters:: nutrient_id (str) – The nutrient ID.
Returns:: The DRI value if available, None otherwise.
Return type:: float | None

get_all_dris()[source]

Get all DRI values.

Returns:: A dictionary of nutrient IDs to DRI values.
Return type:: Dict[str, float]

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

Bases: Enum

Types of Dietary Reference Intakes.

RDA = 'rda'

AI = 'ai'

UL = 'ul'

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

Bases: Enum

Gender options for DRI data.

MALE = 'male'

FEMALE = 'female'

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

Get the DRI value for a nutrient.

Parameters:

nutrient_id (str) – The nutrient ID.
dri_type (DriType | str) – The type of DRI to get.
gender (Gender | str) – The gender to get the DRI for.

Returns:

The DRI value if available, None otherwise.

Return type:

float | None

Recipe Analysis

class usda_fdc.analysis.recipe.Recipe(name, ingredients=<factory>, servings=1, instructions=None, total_weight_g=0.0)[source]

Bases: object

Represents a recipe with ingredients.

Parameters:

name (str) –
ingredients (List[Ingredient]) –
servings (int) –
instructions (str | None) –
total_weight_g (float) –

name

The name of the recipe.

Type:: str

ingredients

The ingredients in the recipe.

Type:: List[usda_fdc.analysis.recipe.Ingredient]

servings

The number of servings the recipe makes.

Type:: int

instructions

The recipe instructions.

Type:: str | None

total_weight_g

The total weight of the recipe in grams.

Type:: float

name: str

ingredients: List[Ingredient]

servings: int = 1

instructions: str | None = None

total_weight_g: float = 0.0

add_ingredient(ingredient)[source]

Add an ingredient to the recipe.

Parameters:: ingredient (Ingredient) – The ingredient to add.
Return type:: None

get_weight_per_serving()[source]

Get the weight per serving in grams.

Returns:: The weight per serving.
Return type:: float

class usda_fdc.analysis.recipe.Ingredient(food, amount, unit, weight_g)[source]

Bases: object

Represents a recipe ingredient.

Parameters:

food (Food) –
amount (float) –
unit (str) –
weight_g (float) –

food

The food.

Type:: usda_fdc.models.Food

amount

The amount of the ingredient.

Type:: float

unit

The unit of the amount.

Type:: str

weight_g

The weight in grams.

Type:: float

food: Food

amount: float

unit: str

weight_g: float

class usda_fdc.analysis.recipe.RecipeAnalysis(recipe, total_analysis, per_serving_analysis, ingredient_analyses=<factory>)[source]

Bases: object

Represents the nutrient analysis of a recipe.

Parameters:

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

recipe

The recipe being analyzed.

Type:: usda_fdc.analysis.recipe.Recipe

total_analysis

The nutrient analysis of the entire recipe.

Type:: usda_fdc.analysis.analysis.NutrientAnalysis

per_serving_analysis

The nutrient analysis per serving.

Type:: usda_fdc.analysis.analysis.NutrientAnalysis

ingredient_analyses

The nutrient analyses of each ingredient.

Type:: List[usda_fdc.analysis.analysis.NutrientAnalysis]

recipe: Recipe

total_analysis: NutrientAnalysis

per_serving_analysis: NutrientAnalysis

ingredient_analyses: List[NutrientAnalysis]

usda_fdc.analysis.recipe.parse_ingredient(text, client, default_unit='g')[source]

Parse an ingredient from text.

Parameters:

text (str) – The ingredient text.
client (FdcClient) – The FDC client.
default_unit (str) – The default unit to use if not specified.

Returns:

An Ingredient object if parsing succeeds, None otherwise.

Return type:

Ingredient | None

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

Create a recipe from ingredient texts.

Parameters:

name (str) – The name of the recipe.
ingredient_texts (List[str]) – The ingredient texts.
client (FdcClient) – The FDC client.
servings (int) – The number of servings the recipe makes.
instructions (str | None) – The recipe instructions.

Returns:

A Recipe object.

Return type:

Recipe

usda_fdc.analysis.recipe.analyze_recipe(recipe, dri_type=DriType.RDA, gender=Gender.MALE)[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 comparison.

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, nutrient_ids=None, min_percent=1.0)[source]

Generate data for a DRI percentage chart.

Parameters:

analysis (NutrientAnalysis) – The nutrient analysis.
nutrient_ids (List[str] | None) – The nutrient IDs to include (all with DRI values if None).
min_percent (float) – The minimum DRI percentage to include.

Returns:

A dictionary with chart data.

Return type:

Dict[str, Any]

usda_fdc.analysis.visualization.generate_nutrient_comparison_chart_data(analyses, nutrient_id)[source]

Generate data for a nutrient comparison chart.

Parameters:

analyses (List[NutrientAnalysis]) – The nutrient analyses to compare.
nutrient_id (str) – The nutrient ID to compare.

Returns:

A dictionary with chart data.

Return type:

Dict[str, Any]

usda_fdc.analysis.visualization.generate_nutrient_radar_chart_data(analysis, nutrient_ids)[source]

Generate data for a nutrient radar chart.

Parameters:

analysis (NutrientAnalysis) – The nutrient analysis.
nutrient_ids (List[str]) – The nutrient IDs to include.

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