<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Huon Wilson on Medium]]></title>
        <description><![CDATA[Stories by Huon Wilson on Medium]]></description>
        <link>https://medium.com/@huonw?source=rss-340a09703a3a------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*zooDaiV_wdZ0Hbne3ysAAQ.png</url>
            <title>Stories by Huon Wilson on Medium</title>
            <link>https://medium.com/@huonw?source=rss-340a09703a3a------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 14:33:43 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@huonw/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The joy of cooking (an app)]]></title>
            <link>https://medium.com/@huonw/the-joy-of-cooking-an-app-dd0422e39de4?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/dd0422e39de4</guid>
            <category><![CDATA[self-hosted]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[technology]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Mon, 30 Aug 2021 00:00:00 GMT</pubDate>
            <atom:updated>2021-09-07T21:45:20.277Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*QDyVekoKN-bjY_YO" /><figcaption>Photo by <a href="https://unsplash.com/@icons8?utm_source=medium&amp;utm_medium=referral">Icons8 Team</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Taking shortcuts? Leaving edge-cases unconsidered and unhandled? Is this engineering?! My approach to programming and software engineering has been shaped by years of building <a href="https://rust-lang.org/">open source</a> <a href="https://swift.org/">compilers</a> and <a href="https://stellargraph.readthedocs.io/en/stable/README.html">libraries</a>, where those edge cases matter, reliability is crucial and flexibility is important. It’s been a breath of fresh air to take a step back and stop thinking about every detail, and instead write code that works for a specific set of people: me and my wife.</p><p>Early in 2020 (while fires raged, in the before-times), I read <a href="https://www.robinsloan.com/notes/home-cooked-app/">Robin Sloan’s <em>An app can be a home-cooked meal</em></a> and the idea of code designed for a small group has been rattling around in my head ever since. I can feel the truth in Sloan’s writing:</p><blockquote><em>And, when you free programming from the requirement to be general and professional and scalable, it becomes a different activity altogether, just as cooking at home is really nothing like cooking in a commercial kitchen. I can report to you: not only is this different activity rewarding in almost exactly the same way that cooking for someone you love is rewarding, there’s another feeling, one that persists as you use the app together. I have struggled with words for this, but/and I think it might be the crux of the whole thing:</em></blockquote><blockquote><em>This messaging app I built for, and with, my family, it won’t change unless we want it to change. There will be no sudden redesign, no flood of ads, no pivot to chase a userbase inscrutable to us. It might go away at some point, but that will be our decision, too. What is this feeling? Independence? Security? Sovereignty?</em></blockquote><blockquote><em>Is it simply… the feeling of being home?</em></blockquote><h3>The project</h3><p>I got married last October, and I wanted to have an anticipatory countdown, somehow. We both happen to have Garmin watches, which support custom watch faces. I created a simple but fun little app: it shows the time, date and the battery, but also has a photo and a message.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1-az1_oA3WgzZq4K.png" /><figcaption>A screenshot of the watch face from Garmin’s simulator (left) and on my watch (right), on the birthday of <a href="https://www.instagram.com/corgi_tales/">Sterling</a> (pictured, excited about a tennis ball).</figcaption></figure><p>The photo and message changes each day, usually randomly. However, on some special days, it chooses a particular message or photo, like the countdown across the 10 days leading up to our wedding. The photos are synced, so that both of us get the same photo each day. The random messages aren’t synced: instead I wrote some for my wife’s watch and she for mine. It’s nice to wake up each day and see what unexpected combination of photo and message I get.</p><h3>“Engineering”</h3><p>If I was to create a gallery/message app <em>properly</em>, there’s a whole lot of work required beyond the core “show the watch face” code:</p><ul><li>upload photos and messages for random selection</li><li>associate particular photos and/or messages with particular days (with the possibility for recurrence each month or year)</li><li>potentially, a service to sync the photo order/selection across multiple devices (or, just being careful to put the same photos in the same order on each one)</li><li>message templating, because some messages should say “Happy 1st anniversary” on the first instance, “Happy 2nd anniversary” on the next</li><li>wrapping text nicely, to avoid it overflowing off the edge of the screen, like the example above</li><li>workflow for publishing to an app store, including signing and updating</li></ul><p>Instead, I didn’t do it properly, because it’s an app to run on two and only two devices. I can break all the rules: I can hardcode content, I include private information, I can make assumptions about devices. For instance:</p><ul><li>the app directly embeds all 25 background images</li><li>our two devices are different models, so the messages for each of us are conditionalised based on the device qualifiers using build system functionality</li><li>those two models are the only ones supported, so a minimal CI that builds for those devices is all that’s needed</li><li>the app can be easily sideloaded: plug the watch into a computer and copy the compiled .prg file onto it (I think this is a critical component of &quot;home cooking&quot; code: one must have sufficient control over the devices to run arbitrary code, without expensive or complicated processes managed by external corporations)</li></ul><h3>Open source?</h3><p>The modern software world is <a href="https://www.fordfoundation.org/work/learning/research-reports/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure/">built on the shoulders of free and open source software</a>. This project is not even 700 lines of code, and it’s still no different: I wrote it in Eclipse, stored it in git (via Emacs and <a href="https://magit.vc/">Magit</a>), cribbed the toolchain setup for CI from <a href="https://github.com/jokarls/donkeybrains">code published by @jokarls</a>, and that’s ignoring my little Python script for resizing and dithering the images appropriately, and of course skipping over whatever is used by Garmin (and the computer upon which I wrote it, and the internet services I used…).</p><p>Unfortunately, I think open sourcing this sort of code removes a large chunk of the freedom that’s so glorious. Just as publishing a recipe changes how it is phrased, so too does publishing the source code. I’m comfortable sharing code freely, whatever its state, but I’m not comfortable sharing the private messages I’d write to my wife, or the photos included: without the pressure of openness, I could just place these wherever is convenient.</p><p>I’d also prefer to keep these personal project free from the unfortunate negative aspects of published code: my experience with open source is somewhat tainted by the responsibilities of maintainership and the associated guilt, burnout and occasional instances of unpleasant user entitlement.</p><p>I’ll give back from these sort of “cooking” projects through blog posts, contributions to the tools/libraries used and potentially splitting out small parts, instead of open sourcing the projects themselves.</p><h3>Like cooking</h3><p>I don’t generally like cooking that much, except for when I’m cooking with my wife. I get the same immediate and personal sense of fulfillment writing code for (and, in this case, with) her. “Eating” the app on my wrist for months is just icing on top.</p><p><em>Originally published at </em><a href="http://huonw.github.io/blog/2021/08/home-cooked-app/"><em>https://huonw.github.io</em></a><em> on August 30, 2021.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dd0422e39de4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The customer is always right: user observation is an engineering superpower]]></title>
            <link>https://medium.com/stellargraph/the-customer-is-always-right-user-observation-is-an-engineering-superpower-7de1ae0297be?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/7de1ae0297be</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[ux-design]]></category>
            <category><![CDATA[data-science]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Thu, 04 Jun 2020 01:12:52 GMT</pubDate>
            <atom:updated>2020-06-04T01:16:56.395Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AGbjlWTd5EujDO0y_54o0Q.png" /><figcaption>Photo by <a href="https://unsplash.com/@davidclode?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">David Clode</a> on <a href="https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>It’s a meme borne of frustration, but when it comes to <strong>how</strong> a customer or user experiences a product, <em>they cannot be wrong</em>. It’s a tenet of user experience (UX) design that one should pay attention to what a user is doing and thinking when using a website or app. This applies even for specialist users, like data scientists or software engineers using a library. By carefully observing how a product is used in practice and understanding the cause of even the smallest mistake, an engineer is empowered to make dramatic improvements to its usability.</p><p>The <a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> library is part of a project of <a href="https://medium.com/stellargraph/belting-out-the-chorus-e-d-for-graph-machine-learning-in-a-distributed-multidisciplinary-team-8423037dcbb7">multidisciplinary experts</a>, and the <a href="https://github.com/stellargraph/stellargraph/graphs/contributors">developers</a> of the library apply this UX-focused thinking. The library is more usable, practical and has fewer avenues for common mistakes and problems because of this. We try to be as helpful as possible when a user has a problem, even if it’s something “trivial”, both by providing an immediate solution, and by thinking about how to stop the problem happening again!</p><blockquote><a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> is an open source library for graph machine learning. A <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graph</a> is a collection of nodes and the edges between them, where the edges represent some connection or relationship between the nodes. <a href="https://medium.com/stellargraph/knowing-your-neighbours-machine-learning-on-graphs-9b7c3d0d5896">Graph machine learning</a> takes conventional machine learning models like <a href="https://en.wikipedia.org/wiki/Multilayer_perceptron">multilayer perceptron</a> and <a href="https://en.wikipedia.org/wiki/Long_short-term_memory">long short-term memory</a> that apply to single data points (representing individual nodes) and augments them to use the information provided by each data point’s connections.</blockquote><h3>The approach</h3><p>The StellarGraph team takes two simple approaches to user observation:</p><ul><li><strong>User feedback</strong>: indirect observation by paying attention to the issues and questions people have.</li><li><strong>Usability testing</strong>: directly observing individuals actually using the library.</li></ul><p>Both of these approaches are driven by taking raw user experiences and then <strong>sifting down to a small number of key insights and actions</strong>.</p><h3>Indirect observation</h3><p>Issues reported by users are a treasure trove of hints about deeper underlying problems. For StellarGraph, we went through the issues helpfully filed by people using the library and extracted some key observations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WPsgwgBfbnkQsbjk" /><figcaption><em>A subset of a spreadsheet summarising the external issues filed against StellarGraph. The “Count” row hints at some common trends: lots of version mismatches, lots of heterogeneous graphs, lots of node classification tasks.</em></figcaption></figure><p>The process was not complicated:</p><ol><li><strong>Find </strong><a href="https://github.com/stellargraph/stellargraph/issues"><strong>issues</strong></a> from outside the team (we add <a href="https://github.com/stellargraph/stellargraph/issues?q=label%3Aexternal">an “external” label</a> to these issues as they are filed).</li><li><strong>Add a row</strong> for each issue to a spreadsheet and <strong>fill out columns</strong> with information like the kind of task(s) being solved, the library functionality being used, and the kind of request: is it a new feature? A bug? Something already supported and working, but not able to be found or understood by the user?</li><li>After filling out the spreadsheet for each issue, <strong>look for common trends</strong>, such as common categories of issues.</li></ol><p>For StellarGraph, this process immediately flagged a few “procedural” issues that occurred often. In some contexts, these might be considered invalid or “not an issue”, but we agreed they represented problems that we could put some effort into solving. Two of the most common are:</p><ul><li><strong>Version mismatches, </strong>where a user was running a demo notebook from one version with a different version of the library. Before the 1.0 release, breaking changes between versions were common, and so this mismatch resulted in confusing errors. We filed <a href="https://github.com/stellargraph/stellargraph/issues/1172">#1172</a> and addressed it in <a href="https://github.com/stellargraph/stellargraph/pull/1242">#1242</a>, by adding a version check to each notebook.</li><li><strong>Failure to find an appropriate demo notebook</strong>, where the user didn’t manage to find one of the many demos for a task already solved by StellarGraph. We filed <a href="https://github.com/stellargraph/stellargraph/issues/1087">#1087</a>, and progressively addressed it in <a href="https://github.com/stellargraph/stellargraph/pull/1200">#1200</a> and beyond, by creating clearer tables and indexing to highlight which demos are available (<a href="https://stellargraph.readthedocs.io/en/stable/demos/index.html">current version</a>).</li></ul><p>With this form of indirect observation, properly validating any changes is hard: we can only pay careful attention and notice whether fewer issues for each class of problem are filed. For StellarGraph, we try to release every month, to ensure users get the latest polish quickly.</p><h3>Direct observation</h3><p>Watching users using the product live is more effective than indirect observation. It’s more labour intensive, and more effort; but it’s much easier to notice and understand problems.</p><p>We took this approach for StellarGraph — via the <a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">“dogfooding”</a> method — just before <a href="https://medium.com/stellargraph/stellargraph-1-0-taking-graph-machine-learning-to-a-new-level-2bd6a04fbc77?source=friends_link&amp;sk=563461b77974972d3fab5b62ee15018c">the library’s 1.0 release</a> by watching colleagues from other projects use the library. This process was also not complicated:</p><ol><li>Create some <strong>problem sets</strong> that focus on relevant areas of the library to be tested (this is optional, if users have existing problems or tasks using the product), and let each person choose a task.</li><li>Have someone <strong>watch each person write code</strong> using the library to solve the task, transcribing the work and any discussion as verbatim as possible (only for people who were comfortable with this).</li><li>Otherwise, each person can <strong>take notes</strong> about confusing things, as well as <strong>discuss</strong> occasionally during the task, and then <strong>walk through</strong> the resulting code.</li><li>After collecting all the transcriptions, notes and final code, <strong>look for common trends.</strong></li></ol><p>What’s most critical here is that the StellarGraph library team were <strong>just observing: not helping</strong>. By helping, explaining or defending something we may have enabled the user to solve the specific problem more easily, but we would also be contaminating the insights with our expertise and background. By <em>observing, </em>we got a more accurate idea of the experience of the user; someone who won’t have spent months writing the library itself, and also won’t have live access to those developers to ask questions.</p><p>We did help when someone got completely stuck, but only after understanding and writing down how and why they were stuck.</p><p>This process is fundamentally designed to <strong>test the library, not the individuals using it</strong>. If a user struggles to complete something, that represents a problem in the library, not a failure of the user. Humans are wired to feel bad if they’re unable to do something, so reassurance and a good rapport between observer and user was helpful.</p><blockquote>If a user struggles to complete something, that represents a problem in the library, not a failure of the user.</blockquote><p>Similar to the indirect observation, we turned the common threads into <a href="https://github.com/stellargraph/stellargraph/issues?q=is%3Aissue+label%3Adogfooding+">a variety of issues</a> and worked through the most important ones before the 1.0.0 release, giving it an extra piece of polish.</p><h3>Finding the nuggets of gold</h3><p>How did we take the spreadsheet of issues or dogfooding notes and extract the core problems? You may see a pattern forming; this process was straightforward too.</p><p>In UX terms, we used a combination of analysis and synthesis:</p><ol><li><strong>Start a spreadsheet</strong> with columns “Summary” and “Description”.</li><li>Read through the dogfooding nodes (or spreadsheet of issues) and <strong>summarise each distinct problem</strong> into the Summary column. Quotes and more information should be included in the Description column, in order to <strong>understand the underlying cause or mental model</strong> that led to the problem. In many cases, more than one user will encounter a particular problem, and so the summary and description can be tweaked and expanded as one reads through the raw notes. We also summarised the nice experiences people shared, so this wasn’t just a long list of negative things!</li><li><strong>Create issues</strong> with actions to address the underlying problems.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*aG09N4oTcIb1a7CB" /><figcaption><em>A snippet of the “distillation” spreadsheet for the pre-1.0 StellarGraph dogfooding. After finding the common threads, we added an “Issues” column to keep track of the issues we filed for each one. We encouraged ourselves with some 🎉 cheering 🎉 for the positive things people noticed.</em></figcaption></figure><p>After doing this process for both indirect and direct observation, we had a reasonable idea of the many good and bad aspects of the library. We try to improve on the good aspects, and make changes to stop or minimise the bad.</p><h3>In summary —</h3><p>In applying a few straightforward UX processes to our development, the <a href="https://github.com/stellargraph/stellargraph/graphs/contributors">team</a> of software engineers and researchers working on the <a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> library gained superpowers. We could streamline the library, making it more usable and minimising common mistakes. We avoided blaming users, and recognised that even “silly” questions can represent an underlying issue that can be fixed.</p><p>You’ll see this super-powered polish in <a href="https://github.com/stellargraph/stellargraph/releases/tag/v1.1.0">StellarGraph version 1.1</a>, released this week. Get started with graph machine learning with pip install stellargraph, and following <a href="https://stellargraph.readthedocs.io/en/v1.1.0/demos/node-classification/gcn-node-classification.html">the node classification with GCN demo</a>.</p><p><em>The UX approach here is imitating StellarGraph’s UX experts </em><a href="https://www.linkedin.com/in/georgina-ibarra-1934552/"><em>Georgina Ibarra</em></a><em> and </em><a href="https://www.linkedin.com/in/nhungnguyenux/"><em>Nhung Nguyen</em></a><em>. This post and the observation described was also partially inspired by </em><a href="https://twitter.com/chandlerc1024/status/1243673009845440512"><em>a tweet thread</em></a><em>.</em></p><p><em>This work is supported by CSIRO’s Data61, Australia’s leading digital research network.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/1*w2DqNdSNW9xLOIEY2Biosg.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7de1ae0297be" width="1" height="1" alt=""><hr><p><a href="https://medium.com/stellargraph/the-customer-is-always-right-user-observation-is-an-engineering-superpower-7de1ae0297be">The customer is always right: user observation is an engineering superpower</a> was originally published in <a href="https://medium.com/stellargraph">stellargraph</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Do I know you? Flexible unsupervised and semi-supervised graph models with Deep Graph Infomax]]></title>
            <link>https://medium.com/stellargraph/do-i-know-you-flexible-unsupervised-and-semi-supervised-graph-models-with-deep-graph-infomax-96fbfd63ec31?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/96fbfd63ec31</guid>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[tensorflow]]></category>
            <category><![CDATA[graph-analytics]]></category>
            <category><![CDATA[algorithms]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Wed, 27 May 2020 00:01:58 GMT</pubDate>
            <atom:updated>2020-05-27T00:15:06.532Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Kg2jh-TjrbaqPTQem7GJxg.png" /><figcaption>Photo by <a href="https://unsplash.com/@sebaspenalambarri?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Sebastian Pena Lambarri</a> on <a href="https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Imagine you could feed your data directly into a machine learning model and have it learn, without the need for any manual labelling. Imagine predictions in data-sparse environments could be improved without needing to label more data or even adjust the model structure. Thanks to <a href="https://arxiv.org/abs/1809.10341">Deep Graph Infomax</a> — a graph machine learning algorithm that uses the graph structure to understand patterns in the data associated with each node — these are welcome realities.</p><p>Deep Graph Infomax is an <a href="https://en.wikipedia.org/wiki/Unsupervised_learning">unsupervised</a> training procedure. A typical supervised task matches input data against input labels, to learn patterns in the data that are associated with the labels. Deep Graph Infomax skips the labels, and instead guides a model to learn from how input data points are connected as a graph, by understanding what should or shouldn’t be linked. It can thus be used for both unsupervised representations for these points and also pre-training a model to improve performance of semi-supervised tasks without much labelled data.</p><p>A <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graph</a> is a collection of nodes and the edges between them, where the edges represent some connection or relationship between the nodes. <a href="https://medium.com/stellargraph/knowing-your-neighbours-machine-learning-on-graphs-9b7c3d0d5896">Graph machine learning</a> takes conventional machine learning models like <a href="https://en.wikipedia.org/wiki/Multilayer_perceptron">multilayer perceptron</a> and <a href="https://en.wikipedia.org/wiki/Long_short-term_memory">long short-term memory</a> that apply to single data points (representing individual nodes) and augments them to use the information provided by each data point’s connections.</p><p>The <a href="https://github.com/stellargraph/stellargraph">StellarGraph library</a> implements <a href="https://stellargraph.readthedocs.io/en/stable/demos/embeddings/deep-graph-infomax-embeddings.html">Deep Graph Infomax</a> as a flexible training procedure for most of the models StellarGraph supports, as <a href="https://stellargraph.readthedocs.io/en/stable/demos/embeddings/index.html">one of several methods</a> that work without supervision. StellarGraph is an open source, user-friendly library for graph machine learning built on Tensorflow Keras.</p><h3>Step-by-step: true versus corrupted</h3><p>The core idea is learning to distinguish between the nodes of two graphs:</p><ul><li>A true graph, consisting of the real nodes and the edges that connect them, along with feature vectors associated with each node</li><li>A corrupted graph, where the nodes and edges have been changed in some manner</li></ul><p>A Deep Graph Infomax training procedure starts with the graph <em>G</em> and has four components:</p><ul><li><strong>A corruption procedure <em>C</em>. </strong>The corruption procedure changes the true input graph <em>G</em> into the mutated version <em>H = C(G)</em>. <a href="https://arxiv.org/abs/1809.10341">The paper</a> suggests randomly shuffling the node features among the nodes: <em>H</em> has the same edges as <em>G</em>, but the features associated with each node differ.</li><li><strong>An encoder <em>E</em>.</strong> The encoder takes an input graph and computes an embedding vector <em>v </em>for each node. It is typically some graph machine learning model such as <a href="https://stellargraph.readthedocs.io/en/stable/demos/node-classification/gcn-node-classification.html">GCN</a> or <a href="https://stellargraph.readthedocs.io/en/stable/demos/node-classification/graphsage-node-classification.html">GraphSAGE</a>.</li><li><strong>A read-out <em>R</em>.</strong> The read-out collapses the separate embedding vectors for each node in a graph into a single summary vector <em>s</em> for the whole graph, like <em>s = R(E(G))</em>. This can be as simple as the sum or average, or something more complicated.</li><li><strong>A discriminator <em>D</em>.</strong> The discriminator compares a node embedding vector against the graph summary vector, like <em>D(v, s)</em>, to yield a “score” between 0 and 1 for each node embedding vector.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wr9PAt3lAu6dnb3fZTKApA.png" /><figcaption><em>The Deep Graph Infomax algorithm, as a flow chart (adapted from Figure 1 in </em><a href="https://arxiv.org/abs/1809.10341"><em>the paper</em></a><em>). The input data is fed in as a graph G in the top left corner.</em></figcaption></figure><p>Starting with an input “true” graph <em>G</em>, the forward pass of a Deep Graph Infomax model mirrors those components very closely:</p><ol><li><strong>Corrupt</strong> <em>G</em> to a new graph:<strong> </strong><em>H = C(G)</em></li><li><strong>Encode </strong>each node of both of these graphs: <em>E(G)</em> and <em>E(H)</em></li><li><strong>Summarise</strong> the true graph into a summary vector: <em>s = R(E(G))</em></li><li><strong>Score</strong> the encoded embedding vectors of both <em>G</em> and <em>H</em>, using the discriminator and <em>G</em>’s summary vector <em>s</em>: <em>D(v, s)</em> for <em>v</em> in <em>E(G) </em>and <em>E(H)</em></li><li><strong>Collate</strong> all the scores in a loss function (equation (1), in <a href="https://arxiv.org/abs/1809.10341">the paper</a>) that tries to maximise <em>D(v, s)</em> if <em>v</em> is the embedding vector of a true node and minimise it if <em>v</em> is the embedding vector of a corrupted node.</li></ol><p>After training, this will have the discriminator gives scores close to 1 for the true nodes, and scores close to 0 for the corrupted nodes. As part of this, the weights of the encoder model are trained to be useful for this distinguishing step. Once training has completed, the encoder model can be used independently to compute node embedding vectors directly.</p><p>The algorithmic description tells us the individual steps, but it doesn’t give us a great intuition for what’s happening.</p><h3>Intuition: identifying sensible connections</h3><p>Deep Graph Infomax learns to tell which nodes should be connected. By shuffling the node features, nodes end up connected in “strange” ways. The model learns to distinguish between nodes that have sensible connections and nodes that have weird or unexpected connections.</p><p>Most graph algorithms summarise the neighbourhood of a node to compute a representation or embedding vector. The shuffling will change the shape and content of those neighbourhoods, in a way that the model/encoder <em>E</em> can learn to capture.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6kRBn59UtZdqGefHFeDPHQ.png" /><figcaption><em>A simplified family tree could be a graph of people with edges from (biological) parent to child. The true graph G has patterns associated with the edges like “</em><em>source age &gt; target age&quot;, while the corrupted graph H does not. Deep Graph Infomax can help a model learn the difference.</em></figcaption></figure><p>For example, in a (biological) family tree with ages included as a data, a neighbourhood of a node (person) will be connected to two older nodes (parents), and zero or more younger nodes (children). If the edges are directed from parent to child, there’s rules like parents being older than children. Even without edge direction, there’s still rules like being connected to only two older nodes. There’s also softer trends, like the ages should be far enough apart, but not too far, reflecting the reasonable range of ages when people have children.</p><p>If the features (ages) are shuffled, these rules and patterns are likely to disappear. The model <em>E</em>’s computed embedding vectors summarise each node’s neighbourhood, and they will reflect this change.</p><p>The summary vector <em>s</em> serves as a reference point for the comparison, as the “average” true neighbourhood.</p><h3>What’s the application?</h3><p>A model trained with Deep Graph Infomax will yield representations or embedding vectors for each node. These embedding vectors can be used for tasks like clustering, community detection and nearest neighbour searches.</p><p>They can also be used as input to downstream tasks, like node classification or regression. The vectors become inputs to another model. This does require labels for each node, but the embedding vectors already capture useful information, and so fewer labels might be necessary.</p><p>Finally, the model <em>E</em> trained by Deep Graph Infomax can also be <a href="https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn-deep-graph-infomax-fine-tuning-node-classification.html">further trained and fine-tuned</a>. The model already captures useful information, so again, fewer labels are necessary to get good results. This turns a supervised task into a semi-supervised one, where training with labels benefits from the existing patterns already captured by Deep Graph Infomax.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*Rv30dcrYj0SB9dn6e-Exng.png" /><figcaption><em>Node classification is a task that can benefit from pre-training with Deep Graph Infomax. StellarGraph’s </em><a href="https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn-deep-graph-infomax-fine-tuning-node-classification.html"><em>demo of GCN, Deep Graph Infomax and fine-tuning</em></a><em> works with just eight training examples, with one or two from each of the seven classes of nodes in the Cora dataset. Pre-training with Deep Graph Infomax and then fine-tuning with the training set gives dramatically better accuracy than just training a model directly on the training set. (Accuracies averaged across 50 runs, standard error of both is about 0.8 percentage points.)</em></figcaption></figure><h3>How to get started?</h3><p>In <a href="https://github.com/stellargraph/stellargraph">StellarGraph</a>, using Deep Graph Infomax requires three pieces:</p><ul><li>A base model and its data generator (this is the encoder <em>E</em>)</li><li>The <a href="https://stellargraph.readthedocs.io/en/stable/api.html#stellargraph.mapper.CorruptedGenerator">corrupted data generator</a> to do the feature shuffling (this is the corruption function <em>C</em>)</li><li>The <a href="https://stellargraph.readthedocs.io/en/stable/api.html#stellargraph.layer.DeepGraphInfomax">Deep Graph Infomax model</a> itself which coordinates the whole process including encoding, summarising and discriminating (this includes both the read-out <em>R</em> and the discriminator <em>D</em>).</li></ul><p>Given input data in a graph <em>G</em>, each of these points translates directly into a short snippet of code. There’s <a href="https://stellargraph.readthedocs.io/en/stable/demos/embeddings/deep-graph-infomax-embeddings.html">a narrated demo</a> that walks through the procedure, which we summarise here.</p><p>The base model is created in the same way for unsupervised training with Deep Graph Infomax and for supervised training in any normal way. For instance, we can construct a one-layer GCN model:</p><pre>base_generator = FullBatchNodeGenerator(graph)<br>base_model = GCN(<br>    layer_sizes=[128],<br>    activations=[&quot;relu&quot;], <br>    generator=base_generator<br>)</pre><p>Then, we need to create a data generator that does the shuffling of the node features. This is done with CorruptedGenerator, which automatically knows how to shuffle data for many models, including FullBatchNodeGenerator like we use for GCN:</p><pre>corrupted_generator = CorruptedGenerator(base_generator)</pre><p>Finally, we create the Deep Graph Infomax model itself, using the base GCN model and the corrupted generator. This model’s in_out_tensors yields the inputs and outputs required to build a Tensorflow Keras model, which can be trained with the conventional APIs like fit:</p><pre>infomax = DeepGraphInfomax(base_model, corrupted_generator)<br>dgi_in, dgi_out = infomax.in_out_tensors()</pre><pre>dgi_model = tf.keras.Model(inputs=dgi_in, outputs=dgi_out)</pre><p>Once the base model is trained via Deep Graph Infomax, it can be used to create a separate Keras model. This model can then be further fine-tuned with fit, or used to compute embedding vectors with predict:</p><pre>embedding_in, embedding_out = base_model.in_out_tensors()</pre><pre>embedding_model = tf.keras.Model(<br>    inputs=embedding_in, <br>    outputs=tf.squeeze(embedding_out, axis=0)<br>)</pre><p>That’s it! With a <a href="https://stellargraph.readthedocs.io/en/stable/demos/embeddings/deep-graph-infomax-embeddings.html">couple of lines of code</a>, we’ve connected a base GCN model into Deep Graph Infomax so that it can be trained without supervision, and then used the trained model to yield node embedding vectors. This is the same basic process used when <a href="https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn-deep-graph-infomax-fine-tuning-node-classification.html">fine-tuning the trained model for end-to-end node classification</a>.</p><h3>In summary —</h3><p>Deep Graph Infomax is a procedure for training graph machine learning models without supervision. It trains a model to capture patterns in the connections between nodes and their features, by contrasting true nodes against corrupted/shuffled nodes. It does this without requiring any manual labels, but can be beneficial as an initialisation or pre-training procedure when one does have some labelled data.</p><p><a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> implements it as a training procedure for many of its graph machine learning models. Run pip install stellargraph, and jump into the demos of Deep Graph Infomax for <a href="https://stellargraph.readthedocs.io/en/stable/demos/embeddings/deep-graph-infomax-embeddings.html">computing node embeddings</a> and for <a href="https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn-deep-graph-infomax-fine-tuning-node-classification.html">pre-training for data-scarce environments</a>.</p><p><em>The Deep Graph Infomax algorithm was initially implemented in StellarGraph by </em><a href="https://github.com/kieranricardo"><em>Kieran Ricardo</em></a><em>. We’re working on generalising our Deep Graph Infomax support to easily work with other algorithms, like </em><a href="https://github.com/stellargraph/stellargraph/issues/1255"><em>Relational GCN</em></a>, <a href="https://github.com/stellargraph/stellargraph/issues/1256"><em>Cluster-GCN</em></a><em> and even </em><a href="https://github.com/stellargraph/stellargraph/issues/1134"><em>generalise from nodes to whole graphs</em></a><em>.</em></p><p><em>This work is supported by CSIRO’s Data61, Australia’s leading digital research network.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/0*DXL_HUjufB9XPnnI" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=96fbfd63ec31" width="1" height="1" alt=""><hr><p><a href="https://medium.com/stellargraph/do-i-know-you-flexible-unsupervised-and-semi-supervised-graph-models-with-deep-graph-infomax-96fbfd63ec31">Do I know you? Flexible unsupervised and semi-supervised graph models with Deep Graph Infomax</a> was originally published in <a href="https://medium.com/stellargraph">stellargraph</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Faster machine learning on larger graphs: how NumPy and Pandas slashed memory and time in…]]></title>
            <link>https://medium.com/stellargraph/faster-machine-learning-on-larger-graphs-how-numpy-and-pandas-slashed-memory-and-time-in-79b6c63870ef?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/79b6c63870ef</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[numpy]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[pandas]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Thu, 07 May 2020 01:01:00 GMT</pubDate>
            <atom:updated>2020-05-07T01:01:00.989Z</atom:updated>
            <content:encoded><![CDATA[<h3>Faster machine learning on larger graphs: how NumPy and Pandas slashed memory and time in StellarGraph</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*27y0KYE3T2PZLd6IJwyvMw.png" /><figcaption>Photo by <a href="https://unsplash.com/@hassan02?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Hassan Amra</a> on <a href="https://unsplash.com/s/photos/cheetah?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>This week, <a href="https://medium.com/stellargraph/stellargraph-1-0-taking-graph-machine-learning-to-a-new-level-2bd6a04fbc77">StellarGraph released a new version</a> of its open source library for machine learning on graphs. One of the most exciting features of <a href="https://github.com/stellargraph/stellargraph/releases/">StellarGraph 1.0</a> is a new graph data structure — built using NumPy and Pandas — that results in significantly lower memory usage and faster construction times.</p><p>Consider that <a href="http://snap.stanford.edu/graphsage/">a graph created from Reddit</a>, with more than 200 thousand nodes and 11 million edges, required almost 7GB of memory with previous iterations of the library’s graph data structure. It also took 2.5 minutes to construct.</p><p>In the new StellarGraph class’s minimal form, that same Reddit graph now uses approximately 174MB. And this isn’t even a classic ‘memory versus time’ balance: the new form takes only 0.9 seconds to construct.</p><p>That is, the new StellarGraph class is <strong>40 times smaller</strong> to store and <strong>hundreds of times faster</strong> to construct than the old StellarGraph.</p><p>In this article, we’ll explore how a careful focus on <em>what works best </em>for graph machine learning — in this case replacing StellarGraph’s graph data structure from one built on NetworkX to one built using NumPy and Pandas — led to big performance enhancements in the StellarGraph class.</p><h3>A class above</h3><p>The StellarGraph library is an open source, user-friendly library for graph machine learning. A <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graph</a> is a collection of nodes and the edges between them, where the edges represent some connection or relationship between the nodes.</p><p>The core abstraction in the library is <a href="https://stellargraph.readthedocs.io/en/stable/api.html#stellargraph.StellarGraph">the StellarGraph class</a>, which is a graph data structure that manages all the information about the graph or graphs being used for machine learning.</p><p>Previous versions of the StellarGraph class were backed by <a href="https://networkx.github.io/">NetworkX</a>, which allowed for quick and effective development of many graph machine learning algorithms because of its convenient and flexible API, built using nested dictionaries.</p><p>However, this flexibility meant it wasn’t optimised for graph machine learning: NetworkX has different trade-offs than those best for machine learning, the most notable being the amount of memory required to store a graph.</p><p>So, over the releases leading up to 1.0, the NetworkX-backed graph data structure was replaced with a new one built using NumPy and Pandas.</p><h3>How does it work?</h3><p>There are three key parts to the new StellarGraph class:</p><ul><li>Efficient storage of edges</li><li>Keeping node features available for quick indexing</li><li>Support for arbitrary node IDs.</li></ul><h4>Efficient storage of edges</h4><p>The new StellarGraph class stores most of its data using NumPy arrays.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/600/1*WCqN4YoiJV6bInrepbRI2w.png" /><figcaption><em>A NumPy array can consist of a single chunk of memory with values stored inline. A Python list stores pointers to other Python objects, and each of these has extra metadata overhead, dramatically increasing the cost over NumPy.</em></figcaption></figure><p>These arrays <a href="https://docs.scipy.org/doc/numpy-1.13.0/reference/arrays.ndarray.html#internal-memory-layout-of-an-ndarray">lay data out contiguously in memory</a>, so that an array of four byte integers (like the <em>numpy.int32</em> type) requires only four bytes per element. This is different to a Python list of the same integers, which requires ten times more memory, at 43 bytes per element.</p><p>The edges of the graph are conceptually pairs of a source node ID and a target node ID, representing the connection between the two nodes. In the new StellarGraph class, the edges are stored as NumPy arrays containing the source and targets in a <a href="https://en.wikipedia.org/wiki/AoS_and_SoA">“structure of arrays”</a> style.</p><p>This explains a significant fraction of the reduction in memory use for the Reddit graph. The edge information can be placed contiguously in memory with no overhead from Python objects. By using NumPy natively, we also get to easily leverage the efficient <a href="https://docs.scipy.org/doc/scipy/reference/sparse.html">sparse matrix</a> and <a href="https://docs.scipy.org/doc/scipy/reference/sparse.csgraph.html">graph algorithms</a> provided by <a href="https://www.scipy.org/">the SciPy library</a>.</p><h4>Keeping node features available for quick indexing</h4><p>NumPy arrays are also used for node features. StellarGraph is optimised for machine learning, which typically means working with vectors of “features”, or lists of numbers that encode information about each entity. Any StellarGraph graph can have nodes of multiple types, with a different number of features associated with every node of each type.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/933/1*7ArclmLbfj1v3h2ieOIP7Q.png" /><figcaption><em>The graph on the left has two node types; “white background” and “black background”, along with some feature vectors of numbers for each. These get transformed into 2D NumPy arrays on the right, matching the order of the nodes.</em></figcaption></figure><p>The new StellarGraph class stores the node features by having a large rectangular 2D NumPy array for each node type: for a particular node type, the first row of the array represents the features for the first node of that type, similarly for the second row, and so on.</p><p>This encoding is very memory efficient, since numeric features can be all laid out with no overhead from Python objects, just like edges. It is also fast, because queries about the features of nodes at given locations in the array can be answered by slicing out rows from the array, which is implemented as native C code in the NumPy library.</p><h4>Support for arbitrary node IDs</h4><p>Querying this data structure requires some tricks. It is great for storage, but actually getting the features of a node requires knowing its location; whether it’s the first or tenth or hundredth node of its type.</p><p>One approach is to just require that all node IDs are sequential integers, starting from 0, so all graphs with three nodes have IDs 0, 1, 2. However, this makes the library hard to use with real world datasets where the IDs might be <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUIDs</a>, random values, or some other non-trivial encoding. It quickly gets more complicated in heterogeneous graphs, with more than one type of node.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/951/1*5h7anudxzVdUD9w69X8UHQ.png" /><figcaption><em>Nodes can be keyed with any ID values, by using a pandas.Index as a translation layer into numeric IDs, or ilocs. These ilocs can then be used in the NumPy arrays above.</em></figcaption></figure><p>Thus, the final key piece of the new StellarGraph class is using the <a href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Index.html">pandas.Index</a> types to provide a translation between convenient and conventional node IDs and the sequential integers so that any node ID values can work, and the users of the class don’t have to think about doing their own translation or management.</p><p>The Pandas Index types are being used as a time- and memory-efficient dictionary, mapping IDs to sequential integers (which both StellarGraph and Pandas call “ilocs”, meaning integer locations). It leverages Pandas’ optimised C and <a href="https://cython.org/">Cython</a> native code.</p><p>These ilocs are used as part of the edge storage discussed above. The ilocs are small integers, and so the contiguous layout of a NumPy array ensures our edges are always stored efficiently. Many of StellarGraph’s algorithms work directly with these ilocs, and so see no overhead due to the “fancy” IDs.</p><p><em>There are some additional details here. For example, the nodes are actually numbered globally in the index, not per type, so the graph above would have A → 2, B → 3, …, but most of these are shielded from the user.</em></p><h3>In summary —</h3><p>StellarGraph is easy to install and easy to use because it builds on the shoulders of giants.<strong> </strong>By using NumPy and Pandas we get most of the benefits of optimised native code without having to write the low-level code ourselves — which would require careful optimisation and risk serious memory-corruption bugs — or be concerned with having to carefully distribute it for every platform.</p><p>The new StellarGraph class delivered in 1.0 uses NumPy and Pandas to reduce memory use and improve speed through careful selection of the moving parts, and by focusing on <em>just what is required</em> for graph machine learning. Building on existing libraries gives us the benefits of native code without the problems.</p><p>To get started with graph machine learning with the new StellarGraph class in <a href="https://github.com/stellargraph/stellargraph">the StellarGraph library</a>, <em>pip install stellargraph</em>, and then create a new optimised graph object with your data with <em>StellarGraph(nodes, edges)</em>. There are <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/basics/loading-pandas.html">demos with all the details</a>.</p><p><em>This work involved major contributions, research and code from </em><a href="https://github.com/adocherty"><em>Andrew Docherty</em></a><em>, </em><a href="https://github.com/geoffj-d61"><em>Geoff Jarrad</em></a>, <a href="https://github.com/huonw"><em>Huon Wilson</em></a><em> and </em><a href="https://github.com/kieranricardo"><em>Kieran Ricardo</em></a><em>. We’re working on even more improvements top of this optimised base, that should improve memory use and speed even further, such as </em><a href="https://github.com/stellargraph/stellargraph/issues/718"><em>#718</em></a><em>.</em></p><p><em>This work is supported by CSIRO’s Data61, Australia’s leading digital research network.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/1*w2DqNdSNW9xLOIEY2Biosg.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=79b6c63870ef" width="1" height="1" alt=""><hr><p><a href="https://medium.com/stellargraph/faster-machine-learning-on-larger-graphs-how-numpy-and-pandas-slashed-memory-and-time-in-79b6c63870ef">Faster machine learning on larger graphs: how NumPy and Pandas slashed memory and time in…</a> was originally published in <a href="https://medium.com/stellargraph">stellargraph</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[StellarGraph 1.0 — taking graph machine learning to a new level]]></title>
            <link>https://medium.com/stellargraph/stellargraph-1-0-taking-graph-machine-learning-to-a-new-level-2bd6a04fbc77?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/2bd6a04fbc77</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Tue, 05 May 2020 13:47:45 GMT</pubDate>
            <atom:updated>2020-05-15T09:29:20.317Z</atom:updated>
            <content:encoded><![CDATA[<h3>StellarGraph 1.0 — taking graph machine learning to a new level</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*baDkYRJbHU9lNM6LgjJIZQ.png" /></figure><p>Today we delivered version 1.0 of the open-source, user-friendly <a href="https://github.com/stellargraph/stellargraph">StellarGraph library</a> for machine learning (ML) on graphs and networks. It’s the culmination of three years of active research and engineering.</p><p>StellarGraph delivers state-of-the-art algorithms and detailed examples for a broad range of tasks, not limited to:</p><ul><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/index.html"><strong>Node classification</strong></a><strong>: </strong>predicting properties of individual nodes</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/index.html"><strong>Link prediction</strong></a><strong>:</strong> predicting properties of edges, including predicting links between pairs of nodes</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/index.html"><strong>Unsupervised training</strong></a><strong>/representation learning</strong>: training models to without labelled data, allowing computing embedding vectors for nodes and edges</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/graph-classification/index.html"><strong>Graph classification</strong></a><strong>:</strong> predicting properties of whole graphs or subgraphs.</li></ul><p>StellarGraph also works with existing data science workflows, is user-friendly and has detailed narrated examples designed to serve as a starting point for tasks.</p><p>It’s a stellar package.</p><p><em>If you’re familiar with StellarGraph, </em><a href="https://github.com/stellargraph/stellargraph/releases/tag/v1.0.0"><em>the release notes</em></a><em> show all the improvements from 0.11 to 1.0.</em></p><h3>The fundamentals</h3><p>A <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graph</a> is a collection of nodes and edges between them, where the edges represent some connection or relationship between the nodes. <a href="https://medium.com/stellargraph/knowing-your-neighbours-machine-learning-on-graphs-9b7c3d0d5896">Graph machine learning</a> takes conventional machine learning models like <a href="https://en.wikipedia.org/wiki/Multilayer_perceptron">multilayer perceptron</a> and <a href="https://en.wikipedia.org/wiki/Long_short-term_memory">long short-term memory</a> that apply to single data points (representing individual nodes) and augments them to use the information provided by each data point’s connections.</p><p>StellarGraph is built using standard data science technologies like TensorFlow Keras, Pandas and NumPy. It is designed to integrate smoothly into existing data science workflows, by letting users leverage their existing skills and the plethora of learning materials for pre-processing, analysis and visualisation with tools like Pandas, Jupyter and scikit-learn.</p><p>StellarGraph’s graph machine learning models are built using the Keras functional API and operate as standard layers, making it easy to include graph ML models in a larger pipeline.</p><p>To get started with graph machine learning with StellarGraph 1.0, run <em>pip install stellargraph</em>, and then build a model for your task. Follow <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/index.html">one of our examples</a>, like doing <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/gcn-node-classification.html">node classification with Graph Convolutional Networks</a>.</p><h3>State of the art algorithms</h3><p>StellarGraph has broad coverage of state-of-the-art graph ML algorithms:</p><ul><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/gcn-node-classification.html">Graph Convolutional Network</a> (GCN) and the <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/cluster-gcn-node-classification.html">Cluster-GCN</a> training method</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/gat-node-classification.html">Graph Attention Network</a> (GAT)</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/ppnp-node-classification.html">Personalized Propagation of Neural Predictions (PPNP) and Approximate PPNP (APPNP)</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/graphsage-node-classification.html">GraphSAGE</a> and a generalisation <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/hinsage-link-prediction.html">HinSAGE</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/rgcn-node-classification.html">Relational GCN</a> (RGCN)</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/attri2vec-link-prediction.html">Attri2Vec</a></li><li>Random walk methods like <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/node2vec-embeddings.html">Node2Vec</a>, <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/metapath2vec-embeddings.html">Metapath2Vec</a> and <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/ctdne-link-prediction.html">Continuous-Time Dynamic Network Embeddings</a> (CTDNE)</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/graphwave-embeddings.html">GraphWave</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/deep-graph-infomax-embeddings.html">Deep Graph Infomax</a>, generalised to support unsupervised training of many of the algorithms listed here</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/graph-classification/dgcnn-graph-classification.html">Deep Graph Convolutional Neural Network</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/time-series/gcn-lstm-time-series.html">Temporal GCN</a> (T-GCN)</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/sgc-node-classification.html">Simplified Graph Convolution</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/complex-link-prediction.html">ComplEx</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/distmult-link-prediction.html">DistMult</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/embeddings/watch-your-step-embeddings.html">Watch Your Step</a></li></ul><p>These algorithms solve all of the tasks mentioned above. They can be used with a variety of graphs and graph kinds, such as:</p><ul><li>Graphs that include time information, both in the <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/ctdne-link-prediction.html">graph structure</a> and as <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/time-series/index.html">node features as time series (such as spatio-temporal data</a></li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/hinsage-link-prediction.html">Heterogeneous graphs</a>, that have multiple types of nodes connected via multiple types of edges</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/link-prediction/complex-link-prediction.html">Knowledge graphs</a>, that represent information entirely in the graph structure.</li></ul><h3>Your data, your way</h3><p>StellarGraph knows that data preparation is always more work than expected, so it makes this as conventional and as convenient as possible. StellarGraph allows using many common data science libraries and tools, so there’s no need to learn new APIs. This includes:</p><ul><li>NumPy and <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/basics/loading-pandas.html">Pandas natively supported</a>, allowing the use of their processing facilities, as well as libraries like scitkit-learn</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/basics/loading-networkx.html">Conversion to and from NetworkX</a></li><li>Guidance for <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/basics/loading-saving-neo4j.html">reading data from and saving results to Neo4j</a>.</li></ul><p>Each algorithm is built from Tensorflow Keras layers and yields tensors like the standard layers, allowing a graph machine learning model to be augmented with any Tensorflow functionality. This includes adding additional layers after the StellarGraph graph layers to improve model performance, and using any of the built-in callbacks and metrics for controlling and introspecting the training and prediction process.</p><h3>Great documentation</h3><p>StellarGraph makes it easy to get started with any algorithm, with a focus on detailed documentation and demonstration Jupyter notebooks. We see creating great demonstrations as an important step when adding new algorithms — not something we do as an afterthought.</p><p>Our documentation has:</p><ul><li>A <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/index.html">helpful layout</a>, with information about each algorithm and each demo clearly laid out</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/basics/index.html">Introduction to loading data</a> from many formats.</li><li><a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/gcn-node-classification.html">Introduction to graph machine learning</a>, including the typical workflow with StellarGraph</li><li>Easy access to start running and editing each notebook, where each one includes a download button and one-click execute buttons to run on cloud services like <a href="https://mybinder.org/v2/gh/stellargraph/stellargraph/master?urlpath=lab/tree/demos/node-classification/gcn-node-classification.ipynb">Binder</a> and <a href="https://colab.research.google.com/github/stellargraph/stellargraph/blob/master/demos/node-classification/gcn-node-classification.ipynb">Google Colaboratory</a></li><li>Many tasters of downstream tasks, giving examples of additional analysis that one can do beyond the basic training and evaluation</li><li><a href="https://medium.com/stellargraph/better-notebooks-through-ci-automatically-testing-documentation-for-graph-machine-learning-5789e277e597">Detailed testing and validation</a> so the demonstrations always work, reducing confusion and frustration.</li></ul><p>The demonstrations serve as great starting points for many graph machine learning tasks, making it easy to jump in and test with your data.</p><h3>Thanks</h3><p>StellarGraph is a team effort. It has involved dozens of hard-working contributors, helping with writing, testing and refining our code, documentation and blog posts:</p><ul><li><a href="https://github.com/arc0">Alex Collins</a></li><li><a href="https://github.com/adocherty">Andrew Docherty</a></li><li><a href="https://github.com/annitrolla">Anna Leontjeva</a></li><li><a href="https://github.com/hd-chuong">Chuong Ho</a></li><li><a href="https://github.com/daokunzhang">Daokun Zhang</a></li><li><a href="https://github.com/cdawei">Dawei Chen</a></li><li><a href="https://github.com/TheDen">Denis Khoshaba</a></li><li><a href="https://github.com/geoffj-d61">Geoff Jarrad</a></li><li><a href="https://github.com/habiba-h">Habiba @habiba-h</a></li><li><a href="https://github.com/sktzwhj">Huijun Wu</a></li><li><a href="https://github.com/huonw">Huon Wilson</a></li><li><a href="https://github.com/wangzhen263">Jeff (Zhen) Wang</a></li><li><a href="https://github.com/thatlittleboy">Jeremy Goh</a></li><li><a href="https://github.com/jessclmoore">Jess Moore</a></li><li><a href="https://github.com/kjun9">Kevin Jung</a></li><li><a href="https://github.com/kieranricardo">Kieran Ricardo</a></li><li><a href="https://github.com/kiarie-ndegwa">Kiarie Ndegwa</a></li><li><a href="https://github.com/LarsNeR">Lars @LarsNeR</a></li><li><a href="https://www.linkedin.com/in/leda-kalleske-700280a">Leda Kalleske</a></li><li><a href="https://github.com/PantelisElinas">Pantelis Elinas</a></li><li><a href="https://github.com/pspeter">Peter Schmidbauer</a></li><li><a href="https://github.com/thanh-nm">Thanh Nguyen Mueller</a></li><li><a href="https://github.com/timpitman">Tim Pitman</a></li><li><a href="https://github.com/youph">Yuriy Tyshetskiy</a></li><li><a href="https://www.linkedin.com/in/vonpoon">Yvonne Poon</a></li></ul><p>StellarGraph has also benefited enormously from users who have taken the time to ask questions and file thoughtful issues.</p><p><strong>Thank you!</strong></p><p>To get started with graph machine learning with StellarGraph 1.0, run <em>pip install stellargraph</em>. Follow <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/index.html">one of our examples</a>, like doing <a href="https://stellargraph.readthedocs.io/en/v1.0.0/demos/node-classification/gcn-node-classification.html">node classification with Graph Convolutional Networks</a>.</p><p><em>This work is supported by CSIRO’s Data61, Australia’s leading digital research network.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/1*w2DqNdSNW9xLOIEY2Biosg.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2bd6a04fbc77" width="1" height="1" alt=""><hr><p><a href="https://medium.com/stellargraph/stellargraph-1-0-taking-graph-machine-learning-to-a-new-level-2bd6a04fbc77">StellarGraph 1.0 — taking graph machine learning to a new level</a> was originally published in <a href="https://medium.com/stellargraph">stellargraph</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Better notebooks through CI: automatically testing documentation for graph machine learning]]></title>
            <link>https://medium.com/stellargraph/better-notebooks-through-ci-automatically-testing-documentation-for-graph-machine-learning-5789e277e597?source=rss-340a09703a3a------2</link>
            <guid isPermaLink="false">https://medium.com/p/5789e277e597</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[continuous-integration]]></category>
            <dc:creator><![CDATA[Huon Wilson]]></dc:creator>
            <pubDate>Wed, 08 Apr 2020 01:01:01 GMT</pubDate>
            <atom:updated>2020-06-03T23:28:07.429Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_2mcFRf5nzJMFtRoYN-N_Q.png" /><figcaption>Photo by <a href="https://unsplash.com/@martinadams?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Martin Adams</a> on <a href="https://unsplash.com/s/photos/kite?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Building a data science library is walking between two worlds: data science is dominated by Python notebooks, a fast and convenient way to experiment and demonstrate code in the browser, while software engineering focuses on making software reliable and repeatable. <a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> uses continuous integration to keep the benefits of both.</p><p>StellarGraph is an open source, user-friendly Python library for <a href="https://medium.com/stellargraph/knowing-your-neighbours-machine-learning-on-graphs-9b7c3d0d5896">graph machine learning</a> built on TensorFlow and Keras. It provides <a href="https://stellargraph.readthedocs.io/en/stable/demos/index.html">a lot of demonstrations</a> of its functionality, in the form of <a href="https://jupyter.org/">Jupyter notebooks</a>, to get data scientists and anyone else started on solving their real-world problems. The demos are viewable directly on GitHub, and even have links to run automatically in the <a href="https://mybinder.org/">Binder</a> and <a href="https://colab.research.google.com/">Google Colab</a> cloud services.</p><p>With the release of StellarGraph version 1.0 planned later this month, we’ve developed automatic processes so that our demos work — and will continue to work — even as we make major enhancements to the library.</p><p>In this article, we’ll walk through the detailed and helpful continuous integration (CI) that supports us in keeping the library’s demos current and informative.</p><h3>How it works</h3><p>StellarGraph’s CI for notebooks works in three main ways:</p><ul><li>Validates that every notebook is <strong>up to date and runs successfully</strong>, using <a href="https://papermill.readthedocs.io/en/latest/">papermill</a><strong> </strong>to <strong>keep CI fast</strong> for a good developer experience</li><li>Provides links to <a href="https://nbviewer.jupyter.org/">nbviewer</a> to <strong>view failures conveniently</strong> in a nicely rendered way, directly in the browser</li><li>Checks that we’re providing <strong>a consistent experience</strong> by ensuring every notebook has links to cloud services and the same formatting, via <a href="https://github.com/psf/black">black</a> and custom code.</li></ul><p>Let’s look at the finer details of each of these.</p><h3>High velocity; reliable; humans — pick two</h3><p>Documentation and examples are most useful when they’re accurate. StellarGraph is an active project with <a href="https://github.com/stellargraph/stellargraph/pulse/monthly">constant improvements and bug fixes</a>; many of these allow us to make our notebooks better, and some changes require adjusting a notebook or two. All of this has to be done <em>perfectly</em>.</p><p>Our goal is to make sure <strong>every demo works every time</strong>, following the <a href="https://graydon2.dreamwidth.org/1597.html">“not rocket science” rule of software engineering</a>. It’s much easier to keep notebooks working on a pull-request-by pull-request basis. If we don’t keep them up to date, it may take us a long time to even realise they’re broken, let alone diagnose the cause and fix them.</p><p>We are careful, and update and rerun notebooks as required, but it’s easy for humans to make mistakes. StellarGraph has more than 40 notebooks, and about 25 pull requests being merged each week. This means that even a low rate of mistakes still results in a <em>lot</em> of broken notebooks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*tfrPmKCZqdSdOhxQ" /><figcaption><em>Software rot: With 25 pull requests a week and even a low chance of each pull request breaking a notebook (1%), the probability of all notebooks working quickly decreases to zero.</em></figcaption></figure><p>For instance, suppose each pull request has only a 1% chance of making some notebooks stop working. Be it a small chance, this would mean that there’s only a 78% chance of all notebooks working after a week, and less than 40% chance of all notebooks working after a month.</p><p>We try to keep our notebooks working with manual code review, using the <a href="https://www.reviewnb.com/">ReviewNB</a> app. ReviewNB provides more useful diffs than the raw JSON, making it easy to discuss good and not-so-good changes. However, humans are fallible and can miss problems. Furthermore, code review only highlights notebooks that have had edits; it does not highlight notebooks that <em>should</em> have edits!</p><h3>Automatically-run notebooks</h3><p>To help us humans, we utilise computers to check the notebooks too: CI checks that most of them run properly on every pull request and every merge, in addition to the unit tests. But CI works best if it is fast, and, as most of our notebooks demonstrate heavyweight machine learning, <em>it’s not fast enough</em>.</p><p>The easiest way to reduce CI time is to do work in parallel. Almost all of the notebooks depend solely on the StellarGraph library, so they can be executed independently of each other. We <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/.buildkite/steps/test-demo-notebooks.sh">run</a> them <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/.buildkite/pipeline.yml#L86">concurrently</a> using a <a href="https://buildkite.com/docs/tutorials/parallel-builds#parallel-jobs">parallel job</a> on <a href="https://buildkite.com/">Buildkite CI</a>, but it’s still not enough: some of the notebooks individually take too long.</p><p>We use <a href="https://papermill.readthedocs.io/en/latest/">papermill</a> to <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/.buildkite/steps/test-single-notebook.sh#L14">execute our notebooks</a> because it supports <a href="https://papermill.readthedocs.io/en/latest/usage-parameterize.html">parameterisation</a>: when running on CI, our notebooks train their models for less time, or compute shorter random walks, or other optimisations.</p><p>Papermill’s parameterisation allows this to be done without having to add ugly “are we on CI” conditional code to each demo. For notebooks that need parameterisation, we only need to refactor slightly to have a single cell that contains the parameters that need to be adjusted. Then, new values can be substituted in via <a href="https://github.com/stellargraph/stellargraph/blob/develop/.buildkite/notebook-parameters.yml">a YAML file</a> and the parameters_file option.</p><p>These notebooks are running transiently on CI, so the accuracy of the model isn’t so important. The main thing that’s needed is the execution of every code path, to validate that it all works. We optimise parameters to be as small as possible while still exercising every edge case, such as only reducing the number of training epochs to two instead of one, to catch any problems that occur between epochs.</p><p>If there’s a problem, like function arguments changing or even running out of memory, the notebook will fail to run and our testing fails. This tells us immediately that more changes are required to keep everything working.</p><h3>Highlighting errors with Buildkite artifacts and annotations</h3><p>CI helps us see when something has gone wrong, but it’s even better to know the exact problem. Papermill is helpful by logging all of the stdout and stderr output of the notebook; but digging through verbose CI logs is cumbersome. Furthermore, these logs often don’t have enough context to easily understand the problem especially compared to the rendered view of a notebook, where the error is attached to an individual cell, along with any other relevant cells.</p><p>After running a notebook, the CI <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/.buildkite/steps/test-single-notebook.sh#L18-L20">attaches the resulting notebook</a> as <a href="https://buildkite.com/docs/pipelines/artifacts">an “artifact”</a> to the step that ran it, whether it passed or not. If execution failed, this output notebook will include the exception or other error inside it.</p><p>We’re using a <a href="https://buildkite.com/stellar/stellargraph-public">public pipeline on Buildkite</a>, so the artifacts are publicly viewable, meaning the pull request author — or anyone else — can click through and download them to inspect the problems.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AE5amw1s9SkgmWl7aqW6Yw.png" /><figcaption><em>When </em><a href="https://github.com/stellargraph/stellargraph/pull/1215"><em>a notebook fails on CI</em></a><em>, a link to </em><a href="https://nbviewer.jupyter.org/urls/buildkite.com/organizations/stellar/pipelines/stellargraph-public/builds/2998/jobs/3203e1e3-77c6-45a5-a1b0-bb2fec15f795/artifacts/0d8d3f6e-f14e-4475-9d08-3921a3db1847"><em>view the failed notebook</em></a><em> on nbviewer is automatically </em><a href="https://buildkite.com/stellar/stellargraph-public/builds/2998#annotation-gcn-cora-node-classification-example.ipynb-3203e1e3-77c6-45a5-a1b0-bb2fec15f795"><em>added to the build</em></a><em>.</em></figcaption></figure><p>We do a lot more with Buildkite too. <a href="https://nbviewer.jupyter.org/">Nbviewer</a> can render any public Jupyter notebook URL, including these artifacts. Our CI creates links to view them directly in the browser and, for notebooks that failed, <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/.buildkite/steps/test-single-notebook.sh#L35-L43">adds an annotation</a> to the top of the build with that link. All it takes to understand the problem is to view the failing build and click on one of the highlighted links.</p><h3>A consistent demo experience</h3><p>StellarGraph works to provide a consistent experience for each demo because this makes it easier for:</p><ul><li>users of StellarGraph to switch between demos without having to understand the idiosyncrasies of each one</li><li>developers of StellarGraph to write and edit the notebooks, because more parts of the process have an expected behaviour, and there’s no time-wasting on things like formatting</li><li>automatic tools to help us maintain demos, because the input notebooks are more structured.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/924/1*CsqSGi9ih4iQnO7Kl99Xbg.png" /><figcaption><em>The Binder button in a notebook, like the one in </em><a href="https://github.com/stellargraph/stellargraph/blob/master/demos/node-classification/gcn/gcn-cora-node-classification-example.ipynb"><em>the introductory node classification demo using GCN</em></a><em>, takes readers directly to </em><a href="https://mybinder.org/v2/gh/stellargraph/stellargraph/master?urlpath=lab/tree/demos/node-classification/gcn/gcn-cora-node-classification-example.ipynb"><em>an executable environment</em></a><em> in less than one minute.</em></figcaption></figure><p>The foundational piece of this is <a href="https://github.com/stellargraph/stellargraph/blob/develop/scripts/format_notebooks.py">a custom script</a> that uses <a href="https://github.com/jupyter/nbconvert">nbconvert</a> to run some notebook preprocessors. These preprocessors do things like:</p><ul><li><a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/scripts/format_notebooks.py#L97-L124">format the code</a> with the <a href="https://github.com/psf/black">black</a> formatter</li><li><a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/scripts/format_notebooks.py#L68-L77">renumber the cell execution counts</a> from 1, so that someone making edits can run and rerun the notebook as many times as they need until it works and the notebook still shows “In [1], Out [1], In [2], Out [2], …” when published</li><li><a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/scripts/format_notebooks.py#L127-L181">insert the appropriate link</a> for each notebook to the <a href="https://mybinder.org/">Binder</a> and <a href="https://colab.research.google.com/">Google Colab</a> cloud services, so that people viewing the demos on GitHub can switch to executing them in a flash.</li></ul><p>This script makes it easy for a developer to keep the notebooks consistent by applying all that formatting directly with a single command. Unfortunately, making it easy is only half the story; requiring humans to <em>remember</em> to do it will mean it is occasionally forgotten.</p><p>The solution here is the same as for running the notebooks: check the formatting on CI. Our script supports this via a mode where it reformats the notebook to a temporary path, and then <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/scripts/format_notebooks.py#L393-L394">compares the reformatted notebook</a> with the original: they should be the same.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bteyezGvpk-GiF6xquE4_g.png" /><figcaption><em>When </em><a href="https://github.com/stellargraph/stellargraph/pull/1215"><em>notebooks aren’t formatted correctly</em></a><em>, the CI build is </em><a href="https://buildkite.com/stellar/stellargraph-public/builds/2998#annotation-format_notebooks"><em>annotated</em></a><em> with the list of those notebooks and the command to run to fix it.</em></figcaption></figure><p>If there’s a difference, the script will <a href="https://github.com/stellargraph/stellargraph/blob/59d269a10f207b6b5e5c2b891de8bd3d5408cb3b/scripts/format_notebooks.py#L426-L435">add an annotation</a> to <a href="https://buildkite.com/stellar/stellargraph-public/builds/2998#annotation-format_notebooks">the build</a> that suggests an appropriate command for fixing it.</p><h3>Conclusion</h3><p><a href="https://github.com/stellargraph/stellargraph">StellarGraph</a> prides itself on <a href="https://stellargraph.readthedocs.io/en/stable/demos/index.html">its demos</a> and we rely on automation to keep them great, even in a high-velocity project as we build up to our 1.0 release. We get a nice review experience via ReviewNB, and get alerted when a notebook fails to run or has inappropriate formatting. All of this happens before landing any changes, and problems are flagged with convenient links and suggested fixes using Buildkite CI.</p><p>All our code is <a href="https://github.com/stellargraph/stellargraph">open source</a>, so we hope by sharing others can mesh the worlds of data science and software engineering and see the benefits of both.</p><p>Get started with graph machine learning in the StellarGraph library with pip install stellargraph and our demo of <a href="https://stellargraph.readthedocs.io/en/v1.1.0/demos/node-classification/gcn-node-classification.html">node classification using a Graph Convolutional Network</a>.</p><p><em>The CI work in StellarGraph was largely done by </em><a href="https://github.com/timpitman"><em>Tim Pitman</em></a><em>, with contributions from </em><a href="https://github.com/huonw"><em>Huon Wilson</em></a><em>. The formatting script was mostly written by </em><a href="https://github.com/adocherty"><em>Andrew Docherty</em></a><em> with extensions from Tim and Huon. </em><a href="https://github.com/TheDen"><em>Denis Khoshaba</em></a><em> keeps our CI and infrastructure working smoothly. To make papermill work even better on CI, Huon </em><a href="https://github.com/nteract/papermill/pulls?q=is%3Apr+author%3Ahuonw+"><em>contributed several tweaks</em></a><em>.</em></p><p><em>This work is supported by CSIRO’s Data61, Australia’s leading digital research network.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/224/1*w2DqNdSNW9xLOIEY2Biosg.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5789e277e597" width="1" height="1" alt=""><hr><p><a href="https://medium.com/stellargraph/better-notebooks-through-ci-automatically-testing-documentation-for-graph-machine-learning-5789e277e597">Better notebooks through CI: automatically testing documentation for graph machine learning</a> was originally published in <a href="https://medium.com/stellargraph">stellargraph</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>