Gaghiel Tutorial (Grocery Recommendations)

Gaghiel is simMachines’ recommendation Angel. It suggests items that an individual may like by comparing that individual’s prior preferences with the preferences of individuals in the rest of the data.




  • Tutorial Description

      This tutorial will demonstrate the recommendation capabilities of the Gaghiel Angel on the simMachines platform. If you have a simMachines’ account and wish to follow along, the data file we are using can be found here.

      We are going to use Gaghiel to suggest products in a grocery store that a customer will be likely to purchase. Gaghiel will accomplish this by identifying those customers with the most similar purchase histories as the queried customer and then determining which items are commonly purchased by those similar customers that the queried customer has not purchased. This information could be used in a variety of ways including individually targeted marketing or in store product recommendations.




  • Getting Started

      Create a new folder for this tutorial and upload the data. If you are unfamiliar with this process please see the Platform Navigation Tutorial.

      From the “Create Angel” window select Gaghiel, then choose the folder in which the data is saved.

      Once selected you will see the first few rows of the data. Directly above the data is the columns’ header.




  • File Specifications

    Unlike other Angels, Gaghiel does not require column types to be identified. Instead, Gaghiel accepts files in the format of:

    Column 1 = ID – A unique identification for the object.

    Column 2 = Item – A semicolon separated list of the items associated with the object.

    Column 3 = Weight – A semicolon separated list of how many of each item is associated with the object. Weight must be the same length as Item, and the order of Weights must correspond to the order of Items.

    This file contains data about customer purchase histories. This table shows the first fifteen lines of the file:

    ID ITEMS WEIGHTS
    01624168 4714981010038;4902555123738;8711500638229;4710736570031;4710088413383;4714692001264;4710036008586;4714242832669;4713915513416;4714431050881 2;1;1;1;1;1;3;1;3;2
    00575683 8801019931536;4710043004731;0010742202211;4710174041551;4719111015020;0310742007329;4710154058326;4714910170307 2;1;1;1;2;1;1;1
    01677768 4710885646205;20203689;4710022445708;4710852001075;4710706510029;4710960892091;0748675116250;4710252000043;4710063312212;4711207003027;4712067898884;4712067898846;4710147660826;4711481100054;4710063312168 1;1;3;2;1;1;1;1;1;2;1;2;2;2;1
    01359039 8851991110160;0037000329169;4718121000712;2250078000022;8851991110146 1;1;1;1;1
    01749786 4710088434593;4718297890919;4710249002029;4710088410610;4710011408028;4710249002005;4710943101318;4710199010174;4711985100024;4710321790509;4710320224265;4710088410795;4711219600504 1;2;1;1;1;1;1;1;1;1;1;1;1
    02003542 4710017052928;4710202072182;20458140;4710043351040;4710868506199;4710088432353;4710498123957;4710094021572;4714058833195;2100230001070;4710594912028;4710207010219;4715890102180;4710908110232;4710043231410;4711553176987;4712425010569;4710015101826;4711926725651;4710105002019;4715525951244;4712076000575;4710091111702;4902704881052;4711566856913;20513429;0079763251158;4714058833218;20545970;4715140028581;4712814168888;4713894104186;4710321880170;4710088410139;20498573;8990057979461;4903301825555;8712045013069;9310022861109;4710868501057;20561529;4714058833126;0300086631038;4711856000668;20513412;4710644086235;4710110222976;4711863180827;4710205006948;4710314413149;8850987101021 2;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;2;1;1;1;1;1;1;4;1;1;3;1;1;1;1;1;1;1;3;1;1;3;1;1;1;1;1;1;1;1;1
    00149266 4710982050011;4710063131509;4902704881052;4710171042223;4710205005750;4710664900016;4710144101452;4710176023098 1;3;1;1;1;2;2;1
    02175843 0719859796117;4714220420079;20515485;4710017009571;4972525050975;4973167974070;4710126191372;4712222300375;4713317111036;4710088433312;4719862630534;4718585391296;0719859796124;20513016 2;2;1;1;1;1;1;2;1;1;1;1;3;2
    01325164 20557003;4714981010038;4710579101003;7231254880206;4719090900065;4712598000015;4711271000014;4714072600773;4710570001906;4710008290032;4710063121494;4710154015206;4715747112201;4710046031505;4711022100017;4710104112924;4710191000012;4710706902008;4716545000523;4712425010712;8888240001030;4710162000072;4713985863121;20434809;4710036000320;4711160000989;4714058833218;0723125488064;4710494050110;4710028201247;4710008316145;4713071811159;4710583996008;4712277888866;4715874001027;2250271000966;4711269680099;4711083320935;4711022100024;4715747112102;4710022102892;4710980000063;4711856020208;4710063031106;4719090900058;4710154012144;4710530912013;4710105015125;4710198221113;4710363542005;20492519;4713115888819;4711856020215 1;1;1;1;1;1;2;1;1;1;1;2;1;1;1;1;2;1;1;1;1;2;1;1;1;1;2;1;1;1;1;2;1;1;2;1;1;1;1;2;2;1;1;1;1;1;1;1;1;2;1;1;1
    01683080 4712482050010;4710168102206;4902430491525;4712172500016;8851019430515;4712023775693;4710095321305;8852047605425;4710047504657;4714390001030;4710543215040;7610700602393;4710885672808;4710043002638;4710043312010;2230123002294;4710022275503;4710063151101;4902430041270;4710857472689;4710176011194;4710011408028;4719857522189;0022000147165;4712023775686;4711108205544;4713985863121;4719090301015;4710247005831;4710247005978;4711001302104;4710096000322;0066592001450;4710312010067;4710626110156;4710323168108;4710030626601;4716349082053;4710012131130;4711109002036;4719862260410;4710126021174;4014612508973;4711713290195;4710011432825;4710162000010;4712031000381;4956043789449;4710186064364;4712425010255;4713243800042;4901550332077;4716701000015;9556178007149;4005808867301;4710583510112;4714390001047;4711486008256;4711300986692;4710094003745;4934567661519;4710084208341;4710362040182;4710871000165;4710063131509;4005808812134;4710626111351;47107021;4719856616339;4710126021198;4714499850041;4710017005719;8801062148035;4710583510082;0047400115002;0078895122237;4711202220184;4713247001070;4710386123816;4710011401135;4715006140051;4710011401128;4710088410610;4710036000849;20301101;4710304111147;4710626111450;4710254049521;4715874000662;4710036009781;2230090000095;4710943100328;4719856840017;4710126031906;4713247007263;4710175567166;5000174957778;4710017005788;4711258001256;4714101099141;4710010020054;4710126020344;4710265849066;4710205006924;2250271000355;4712023775648;4710076432037;0613033216296;4710265847666;4710088446206;4710175567173;4711684600559;4711634002297;4719090301046;4710126031890;4710011412223;4711101030013;4710314900519;4710857000059;4710043980714;4710057110046;4710114128038;4711931220110;4710885674802;4710011406123;4711781730630;4710095370235;4710543310066;4710320224661;4005808867400;4718480160195;4710861100028;4719854271752;4011800070007;4710363604000;4711985005626;4710685440362;4710254011627;4715872000299;4710321880446;4712076000568;4710303224640;4711634000460;0723125488040 1;1;1;1;1;1;1;1;1;1;1;2;1;1;1;1;1;1;1;1;1;1;1;1;1;1;2;1;1;1;1;1;1;2;1;1;1;1;1;1;1;1;1;2;1;2;1;1;1;1;3;1;1;1;1;1;2;2;1;1;1;1;1;2;1;1;1;1;1;1;1;1;1;1;1;1;1;1;1;2;3;3;1;2;2;1;1;1;1;1;1;1;3;1;1;1;1;2;1;1;2;1;2;1;5;1;1;1;2;1;1;1;1;1;1;1;1;1;1;1;2;1;1;1;2;1;1;2;1;1;1;2;2;1;1;1;1;1;1;2;1;1;1;1
    00668385 20518271;2250271001017;4710746111149;4710265796216 1;2;1;1
    00248952 4710706121751;0078895423037;4710172020107;4710294110113;4710908110232;4710734000226;4710561121125 1;1;5;3;2;1;3
    00526234 8888021200140;4710254011672;20557003;4710105015521;8888021200256;3228020490329;4710583110015;4710043981513;4710583300089;4710114128618;4710363723008;4711271000014;4711408000139;4710038850558;4711001917018;4710043552102;4710012122121;4710254011610;4710120001530;4712031000060;4712825123012;4711271000472;4711290030092;2250028000416;4710036039023 1;1;1;1;2;1;1;1;1;1;2;2;1;1;1;2;1;1;1;1;1;2;1;1;1
    00575676 4711186500074;4710543310059;4714686400394;4710105015521;4710179111709;4710626111351;4710022237501;4719090900065;4710363240406;4710063312212;4710015202721;4710176121145;4710543215040;4712959001408;4710105046013;4710857000202;4710176011040;4710530912020;4713645301512;4719857520413;4710095370235;4710063312106;4710105015415;20411503;4710015103479;4712815113870;4719090900058;4711080010112;4710096000322;4710088466976;4710475004224;4710265849066;4710176021445;4710176001812 1;1;1;2;1;1;1;1;1;1;1;1;1;1;2;1;1;1;2;2;1;1;1;1;1;1;1;1;1;1;1;1;1;1
    00958172 20563356;4710421090059;4718480240323 1;6;1

     

    This file has three columns. The first column is the customer ID. The second column is a semi-colon separated list of products purchased by that customer. The last column is a semi-colon separated list of the number of times that each product has been purchased by the customer.

    Note: the the second and final column must be the same length. This is because every item in the second column (product) needs to have an associated weight provided in the final column (the number of times the customer has purchased the product).

    The purpose of this tutorial is to have Gaghiel recommend products to a customer based on their previous purchases.






  • Angel Specification and Creation

    Gaghiel accepts the following Angel specifications:

    Top Recommendations The maximum number of recommendations to return. (Default: 10)
    Repeat Items Should items already part of the query object be returned? (Default: No)
    Storage Units Specifies the amount of memory devoted by the server to this Angel. Larger files or Angels with more strict search parameters may require additional memory. Each unit is 2 GB. (Range 1 to 6, default 1)
    Parallelism Specifies the number of servers redundantly running the Angel. (Default 2)
    Ramiel K Specify the number of results for the nearest neighbor search. (Default 10)
    Pivots The number of primary search points in the engine. (Range 256 to 1024, default 256)
    Probability Minimum accepted probability for the results, any result with lower probability will be discarded. (Range 0 to 1, default .95)
    Accepted Error Maximum accepted difference in distance between returned objects and the query object. (Minimum 1, default 1.2)

     

    Once all desired specifications have been entered and you have given your Angel a name, click “Create”.

    You will be taken to the “Your Angels” page where you can see the status of the Angels that you have created. Once your Angel’s status is “running” it is ready to answer queries. Depending on the file size it may take a few seconds to a few minutes for an Angel to complete initialization.




  • Querying Your Angel

    You now have a functional Gaghiel Angel capable of returning recommendations. Let’s try it out!

    When querying a Gaghiel Angel you have two options, Execute Query and Batch Query. Both are accessed from the “Angel Actions” dropdown on the “Your Angels” screen.

    You can now submit queries to provide recommendations. You can request a recommendation for a customer not already in the dataset by entering its values into the available fields, or select an existing customer by selecting the folder with your data in the “Choose your folder” dropdown and clicking the “Fill Query Fields” button next to the object.

    Let’s generate a query and see Gaghiel in action!

    Populate the fields with the items and weights of a customer you want a recommendation for and click “Execute Query”.

    The results will immediately appear in the area above the “Execute Query” button. The first number is the recommended item, and in brackets is a confidence value; the higher the value, the higher the confidence.




  • Batch Queries

    Gaghiel also accepts batch queries. A batch query will take a file of objects and return recommendations for each object in the file. The output of a batch query will be a CSV file with the object ID in the first column, and the recommended items, with their confidence value in parenthesis, in the second.

    To run a batch query, select “Batch Query” from the “Angel Actions” dropdown next to the Angel on the “Your Angels” page.

    Select the folder containing the file you wish to run a batch query on, name your output file, and specify an output folder. Then select “Execute Query”.

    The status of your batch execution is visible at the bottom of the page. When the status is marked “Completed”, click the “Download Results” button to download the results.


  • Danny ShaymanGaghielTutorial