View or edit on GitHub

This page is synchronized from trase/models/brazil/soy_2023_2024_v27/decision_tree_description.md. Last modified on 2026-09-17 20:47 CEST by achandra. Please view or edit the original file there; changes should be reflected here after a midnight build (CET time), or manually triggering it with a GitHub action (link).

BoL Decision Tree — v2.7

The decision tree follows that of v2.6, with the following expected differences:

Greater reliance on CNPJ and CNAE of BoL to locate the municipality of the logistic hub
More complete list of silos/storage facilities to resolve links
Link of the supply chain decision tree with the supply shed work method
An attempt to resolve Unknown (TBD)

First test on soy exports in 2023, with the goal of applying to 2024 and 2025 trade.

Branch 1: Shipments of BEAN directly linked to farms (asset level 1)

The BoL CNPJ14 information matches the cadastro, allowing use of the CNAE information to make direct links to a farm municipality.

CNAE farm activity: - 0115-6/600 — soy cultivation - 0141-5/01 — production of certified seed, except forage for pasture

Sub-branches

Branch 1.1 — Farm municipality produces soy - Branch: 1.1 link to farm municipality with production - Flag: send to supply shed (silo)

Branch 1.2 — Farm municipality does NOT produce soy - Branch: 1.2 link to farm municipality no production - Flag: send to supply shed (silo)

Branch 2: Shipments of BEAN directly linked to storage facilities (asset level 2)

The BoL CNPJ14 information matches the CNPJ in the silo list and the cadastro, allowing use of the CNAE information to make direct links to the facility municipality.

CNAE storage activity: - 5211-7/01 — general storage - 5211-7/99 — warehouse and goods for 3rd parties - 163600 — post-harvest activity (as recommended by Vivian) - 5231-1/02 — port operator activities

Sub-branches

Branch 2.1 — CNPJ14 matches both the silo list and the cadastro - Branch: 2.1. link to silo list and cadastro - Flag: send to supply shed (silo)

Branch 2.2 — CNPJ14 only matches the cadastro (no facility detected through other means) - Branch: 2.2 link to silo cadastro only - Flag: send to supply shed (silo)

Branch 3: Shipments of CAKE and OIL directly linked to a crushing facility (asset level 3)

The BoL CNPJ14 information matches the CNPJ in the crushing facility list and the cadastro, allowing use of the CNAE information to make direct links to facility municipalities.

CNAE crushing activity: - 1041-4/00 — vegetable oil production (bruto), except corn - 1042-2/00 — vegetable oil production, except corn - 1069-4/00 — crushing of vegetable products

Sub-branches

Branch 3.1 — The exporter's crushing facility is identified, either directly or by finding silos nearby

Branch 3.1.1 — CNPJ14 matches a crushing facility in soy facility list
CNPJ14 matches a crushing facility, so the exporter is itself a known crushing facility in the soy facility list.
Branch: 3.1.1 link to a crushing facility in soy facility list
Flag: send to supply shed (crush)
Branch 3.1.2 — Exporter has a crushing/silo facility nearby
The exporter isn't directly listed as a crushing facility, but is linked (via the same parent company (CNPJ8)) to one or more processing facilities in the same municipality
Branch 3.1.2.1 — Only 1 silo in the municipality
- Only one such facility is found > link to it directly.
- Branch: 3.1.2.1 link to crush with 1 silo or crushing in same municipality
- Flag: send to supply shed (silo)
Branch 3.1.2.2 — More than 1 silo in the municipality
- More than one such facility is found, the most likely one is selected using a priority order
- Branch: 3.1.2.2 link to crush with >1 silo in the same municipality
- Flag: send to supply shed (silo)

Branch 3.2 — There are no company silos in the same municipality as the crushing facility

Branch 3.2.1 — Cake and Oil exports match a SICASQ facility
The BoL CNPJ14 information matches a facility listed in SICASQ
Branch: 3.2.1 exports matches crushing facilities with SICASQ
Heads up: a caveat noting SICASQ only shows which facilities participate in bilateral export agreements, not that they're barred from exporting elsewhere, and that there's no batch/facility-level segregation evidence, so a match is indicative rather than conclusive.

Branch 4: Shipments of BEAN are linked to an office

The BoL CNPJ14 information matches the CNPJ in the office or sales activity in the cadastro.

CNAE sales activity: - 46222/0-0 — bulk sales of soy - 46231-0/8, 46231-9/9 — bulk sales of feed - 46320-0/1 — bulk sales of cereal and leguminous products - 46320-0/2 — sales of flour - 46320-0/3

Sub-branches

Branch 4.1.1 — Office not located at a port, and combined exporter exports from the municipality > 20,000 tonnes (i.e. acts as a hub) - the CNPJ14 is an office that is not located at a port, and combined exports of the exporter from the municipality are > 20,000 tonnes (therefore acts as a hub) - Branch: 4.1.1 office is not located at a port and trades >20,000 t - Exception — São Paulo, Mairinque and Porto Alegre are never treated as hubs here. In these three municipalities an office/wholesale CNPJ is a corporate registration address rather than a physical point of aggregation, so branch 4 skips them and the flow falls through to Branch 5 (Unknown - missing information), where the unknown-sourcing allocation spreads it on the known sourcing pattern. The logistics hub is reset to BR-XXXXXXX at the same time, in both 4.1.1 and 4.1.2, so the office municipality does not survive on the flow. - Why: each carries far more volume than the storage recorded there could hold — São Paulo 22.6 Mt against 7,920 t (a turnover of ~2,850x, where the median hub municipality is 2.1x), Porto Alegre 1.7–2.1 Mt against 29,900 t, Mairinque 1.4 Mt against 13,970 t. Routing to unknowns was preferred over reassigning to the nearest company-owned facility, which would replace one artificial concentration with another and would need distance, capacity and sourcing assumptions the data does not support. - Scope: this covers branch 4 only. São Paulo is still reached through branches 1.2 and 2.1 by head offices whose CNPJ also carries a warehousing (5211-7/01, 5211-7/99) or post-harvest (0163-6/00) CNAE — 10.7 Mt in 2023 and 13.2 Mt in 2024, which remains open. - Constant: OFFICE_ONLY_HUB_MUNICIPALITIES in model.py. The silo_turnover_within_limit dbt test on the v2.7.0 outputs reports municipalities of this shape.

Branch 6: Unmatched CNPJ flows - Statistical allocation of a logistics hub

Shipments of BEAN, CAKE and OIL where the BoL does not carry enough information to link the shipment directly to a municipality containing a silo or crushing facility (i.e. Branches 1–4 all fail). These account for 30% of soy exports in 2023 and 37% in 2024.

Replaces the old v2.6 approach of assigning potential hubs to unmatched-CNPJ flows via MDIC port, closest distance (branches 2 and 3), etc.

All unmatched CNPJ flows are passed to this Branch 5 for statistical allocation of a logistics hub (LH).

Branch 6.1 — Allocate LH to silo using MDIC and known source pattern - Use known sourcing pattern and MDIC to assign a silo logistic hub

Branch 6.2 — Allocate LH to crushing using MDIC and known source pattern - Use known sourcing pattern and MDIC to assign a crushing logistic hub

Notes: how "Unknown" is treated in v2.7

In both v2.6 and v2.7, a shipment that cannot be directly linked to a municipality with a silo or crushing facility is classified as an unmatched CNPJ flow (branch 5 in v2.7 and branches 2 and 3 in v2.6.1). A "true unknown" refers strictly to the exported volume that remains unassigned after all estimation methods have been exhausted.

v2.6: 60–70% of total exported soy did not match any soy-related CNPJ or facility. An LH was then estimated via branches 2 and 3, covering ~50 percentage points and leaving ~20% truly unknown.
v2.7: thanks to a more complete soy facility dataset, direct CNPJ linkages are established more often, leaving only 30% (2023) / 37% (2024) of soy exports unmatched. Statistical allocation via Branch 6 then assigns an LH to all of these, so 100% of soy exports end up with an assigned LH.

Caveat: although 100% of soy exports are assigned an LH, when the supply shed model subsequently allocates a municipality of origin to each shipment, distance cutoffs constrain the production available to a given LH. This leaves 3–4% of demand unsolved at the supply shed stage.