refscan 0.0.0__py3-none-any.whl

refscan/templates/graph.template.html

@@ -0,0 +1,297 @@
+<html>
+<head>
+    <title>refscan graph</title>
+    <style>
+        #graph-container {
+            width: 100%;
+            height: 100vh;
+        }
+        #metadata-container {
+            font-family: sans-serif;
+            font-size: 0.8em;
+            color: #999999;
+            position: absolute;
+            bottom: 1em;
+            right: 1em;
+            text-align: right;
+        }
+        #metadata-container ul {
+            list-style-type: none;
+            margin: 0;
+        }
+        .text-button {
+            color: inherit;
+            text-decoration: underline;
+            background: none;
+            border: none;
+            margin: 0;
+            padding: 0;
+            cursor: pointer;
+        }
+    </style>
+</head>
+<body>
+
+<!-- Note: A Python script will replace the `{{ ... }}` placeholders. -->
+<div
+        id="graph-data"
+        data-graph-data-json-str-base64="{{ graph_data_json_base64 }}"
+        data-graph-metadata-json-str-base64="{{ graph_metadata_json_base64 }}"
+></div>
+
+<!-- Note: The JavaScript code below will render the above graph data
+           as a graph within this HTML element. -->
+<div id="graph-container"></div>
+
+<!-- Note: The JavaScript code below will render metadata about the graph,
+           within this HTML element. -->
+<div id="metadata-container"></div>
+
+<!-- Note: The third-party JavaScript code we're loading here will add a function
+           named `cytoscape` to the `window` object (i.e. the global scope).
+           Reference: https://js.cytoscape.org/ -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.30.1/cytoscape.min.js"
+        integrity="sha512-kv2oCpI8sYlWvr442qCcFNgXW9swhLRlDJ/39GlfZLGAWOqgU/Kz30YCYBm0yLumVzRvYEMU6uSxFniGzitKiA=="
+        crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+
+<script>
+    (function () {
+        // Note: A Python script will replace the `{{ ... }}` placeholder.
+        console.log("Schema version: {{ schema_version }}");
+
+        // Extract the base64-encoded graph metadata and data from the `graph-data` HTML element.
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset
+        let graphMetadata = {};
+        let graphData = [];
+        const graphDataEl = document.getElementById("graph-data");
+        const graphMetadataJsonStrBase64 = graphDataEl.dataset.graphMetadataJsonStrBase64;
+        const graphDataJsonStrBase64 = graphDataEl.dataset.graphDataJsonStrBase64;
+
+        // Base64-decode the graph metadata and parse it as JSON.
+        try {
+            const graphMetadataJsonStr = atob(graphMetadataJsonStrBase64);
+            graphMetadata = JSON.parse(graphMetadataJsonStr);
+            console.debug("graphMetadata", graphMetadata);
+        } catch (error) {
+            alert("Failed to parse metadata.");
+            console.debug("graphMetadataJsonStrBase64", graphMetadataJsonStrBase64);
+            console.error(error);
+        }
+
+        // Display the graph metadata on the web page.
+        const metadataContainerEl = document.getElementById("metadata-container");
+        const metadataListEl = document.createElement("ul");
+        if (typeof graphMetadata["schema_version"] === "string") {
+            const li = document.createElement("li");
+            li.textContent = `Schema version ${graphMetadata["schema_version"]}`;
+            metadataListEl.appendChild(li);
+        }
+        if (typeof graphMetadata["app_version"] === "string") {
+            const li = document.createElement("li");
+            li.textContent = `refscan version ${graphMetadata["app_version"]}`;
+            metadataListEl.appendChild(li);
+        }
+        let subjectSingular = graphMetadata["subject_singular"];
+        let subjectPlural = graphMetadata["subject_plural"];
+        metadataContainerEl.appendChild(metadataListEl);
+
+        // Base64-decode the graph data and parse it as JSON.
+        try {
+            const graphDataJsonStr = atob(graphDataJsonStrBase64);
+            graphData = JSON.parse(graphDataJsonStr);
+            console.debug("graphData", graphData);
+        } catch (error) {
+            alert("Failed to parse reference data.");
+            console.debug("graphDataJsonStrBase64", graphDataJsonStrBase64);
+            console.error(error);
+        }
+
+        // Display the graph on the web page.
+        const cy = window.cytoscape({
+            container: document.getElementById("graph-container"),
+            elements: graphData,
+            layout: {
+                name: "circle" // For other options, see: https://js.cytoscape.org/#layouts
+            },
+            style: [
+                {
+                    selector: "node",
+                    style: {
+                        label: "data(id)",
+                        backgroundColor: "#666666",
+                    },
+                },
+                {
+                    selector: "edge",
+                    style: {
+                        fontSize: "0.75em",
+                        textRotation: "autorotate", // parallel to the edge
+                        lineColor: "#999999",
+                        targetArrowColor: "#999999",
+                        targetArrowShape: "triangle",
+                        curveStyle: "bezier",
+                        width: 1,
+                    },
+                },
+                {
+                    selector: "node.outgoer",
+                    style: {
+                        fontWeight: "bold",
+                        color: "#00FF00", // text color
+                        backgroundColor: "#00FF00",
+                    }
+                },
+                {
+                    selector: "edge.outgoer",
+                    style: {
+                        label: "data(label)",
+                        lineColor: "#00FF00",
+                        targetArrowColor: "#00FF00",
+                        width: 3,
+                    }
+                },
+                {
+                    selector: "node.incomer",
+                    style: {
+                        fontWeight: "bold",
+                        color: "#FFA500", // text color
+                        backgroundColor: "#FFA500",
+                    }
+                },
+                {
+                    selector: "edge.incomer",
+                    style: {
+                        label: "data(label)",
+                        lineColor: "#FFA500",
+                        targetArrowColor: "#FFA500",
+                        width: 3,
+                    }
+                },
+                {
+                    selector: "node.incomer.outgoer", // a node that is both an incomer and an outgoer
+                    style: {
+                        fontWeight: "bold",
+                        color: "#00FF00", // text color
+                        backgroundColor: "#00FF00",
+                        borderWidth: 3,
+                        borderStyle: "solid",
+                        borderColor: "#FFA500",
+                    }
+                },
+                {
+                    selector: "node.inFocus",
+                    style: {
+                        fontWeight: "bold",
+                        color: "#0000FF", // text color
+                        backgroundColor: "#0000FF"
+                    }
+                },
+                {
+                    selector: "node.isAbstract",
+                    style: {
+                        opacity: 0.5,
+                    }
+                },
+                {
+                    selector: "edge.isAbstract",
+                    style: {
+                        opacity: 0.5,
+                    }
+                },
+            ],
+        });
+
+        // Whenever the user clicks on a node, highlight that node, all the edges
+        // emanating from that node, and all the nodes those edges point to.
+        //
+        // References:
+        // - https://js.cytoscape.org/#events
+        // - https://js.cytoscape.org/#collection/traversing
+        //
+        cy.bind("tap", "node", (event) => {
+            // Remove classes from all elements.
+            cy.elements()
+                .removeClass("outgoer")
+                .removeClass("incomer")
+                .removeClass("inFocus");
+
+            // Apply classes to the target node, the arrows coming out of it,
+            // and the nodes those arrows point to.
+            event.target
+                .addClass("inFocus")
+                .outgoers()
+                .addClass("outgoer");
+
+            // Apply classes to the arrows pointing to the target node,
+            // and the nodes those arrows are coming out of.
+            event.target
+                .incomers()
+                .addClass("incomer");
+        });
+
+        // Whenever the user double-clicks on a node, un-highlight all elements.
+        cy.bind("dbltap", "node", (event) => {
+            // Remove classes from all elements.
+            cy.elements()
+                .removeClass("outgoer")
+                .removeClass("incomer")
+                .removeClass("inFocus");
+        });
+
+        /**
+         * Sets up a text button that can be used to toggle the visibility of
+         * nodes that represent abstract things.
+         */
+        function setupAbstractNodeVisibilityToggler() {
+            // Get a collection of all nodes that represent abstract things.
+            // Note: For conciseness, we refer to them as "abstract nodes" here.
+            // Reference: https://js.cytoscape.org/#eles.filter
+            const abstractNodes = cy.filter(function(el, idx, allEls) {
+                return el.isNode() && el.data("is_abstract");
+            });
+
+            // If there are any abstract nodes, give them (and the edges connected to them)
+            // a specific "stylesheet" class and set up their visibility toggler.
+            if (abstractNodes.length > 0) {
+                abstractNodes.addClass("isAbstract");
+                abstractNodes.connectedEdges().addClass("isAbstract");
+                
+                // Set up a clickable element that can be used to show/hide the abstract nodes.
+                // Note: When a node gets hidden, its connected edges will be automatically hidden also.
+                const strings = {
+                    prefix: `Abstract ${subjectPlural} are `,
+                    visible: "visible",
+                    hidden: "hidden",
+                };
+                let removedNodes = cy.collection(); // initially empty
+                const prefixEl = document.createElement("span");
+                prefixEl.textContent =strings.prefix;
+                const togglerEl = document.createElement("button");
+                togglerEl.classList.add("text-button");
+                togglerEl.title = "Toggle visibility";
+                const togglerTextEl = document.createElement("span");
+                togglerTextEl.textContent = strings.visible;
+                togglerEl.appendChild(togglerTextEl);
+                togglerEl.addEventListener("click", () => {
+                    if (removedNodes.length > 0) {
+                        // Add them back into the graph.
+                        removedNodes.restore();
+                        removedNodes = cy.collection();
+                        togglerTextEl.textContent = strings.visible;
+                    } else {
+                        // Remove them from the graph, but save them in memory.
+                        removedNodes = cy.remove(abstractNodes);
+                        togglerTextEl.textContent = strings.hidden;
+                    }
+                });
+                metadataContainerEl.appendChild(prefixEl);
+                metadataContainerEl.appendChild(togglerEl);
+            }
+        }
+
+        // Set up the abstract node visibility toggler.
+        setupAbstractNodeVisibilityToggler();
+    })();
+</script>
+</body>
+</html>

refscan-0.0.0.dist-info/LICENSE

@@ -0,0 +1,42 @@
+Refscan Copyright (c) 2024, The Regents of the University of California, 
+through  Lawrence Berkeley National Laboratory (subject to receipt of any 
+required  approvals from the U.S. Dept. of Energy).  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+(1) Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+(2) Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+(3) Neither the name of the University of California, Lawrence Berkeley
+National Laboratory, U.S. Dept. of Energy nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+You are under no obligation whatsoever to provide any bug fixes, patches,
+or upgrades to the features, functionality or performance of the source
+code ("Enhancements") to anyone; however, if you choose to make your
+Enhancements available either publicly, or directly to Lawrence Berkeley
+National Laboratory, without imposing a separate written license agreement
+for such Enhancements, then you hereby grant the following license: a
+non-exclusive, royalty-free perpetual license to install, use, modify,
+prepare derivative works, incorporate into other computer software,
+distribute, and sublicense such enhancements or derivative works thereof,
+in binary and source code form.