Skip to content

Opensource Cocoa Coops Code

View or edit on GitHub

This page is synchronized from trase/data/cote_divoire/cocoa/logistics/q4_2025/opensource_cocoa_coops_code/README.md. Last modified on 2026-09-20 13:50 CEST by Nicolas Martin. 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).

Trase Cocoa Cooperative Disclosure Integrator

This open-source Python tool allows users to integrate their own cooperative disclosure data with the official Trase cooperative base map for Côte d'Ivoire.

It takes a standard CSV of cooperative disclosures, cleans and normalizes the text, and performs fuzzy matching against the official Trase GeoJSON. It updates existing cooperatives by appending the disclosing buyer, and geographically processes brand-new cooperatives by assigning them to the correct administrative departments before adding them to the map.

Getting new cooperative information

Folder Structure

Before running the script, ensure your working directory is structured exactly like this:

my_project/
├── update_trase_coops.py
├── requirements.txt
└── data/
    ├── user_disclosure_data.csv                 <-- Your data
    ├── cote-d-ivoire-cocoa-cooperatives.geojson <-- Trase Base Map
    └── ci_departments.geojson                   <-- Ivorian Departments Reference Map

Installation & Prerequisites

  1. Ensure you have Python 3.8+ installed.
  2. Install the required packages by running: 
    pip install -r requirements.txt

Input Data Schema (user_disclosure_data.csv)

For the script to successfully process your cooperative disclosures, your CSV file must include specific columns. Column names are case-insensitive, but the following standard headers are highly recommended:

Column Name Data Type Required? Description
SUPPLIER_FULLNAME String Yes* The full, official name of the cooperative (e.g., COOPERATIVE AGRICOLE BACON ESPOIR).
SUPPLIER_ABRVNAME String Yes* The short or abbreviated name of the cooperative (e.g., CABES).
COMPANY String Yes The name of the buyer, trader, or manufacturer disclosing this cooperative (e.g., NESTLE). (Alternative accepted header: BUYER)
LATITUDE Float Yes** The Y-coordinate (e.g., 6.356).
LONGITUDE Float Yes** The X-coordinate (e.g., -3.909).

Notes on Requirements: * * You must provide at least one naming column (SUPPLIER_FULLNAME or SUPPLIER_ABRVNAME). If both are provided, the script will prioritize the full name for matching. * ** Coordinates (LATITUDE / LONGITUDE) are only strictly required if the cooperative does not already exist in the Trase base map. If the script cannot find a match and coordinates are missing, that cooperative will be skipped.

Example Dataset (example_user_disclosure_data.csv)

There is an example version of user_disclosure_data.csv provided in the data folder, named example_user_disclosure_data.csv.

This example file includes several common data scenarios and formatting quirks to demonstrate how the script handles them automatically:

  • Row 1 (OUBE) — Tests a Roll-Forward: This cooperative exists in the base map for 2019, but here it is reported for 2024 without coordinates. The script will safely copy the 2019 location data and create a new 2024 point with "CHOCO CORP" added to the buyers list.
  • Row 2 (2 AD) — Tests an Exact Match: This exactly matches ID 2 for the year 2019 in the base map. The script will simply append "CHOCO CORP" to its existing 2019 entry.
  • Row 3 (CNF) — Tests a Brand New Cooperative: This does not exist in the base map. The script will use the coordinates to calculate its department, assign it a brand new ID, and plot it on the map for 2024.
  • Row 4 (2A SCCOPS) — Tests Fuzzy Matching: The official name is "COOPERATIVE LES AGRICULTEURS D'AKOUPE", but here there is a slight typo/variation. The script catches the typo dynamically and maps it successfully to ID 3.
  • Row 5 (EPO) — Tests the French Comma Bug: This is a brand new cooperative, but the coordinates use commas instead of decimals (6,150, -7,250). The script automatically fixes the formatting and plots it correctly.

How to Run

Once your data/ folder is populated with the three required files, navigate to the project directory in your terminal and run:

python update_trase_coops.py

Output

The script will generate a new file in your data/ directory named: updated_trase_coops_with_user_data.geojson

This file is a ready-to-use spatial dataset containing:

  1. All original Trase CIV cooperatives.
  2. Updated buyers_list arrays for cooperatives you disclosed.
  3. Brand new spatial point features for cooperatives unique to your dataset, fully populated with their corresponding Department IDs via point-in-polygon spatial joining.