sugartrail/notebooks/004_connection_check.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "177cb892",
   "metadata": {},
   "source": [
    "*In this tutorial we will investigate two seperate companies and check if they are connected.*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8cd2e41",
   "metadata": {},
   "source": [
    "There are instances where we may want to see if two companies are connected. We can do this by simply building a network for each company and comparing them to see if there are any common officers, addresses or companies.\n",
    "\n",
    "Lets test this approach with two example companies, Zahawi & Zahawi Ltd (07285998) and Gorgeous Services Limited (05714521):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10e091d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sugartrail\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f5bd44c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# API key is loaded automatically from .env (COMPANIES_HOUSE_API_KEY).\n",
    "# To set it manually instead: sugartrail.api.basic_auth.username = \"your_key\"\n",
    "if not sugartrail.api.basic_auth.username:\n",
    "    print(\"No API key found — add COMPANIES_HOUSE_API_KEY to your .env file\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5897b17",
   "metadata": {},
   "source": [
    "Create one network for Zahawi & Zahawi including some limits to reduce the number of possibly irrelevant connections:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8ec6a941",
   "metadata": {},
   "outputs": [],
   "source": [
    "zahawi_connections = sugartrail.base.Network(company_id='07285998')\n",
    "zahawi_connections.hop.officer_appointments_maxsize = 20\n",
    "zahawi_connections.hop.officers_at_address_maxsize = 20\n",
    "zahawi_connections.hop.companies_at_address_maxsize = 20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e27a1f1",
   "metadata": {},
   "source": [
    "Create a second network for Gorgeous Services:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eadec2f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "gorgeous_connections = sugartrail.base.Network(company_id='05714521')\n",
    "gorgeous_connections.hop.officer_appointments_maxsize = 20\n",
    "gorgeous_connections.hop.officers_at_address_maxsize = 20\n",
    "gorgeous_connections.hop.companies_at_address_maxsize = 20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8fd1658",
   "metadata": {},
   "source": [
    "We can now pass both networks to the `find_network_connections` method which returns any connections found between two networks. The method accepts two networks as input and an optional `max_depth` value (defaults to 5) which sets the maximum depth of network we will build for both. `find_network_connections` builds each network up to the `max_depth` value and completes when connections are found or the `max_depth` is reached."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6a311159",
   "metadata": {},
   "outputs": [],
   "source": [
    "# zahawi_connections=sugartrail.base.Network(file=f'{sugartrail.const.networks_path}multinode/connection_check_a.json')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b621425",
   "metadata": {},
   "outputs": [],
   "source": [
    "# gorgeous_connections=sugartrail.base.Network(file=f'{sugartrail.const.networks_path}multinode/connection_check_b.json')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dae95c03",
   "metadata": {},
   "outputs": [],
   "source": [
    "connections = sugartrail.multinetwork.find_network_connections(zahawi_connections, gorgeous_connections)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4eee3f43",
   "metadata": {},
   "source": [
    "Looks like a connection was found. We can see by the long string of characters that its an officer ID:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e02ca7c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "connections"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78ec9aab",
   "metadata": {},
   "source": [
    "We can now trace the path from Zahawi & Zahawi to this connection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc581d24",
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.DataFrame(zahawi_connections.find_path('g8BmvnpH8blqT87i93sgJeowx7I'))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "efe1add8",
   "metadata": {},
   "source": [
    "... and the path from Gorgeous Connections to the connection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "786d0d23",
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.DataFrame(gorgeous_connections.find_path('g8BmvnpH8blqT87i93sgJeowx7I'))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b67e8187",
   "metadata": {},
   "source": [
    "Reading both paths tells us how Zahawi & Zahawi connect to Gorgeous Connections. Zahawi & Zahawi has Nadhim Zahawi as an officer who has YOUGOV PLC as an appointment which has Benjamin Elliot as an officer who is also an officer of Gorgeous Services Limited."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}