SNIK Graph

Visualization of the SNIK ontology using the Cytoscape.js graph library. Live at https://www.snik.eu/graph (stable) and https://snikproject.github.io/graph/index.html (master branch). Browse the code documentation here.

Installation and Preview

Node

git clone https://github.com/snikproject/graph.git
cd graph
npm install
cp js/config/config.dist.ts js/config/config.ts
npm run dev 

Open the displayed local link in a browser.

Developing On Windows

Developing on Windows is not recommended but possible with the following adaptions:

• Instead of cp js/config/config.dist.ts js/config/config.ts, do copy js\config\config.dist.ts js\config\config.ts or use the Explorer to copy the file.
• lint-staged fails on Windows with "Current directory is not a git directory!". Skip the Husky commit hook with git commit --no-verify.

Docker

git clone https://github.com/snikproject/graph.git
cd graph
docker build . -t snik-graph
docker run --network="host" snik-graph

Open http://localhost:8043/ in a browser.

When using SNIK Graph as a Git submodule, use docker build -f Dockerfile.submodule .. -t snik-graph instead, so that Git commit information can be included in the about dialogue, otherwise the build fails.

Usage Requirements

Optimized for PC with mouse, does not work well on mobile devices. Requires a browser with ES6 module support.

Documentation

• Developer Documentation
• User Manual
• Layout Help
• Troubleshooting
• SNIK Project Homepage
• generate API documentation in the docs folder with npm run doc

Configuration

SNIK Graph visualizes SNIK by default and is optimized for it but you can configure it to visualize other ontologies as well. You can use the GET parameters on any running instance to filter and tweak the view in small ways without needing to use the UI. For more complex operations, such as using your own ontology with SNIK Graph, you can use the configuration files to run your own instance.

[!NOTE] When forking, please change the git configuration keys - for example in the README and default config. If you want to use your own ontology, you need to change the ontology configuration, see below.

GET Parameters

All GET parameters are optional and must be lower case. Flags are disabled by default and not need a value, for example https://www.snik.eu/graph?empty&benchmark. Default parameter values are specified in js/config.dist.ts. Values for keys starting with ontology are specified in the ontology config included in the config, by default js/config/config.snik.ts.

|Flag|Description| |--------|-------------| |empty|Skip initial graph loading and show button to load a local Cytoscape.js JSON file.| |benchmark|Add an overlay with performance statistics such as FPS and number of classes.| |instances|Load and show instances when loading from SPARQL endpoint, not only classes.| |virtual|Create "virtual triples" to visualize connections like domain-range.|

|Parameter|Type|Config Key|Default|Description| |-------------|--------|--------------|-----------|---------------| |class|URI|||Center and highlight the given class, e.g. https://www.snik.eu/graph?clazz=http://www.snik.eu/ontology/bb/Management. Skips the default view.| |json|URL|||Skip initial graph loading and instead load a Cytoscape.js JSON object from the given URL.| |sparql|URL|ontology.sparql.endpoint|https://www.snik.eu/sparql|SPARQL endpoint to load the graph from| |graph|URI|ontology.sparql.graph|https://www.snik.eu/ontology|SPARQL RDF graph or RDF graph group| |sub|comma-separated list|helperGraphs + defaultSubOntologies|meta,bb,bb2,ob,ciox,he,it4it,limes-exact,match|List of subgraphs to load, only applies to SNIK.|

Config Files

Using the configuration files, you can change the behaviour of SNIK Graph in major ways. To adapt the configuration to your own ontology, check out the HITO config as an example as well.

The instance specific configuration is defined in js/config/config.ts. It exports a config object with key-value pairs. The top-level keys are: |Key|Description|Example| |-------|---------------|-----------| | nodeSize| Height and width of a node in pixels | 39 | | activeOptions | Initially active style options, choose a subset of: ["showproperty","day", "edgecolor"]; partially described in the manual. | ["edgecolor"] | | searchCloseMatch | When searching for a resource, also show resources connected to it by skos:closeMatch. | true | | logLevelConsole | Only used for mobile, desktop will always use cxttapstart | "debug" as LogLevelDesc | | logLevelDisplay | Only used for mobile, desktop will always use cxttapstart | "info" as LogLevelDesc | | logLevelMemory | Only used for mobile, desktop will always use cxttapstart | "debug" as LogLevelDesc | | layoutCacheMinRecall | Preset layout minimum recall required to have it applied. | 0.95 | | layoutCacheMinPrecision | Preset layout minimum precision required to have it applied. | 0.5 | | language | Default language of the interface, choose either "de" or "en". | "en" | | download | Configuration regarding resolution of image downloads. || | ontology | Configuration regarding the ontology used in SNIK Graph. || | multiview | Configuration regarding tabs. || | git | Configuration regarding the GitHub repository connection. ||

download

Changes the resolution of downloaded images. Specify an image object with the following properties: |Key|Description|Example| |-------|---------------|-----------| | image.max.width | Max width of downloaded (high-res) images. | 5000 | | image.max.height | Max height of downloaded (high-res) images. | 4000 | | image.standard.width | Standard width of downloaded images. | 1920 | | image.standard.height | Standard height of downloaded images. | 1080 |

ontology

[!TIP] This is probably what you want to change when using your own ontology.

This configuration is rather complex and one of the reasons why we still use a TypeScript file and not a yaml file of some sorts for configuration. In the current default configuration, we import either a snik config or a hito config for the SNIK and HITO ontologies, respectively. Consult these two files for more examples on this part of the config.

When writing your own ontology config, you can either do that in the config.ts itself (not recommended), or also write a separate file (recommended).

The subkeys are: |Key|Description|Example| |-------|---------------|-----------| | id | ID to identify which ontology is loaded. This is used to toggle some menus only displaying for SNIK. | "snik" | | name | Displayed name of the ontology. | "SNIK" | | legend | Raw HTML for legend in the bottom left. | "<span>&#9632; Entity Type</span>" | | title | Title of the browser tab. Defaults to "Ontology Graph" if not specified. | "SNIK Ontology Graph" | | initialView | Object (probably JSON) which is loaded as the initial view. Consult snik and hito as examples. || | snik | SNIK-specific configuration. Only used for SNIK. Probably null if not the default. See below. | null | | links | Links to homepage etc. in the services and help menus. See below. || | style | How to apply shapes and colors to the resources. See below. || | sparql | SPARQL-Queries to get triples (edges) and classes (nodes). See below. || | filter | Array of pairs of cytoscape selectors and i18n keys which show up additionally to some default values in the filter tab. | [ [node[source='bb'], "bb"] ] |

SNIK-specific configuration

|Key|Description|Example| |-------|---------------|-----------| | defaultSubOntologies | Array of subontologies to load and show by default. See more below. | ["meta", "bb", "ob", "he"] | | helperGraphs | Functionally the exact same as defaultSubOntologies, but semantically different. | ["limes-exact", "match"] | | center | If initialView is not specified, snik.centerDepth number of star operations are made on this node. | "http://www.snik.eu/ontology/bb/ChiefInformationOfficer" | | centerDepth | How many star operations to make on snik.center if no initialView is specified. | 1 |

Help links

If you do not want to display ome or more of these, set them to a falsy value (like null).

|Key|Description|Example| |-------|---------------|-----------| | homepage | Link to the homepage of your project. | "https://www.snik.eu/" | | metamodel | Link to a metamodel of your ontology. | "https://www.snik.eu/public/SNIK_Metamodell_V10.svg" | | feedbackOntology | Link to a place where one can submit feedback about your dataset. | "https://github.com/snikproject/ontology/issues" | | featureRequest | Link to a place where one can submit a feature request for the graph. | [too long] | | youtube | Link to a YouTube channel. | "https://www.youtube.com/channel/UCV8wbTpOdHurbaHqP0sAOng/featured" | | sparqlEndpoint | User-facing SPARQL endpoint. | "https://www.snik.eu/sparql" | | rdfBrowser | RDF browser (e.g. RickView) instance for your ontology. | "https://www.snik.eu/ontology |

Style your own ontology

Nodes can be individually styled by shape and color. This is done via methods which take a cytoscape node and return either a shape name or a color code.

|Key|Description| |-------|---------------| | shape | Determines the shape of a node. Function that takes a NodeSingular and returns one of "rectangle", "ellipse", "triangle" or "hexagon". | | color | Determines the color of a node. Function that accepts a NodeSingular or a string with only the name of the node (without prefix URI) and returns any color code. | | colorMap | Needs to be used by color function. If a node id is contained here, the node has this color. Used in code to auto assign colors to nodes not covered by the color function. |

SPARQL-Config for custom ontology

|Key|Description|Example| |-------|---------------|-----------| | endpoint | SPARQL endpoint to use. Sends queries to this server. | "https://www.snik.eu/sparql" | | graph | Base URI / SPARQL graph to use. | ""http://www.snik.eu/ontology" | | instances | Whether to display instances of classes. May not work. | false | | queries | SPARQL-queries to query for classes and triples. See below. | { nodes: ..., triples: ... } |

There are two different queries run when filling the graph: 1. A query to get the classes to display as nodes in the graph from the ontology (the nodes query), and 2. a query to get the triples to show as edges between the nodes from the ontology (the triples query).

If you want to take a look how the queries are used in the code, consider loadGraphFromSparql.ts.

nodes query

This method takes a from parameter which functions as a SPARQL FROM clause (specifying the RDF dataset) and returns a plain string which is executed as a SPARQL query.

The nodes query is a query which selects the following: - ?c for all (distinct) classes that should be loaded (only loaded classes are contained in triples!) - ?l for labels for the class in all languages as a single string (GROUP_CONCAT(DISTINCT(CONCAT(?l,"@",lang(?l)));separator="|") AS ?l) - ?src is the class that ov:defines the class; it does not need to come from the same SPARQL graph and is not distinct - ?inst instances, if you want instances; else use SAMPLE(?inst) AS ?inst - ?st in SNIK is the subtop of the node, specifies whether this is a role, a function or an entity type; if you don't use SNIK, this still needs to be selected, consider using SAMPLE(?st) AS ?st to ignore it

triples query

This method takes: - a from parameter which functions as a SPARQL FROM clause (specifying the RDF dataset) - a fromNamed parameter which functions as a SPARQL FROM NAMED clause (specifying the RDF dataset) - a virtualTriples, boolean whether you want to include virtual triples - you can ignore this if you don't want it - a instances, boolean whether relations between instances should be queried for It returns a plain string which is executed as a SPARQL query.

The triples query is a query which selects the following: - ?g as the SPARQL GRAPH of the triple - ?c, ?p and ?d as subject, predicate and object of the triple - ?ax for axioms, you probably want to shove this into an optional section and ignore it (also select MIN(?ax) as ?ax)

multiview

|Key|Description|Example| |-------|---------------|-----------| | initialTabs | How many tabs are open at the start. | 1 | | warnOnSessionLoad | When loading a new session, warn that this will override the old one. | true |

git

We rely on GitHub for automatically assigning accounts and labels to issues (which can be reported through the app). Here are the keys we use, most of which you should probably change when running your own instance.

[!CAUTION] Please do not leave them at their default values when forking.

|Key|Description|Example| |-------|---------------|-----------| | defaultIssueAssignee | When reporting an issue through the application, this person is automatically assigned. | "KonradHoeffner" | | issueLabels | We auto-assign some labels in the application and reference them by config keys. If you have different labels in your repository, change these values. | { bug: "bug", confirmLink: "link", deleteTriple: "deletetriple", deleteClass: "deleteclass" } | | repo | Assign the ontology repository and application repository to create the issues in. Please consult the following table for where each repo is used. | { ontology: "https://github.com/snikproject/ontology", application: "https://github.com/snikproject/graph" } |

A more in-depth description of the issue labels, and where each type is created: |Key|Repository|Description|Example| |-------|--------------|---------------|-----------| | bug | application | When a bug is reported through the UI, this label is assigned to the issue. | "bug" | | confirmLink | ontology | When a limes link is being confirmed (right-click an edge; applies only to the very few, if any, remaining unconfirmed edges), this label is assigned to the issue created for the confirmation. | "link" | | deleteTriple | ontology | When a user says a triple should be deleted (right-click any edge), this label is assigned to the issue requesting deletion. | "deletetriple" | | deleteClass | ontology | When a user says a class should be deleted (right-click any node), this label is assigned to the issue requesting deletion. | "deleteclass" |

Development

Scripts

• npm run dev dev server
• npm run build build into dist
• npm run preview serve the dist folder
• npm run test run unit tests
• npm run doc generate API documentation
• npm run prepare automatically run on npm install, prepare Husky Prettier commit hook

Update

1. git pull
2. npm update
3. if there are new keys in the config file, you may need to copy js/config/config.dist.ts to js/config/config.ts again

Make sure it runs locally before updating on the server, see releasechecklist.md.

Code Style

Specified in the configuration files of oxlint and Prettier.

Formatting

Prettier guarantees consistent formatting without time-intensive manual efforts. On npm install, Husky sets up a Git hook for you to automatically apply Prettier on every commit. Staged files are identified by lint-staged. If the automatic formatting Hook fails, for example currently on Windows, please always manually run npx prettier js -w --cache before commiting. If you use an IDE you may automate this by applying Prettier on save.

Linting

There should be no errors and as few warnings as possible. Can be integrated into IDEs and editors like Atom.

• npm run lint
• Some errors can be fixed automatically via npm run fix.

Typechecking

SNIK Graph is written in TypeScript but Vite does not perform any type checking, which you can run manually with npm run typecheck. This can help uncover some otherwise hard to find bugs.

LogLevels

• trace: very verbose information for debugging
• debug: information for debugging
• info: generally useful information, not only for developers (default)
• warn: for problems that are recoverable
• error: for errors that shut down the application

Internationalization (i18n)

We support English (full), German (mostly) and Persian (partly). Feel free to contribute a PR with a new language by copying and adapting js/lang/en.ts, importing it in js/lang/language.ts and adding it to the strings constant there.

Adaptation

If you like SNIK Graph and want to use it with different data, please open an issue. If the website and the SPARQL endpoint are on different domains, you may need to enable CORS in the SPARQL endpoint.

Citation information, meta data and archiving

If you want to cite SNIK Graph, please refer to our publication in the Journal of Open Source Education (JOSE). Citation info and meta data is documented in CITATION.cff, which is also used by Zenodo to populate the metadata of the Zenodo record for each SNIK Graph release.

FAQ

How can I use this for my own ontology?

When using your own ontology, you need to change the configuration in ontology and git, see above. Some things are not configurable yet, but this is actively being worked on.

How can I add another SNIK subontology?

For this, both the ontology and graph source have to be modified.

First, the things you need to change in the graph.

Some things are changed in the config: you need to add your new subontology by its id in ontology.snik.defaultSubOntologies. For colors, you need to add it to the ontology.colorMap. The SNIK ontology config is in config.snik.ts, this probably has to be changed there.

You also need to add a filter so you can filter out the new subontology in the filter menu. For this, add your filter function to filterData in filter.ts. These are cytoscape selectors and I18N labels for the button; all entities selected by the node selector are filtered by this. You then also need to add a label for the new button in the file for the default language.

[!NOTE] The ontology part is TODO. For now, you hopefully do not have to do this.

The devs told me a bug was fixed but it still occurs

Browsers may hold an old version of SNIK Graph in the cache. Go to "Help" -> "About SNIK Graph" to see if you have the newest version and if not delete your browser cache. If it still occurs, please update the issue if one already exists, if not please file an new issue using "Help" -> "Submit Feedback about the Visualization".

License

SNIK Graph has a license with copyleft, the GPLv3 for details. We want to encourage reuse, modification, derivation and distribution as much as possible, so if that license is a problem for you please contact Prof. Winter and we try our best to find a solution.