Documentação técnica do INCIDB

1. O que há no snapshot

Cinco tabelas, exportadas em CSV delimitado por barra vertical UTF-8 e em Apache Parquet, com colunas idênticas:

• 18.583 produtos — uma linha por produto do Open Beauty Facts com uma lista de ingredientes utilizável na embalagem, com a declaração bruta mantida literalmente para que a análise possa ser refeita.
• 5.925 marcas — identidades de marca conforme registradas na origem.
• 46.973 nomes INCI canônicos distintos — resultado da canonicalização de cada token bruto dos rótulos, enriquecidos com o CosIng onde o CosIng os lista.
• 318.758 vínculos de composição ordenados — preservando a ordem do rótulo em position_index.
• 55.426 linhas do mapa de nomes — como cada token bruto dos rótulos foi resolvido e por qual método.

2. Fontes e a junção

Duas fontes, uma junção documentada. A URL, o horário de download e o SHA-256 de cada arquivo de origem ficam registrados no build_report.json fornecido com os dados.

• Open Beauty Facts — o corpus de produtos (códigos de barras, marcas, as próprias categories_tags da fonte, listas de ingredientes brutas) sob a Open Database License (ODbL).
• CosIng da Comissão Europeia — o inventário de ingredientes: categorias funcionais, números CAS e CE, descrições químicas, restrições e inclusão nos Anexos II–VI. Junção pelo nome canônico exato; nomes sem correspondência ficam NULL em todas as colunas derivadas do CosIng, nunca com um valor de preenchimento.
• Alergênicos de fragrância do Anexo III da UE — Regulamento (CE) 1223/2009, alterado pelo Regulamento (UE) 2023/1545, a única lista por trás de is_common_allergen. A FDA dos EUA ainda não publicou sua lista de alergênicos de fragrância da MoCRA; por isso, não existe sinalização dos EUA neste conjunto de dados.
• Camada autoral — 145 classificações comedogênicas transcritas de uma única tabela publicada e 270 sinalizações de acne fúngica derivadas de regras. Ambas trazem sua citação por linha em rating_source e são NULL em todos os outros casos.

3. Cobertura medida

Apresentada de duas formas, porque as duas diferem em uma ordem de grandeza e citar apenas uma induziria ao erro:

• Correspondência CosIng (qualquer): 11,0% dos 46.973 nomes canônicos distintos; 82,5% das 318.758 ocorrências de ingredientes nos rótulos dos produtos.
• functions: 10,9% dos nomes distintos; 81,5% das ocorrências em rótulos.
• cas_number: 8,3% dos nomes distintos; 76,4% das ocorrências em rótulos.
• chemical_description: 8,5% dos nomes distintos, 3.965 valores distintos.

Um corpus de rótulos contém muito mais strings distintas — variantes botânicas, grafias multilíngues, tokens de marketing — do que qualquer inventário regulatório lista, e é por isso que o primeiro número de cada par é baixo. As posições em um rótulo real são preenchidas, em sua esmagadora maioria, por ingredientes que o CosIng cobre, e é por isso que o segundo é alto. Nenhum dos dois números, isoladamente, descreve os dados.

4. Canonicalização

Os tokens brutos dos rótulos são resolvidos em nomes INCI canônicos por um procedimento explícito e ordenado — decodificação de entidades, remoção de caracteres, colapso de espaços em branco, conversão para maiúsculas e, em seguida, correspondência exata, correspondência limpa, um pequeno mapa de erros de digitação com citação, remoção de percentuais, remoção de parênteses, um mapa de sinônimos, divisão de variantes com barra e divisão de concatenações somente quando ambas as metades correspondem ao inventário. Tudo o que falha em todas essas etapas é mantido literalmente e registrado como unresolved, nunca adivinhado. O método utilizado fica armazenado por linha em ingredient_name_map.method, de modo que cada decisão é auditável e reversível.

5. Início rápido — PyArrow & Pandas

import pyarrow.parquet as pq

ingredients = pq.read_table('ingredients.parquet').to_pandas()
links = pq.read_table('product_ingredients.parquet').to_pandas()

# Coverage the way it actually matters: weighted by label occurrence.
merged = links.merge(ingredients, on='ingredient_id', how='left')
print(merged['functions'].notna().mean())

# EU Annex III fragrance allergens
allergens = ingredients[ingredients['is_common_allergen'] == 1]

6. Início rápido — DuckDB

import duckdb

duckdb.query("""
SELECT f.function, COUNT(*) AS label_slots
FROM 'product_ingredients.parquet' pi
JOIN 'ingredients.parquet' i USING (ingredient_id)
CROSS JOIN UNNEST(string_split(i.functions, ';')) AS f(function)
WHERE i.functions IS NOT NULL
GROUP BY 1 ORDER BY 2 DESC LIMIT 10;
""").show()

# Audit the canonicalisation itself
duckdb.query("""
SELECT method, COUNT(*) AS n
FROM 'ingredient_name_map.parquet'
GROUP BY 1 ORDER BY 2 DESC;
""").show()