User Manual

Users

When a subscription is first created there will be no additional users. To add a user click Invite User. This should present a form as follows.

Enter the username of the user that you wish to invite and click Invite. The screen should update to look similar to the following image.

You can now invite further users if required.

If you come back to this screen at a later point you will then see a screen similar to the following image.

You can now select a user and start to edit the groups that they belong to. Groups are used by projects to select subsets of users for a project. Each project can control its own list of groups.

If a user has still not answered the invitation it will say 'Pending' against their name. If they have answered it will say either 'Accepted' or 'Rejected'. You can withdraw an invitation at any time by clicking the icon on the right of the screen. Note that this will not take effect until the next time a user logs in.

Groups

By default three groups are made available for each subscription - Administrators, Editors and Viewers. You will see a screen similar to the following image.

The default groups have preset entitlements. Administrators can do everything and this group cannot be changed. A subscription owner is always an administrator. The Editors and Viewers groups can be deleted if desired.

You can create as many additional groups as you require. A group will generally perform a 'role' within the system and be given a set of entitlements to perform that role. To add a group click Add Group. You will see a form similar to the following image.

Enter a name for the group and click Add. If you want to create a bunch of groups in one go click Multiple , which will add the group but keep the form open to allow another to be added.

Setting up an integration

Integrations are set up via the dashboard. Click on the Integrations card as shown in the following image:

You will need the appropriate entitlement to access this part of the application, which is Manage integration.

Click on the Add Integration button as shown in the following image:

This will display a dialog similar to the following image.

Enter a name for the integration, the target endpoint and the format to send to the target when synchronisation is done. If you do not know the full endpoint at this point you can always edit it later on.

When sending data there are two options - send entire taxonomies, collections and ontologies, or, send just the changes (delta) since the previous send. Which is the best option will depend upon how you want to process the data. For very large taxonomies and ontologies it may be more efficient to just send the delta. If you want to use the delta option select the 'Changes Only' option. Note that there is a 100MB limit for integration payloads.

Click Add.

You should see a screen similar to the following image. The Public Key field contains the key that you can use in the target system to validate requests.

When data is synchronised a list of when the synchronisation was run will be available for each integration.

Integration with EasyGraph

It takes just a few simple steps to be able to push data from Graphologi to EasyGraph once you have a dataset configured in EasyGraph.

Create an integration as above using a holding URL such as the following EasyGraph sandbox URL, filling in the relevant values for InstanceID and Dataset from your EasyGraph set up and using '12345' for what will be the UUID value for egSignatureKeyUUID

/{InstanceID}/{Dataset}/administration/data/import?profile=graphologi&egSignatureKeyUUID=12345

Copy the public key generated by Graphologi and then in EasyGraph create a new key pair for the required user. Do this by clicking on the icon to upload a public key, as in the following image.

Give the key pair a sensible description and paste the key into the 'Public Key' field.

You then need to copy the UUID part of the 'Key ID' in EasyGraph as highlighted in red in the following example image:

Back in Graphologi in the endpoint field replace the holding value 12345 with the key UUID.

That's it. You should be ready to send data from Graphologi to EasyGraph.

Synchronisation

Once your integrations are set up you are ready to try them out (if you have permissions). Synchronisation is done via the project page. Click on the icon to get started. You then need to select which integration you wish to use from the list on the left. Once you have selected an integration the display will change to show you which components of the project have changed since the last time this integration was run for this project, in a similar way to the following image.

Important! Note that imports will not be indicated as changes. This is also the case for integrations set for deltas. If you are doing imports and need to synchronise those, but, under normal circumstances, want to send just deltas, you can set up another integration to push the entire payload and use that after an import to ensure the imported data is sent. Of course, this may require additional logic at the target endpoint. Another option is just to load the imported taxonomy directly into the target system.

By default all components are selected for synchronisation. Deselect any that you do not want to send. You can deselect all components by clicking the Deselect All button. Note that any deleted resources will automatically be sent.

Note that, if you do not send all components that have changed, there is a danger that the target system will not be fully coordinated (for example, if a concept is edited and used in multiple taxonomies). This is, of course, dependent upon the behaviour the target system implements.

Also, if concepts are removed from a concept scheme, or resources from a dataset, they will not be listed in any payload as the payloads only consider things that are part of a concept scheme or dataset.

Expected payload

The payload that Graphologi sends will include the resources from the components that you choose to send and minimal information for deleted resources. Note that, in some circumstances, you may get notified of a deletion more than once.

An example is given below for a trivial taxonomy, where there is a deletion included. You can see that for a deletion there will be the id of the deleted resources as well as a deletionTime property, which is a milliseconds since epoch timestamp.

{
    "graph": [
    {
        "id": "https://ex.com/integration/First",
        "created": "2023-02-17T13:21:56.561Z",
        "prefLabel": {"en": "First"},
        "topConceptOf": ["https://ex.com/integration"],
        "inScheme": ["https://ex.com/integration"],
        "revisionNo": 1,
        "modified": "2023-02-17T13:21:56.908Z",
        "type": "Concept"
    },
    {
        "id": "https://ex.com/integration",
        "useXL": false,
        "created": "2023-02-17T13:21:50.943Z",
        "title": {"en": "Integration"},
        "modified": "2023-02-17T13:22:16.925Z",
        "hasTopConcept": ["https://ex.com/integration/First"],
        "type": "ConceptScheme",
        "useSlashIRI": true,
        "revisionNo": 5,
        "useUuidIRI": false
    },
    {
        "id": "https://ex.com/integration/Second",
        "deletionTime": 1676640220961
    }]
}
            

Validating a request

You should almost certainly validate that the requests are coming from Graphologi. Use the public key associated with an integration to do this. Below is a Javascript example for how to validate a payload using Crypto. You should set a window of a few seconds for the timestamp. Beyond this window you should reject the request. This should NOT be used in production and simply serves as an example.

async function validatePayload(headers, payload, publicKey) {
    // Expecting an authorization header with parameters:
    // Algorithm="RSA-SHA256";Timestamp="{epoch string}";Signature="{string}"
    const payloadString = headers["Content-Type"] === "application/ld+json" ?
        JSON.stringify(payload)
        :
        payload;
    const payloadHash = crypto.createHash('sha256').update(payloadString).digest('hex');
    const params = headers.Authorization.split(";").map(param => {
        const value = param.substring(param.indexOf("=") + 1);
        return value.substring(1, value.length - 1);
    });
    const timestamp = params[1];
    const signature = params[2];                
    // Use timestamp and signature to verify payload string
    const payloadForVerification = timestamp + "\n" + payloadHash;
    const verify = crypto.createVerify('RSA-SHA256');
    verify.write(payloadForVerification);    
    verify.end();
    const result = verify.verify(publicKey, signature, 'base64');
    return result;
}

Setting up a snapshot

Snapshots are set up via the dashboard. Click on the Snapshots card as shown in the following image:

You will need the appropriate entitlement to access this part of the application, which is Manage snapshots.

Click on the Add Project button as shown in the following image:

This will display a dialog similar to the following image.

Select the project you wish to set up. You can start to type the name of the project to filter the list. As projects can have different default languages you can change the language you are searching in.

You should see a screen similar to the following image.

Taking a snapshot

You can set the automatic snapshot period and the maximum number of snapshots to retain. Note that the snapshot period is approximate. Also, when the system starts up (i.e. after an update for instance) a snapshot will be taken soon after regardless of the period.

You can manually trigger a snapshot by clicking on the icon. This may be a sensible thing to do if you are about to make major changes to a project, such as importing.

When you click on the snapshot icon a dialog will appear as in the following image:

You can optionally enter a name and comment for the snapshot. If you wish the snapshot to also be created as a project version check 'Set as Version'.

To actually generate the snapshot click on the Execute button. It will take a small amount of time to process.

Snapshots will appear in the list in a similar way to the following image.

Restoring a snapshot

To restore a project into the existing project click on the icon on the right of the snapshot that you wish to use for the restore.

Once you confirm the action it will take a small amount of time to restore the data. The project will be locked whilst this happens.

Selecting a project

You will automatically be asked to select which project you want to use as the base project. As projects can have different default languages you can change the language you are searching in. You can select from taxonomy or ontology projects.

Once a project is selected Graphologi will load class and property information from that project for autocompletion in the query editor. For very large projects this may take a little time so you can skip this by clicking the Skip button.

Once this is complete you should see a screen similar to the following image.

Running and saving queries

Note that saved queries are only available in Premium subscriptions and above.

To manage saved queries you need the Manage saved query entitlement. To just view saved queries and run them you need the entitlement View saved query.

You can use SELECT, ASK and DESCRIBE queries. Enter your query and then click the Run Query button. The results will be displayed in the bottom section of the screen. It is also possible to preview how query results will look in a report by selecting the icon.

You can save a query by clicking the Save Query button. This will display a dialog similar to the following image:

Enter a title for the query and, if required, a description. You can also select whether the query should be made available for reporting. See the section Reports for more details on reports.

To retrieve a particular saved query select it from the drop-down list on the right of the screen. This will display the detail in a similar way to the following image:

The details of the query can be edited if desired, including updating the query itself by clicking on the Update button.

If you change the query in the editor but want to set it back to the value in the saved query click the Reset button.

The value in the 'IRI' field is that needed to run saved queries in the API.

Querying multiple projects

By default only the selected base project can be queried (including its history named graph). However, you may want to be able to query across additional projects. You can add additional projects using the Add Additional Project button. A maximum of four additional projects can be added.

Once you add an additional project you will see a screen similar to the following image.

You can use the icon to copy the graph IRI to the clipboard.

Note that once additional projects are added any SPARQL query will need to use GRAPH clauses.

You can update any saved query to include added projects.

Note that, for any query used as a report that includes additional projects, a user will only be able to run the report if they have permissions for all the projects listed.

Prefix management

When you export data out of Graphologi certain serialisations use prefixes to shorten IRIs. This can reduce file size and improve readability.

Graphologi will process any prefixes used when importing files and they will then be used on exports. You can also add additional prefixes. This facility can be accessed via the dashboard. Click on the API card as shown in the following image:

You will then see a screen displaying a set of information about various aspects of the subscription. Most of the detail relates to making API calls.

To access this part of the application you need the relevant permission, which is Manage integrations.

The 'Prefixes' panel will list existing prefixes and their associated IRIs. To add another prefix click on the icon. This will display a dialog box as shown below.

Enter a prefix and an IRI. The prefix can only contain the characters a-z, A-Z, digits and hyphens and can be at most twenty characters long. Click the Add button to add the prefix to the list.

Important note: It is not possible to remove a prefix once added so please be careful to ensure that any prefix and IRI you enter are correct before adding.

Selecting the default project language

The application will be configured with a set of available languages. The first step in creating a project is to select the default language. The selected value will control certain aspects of the Vocabulary Manager in terms of expectations for things such as labels for concepts.

Entering project detail

The next step is to enter a project title and, if required, a project description. The language for these will be the default language selected in the previous step.

Selecting additional languages

A project can have as many additional languages as required. These can be chosen from the overall set of languages the application is configured for. Additional languages will be used for things such as preferred labels or notes, where the Vocabulary Manager will allow you to enter data in any of the selected additional languages.

Enabling SKOS-XL

Vocabulary Manager works with SKOS-XL out of the box. SKOS-XL extends the standard SKOS vocabulary to provide the ability to define labels as first class resources, which then allows more information to be stated for each label. All versions include this functionality. To enable it simply toggle the SKOS-XL option as in the image below:

Selecting user groups

The final step is to select the user groups for a project. By default these will be the groups that you are in. Select as many as you need for the project. Note that user groups may span more than one project and this is something to keep in mind if you wish to use ontology features within your taxonomy project.

When the final step is done you should see your new project presented in a similar manner to that in the image below:

Project information

This allows you to edit the basic project details. It will look similar to the following image.

You can do the following on this screen:

• Edit the project title and description and add more language translations for both if required.
• Add more languages to the project. Note that the default language for a project is fixed at the time the project is created and cannot be altered.
• For taxonomy projects you can enable SKOS-XL. Once enabled this cannot be disabled.
• For ontology projects you can exclude from import association. This can be important if you have multiple copies of ontologies in different projects. When this happens importing taxonomy projects referencing those ontology projects can cause ambiguity and Graphologi is not able to determine which project to associate. By excluding projects you can remove any ambiguity.
• Add custom datatypes for use with SKOS notation values.
• Change the project colour. By default a random colour will have been selected from the palette.

Permissions

Permissions allows you to change the user groups that have access to a project.

Note that the administrator group is always associated with a project.

RDF import

If you are importing an RDF format you will then see import options as in the following image.

If importing an ontology you will also get an option to ignore minor errors. This can help with many ontologies as unfortunately it is not uncommon for errors to exist.

The options control whether the imported taxonomy/ontology will use slash or hash IRIs and whether IRIs generated by the system use UUIDs or labels.

Spreadsheet (XLSX), TSV or CSV import

This is available for taxonomy projects and data projects. If you are importing a spreadsheet (an XLSX file), a TSV, or a CSV file, you will see a screen similar to the following image.

You need to select the base language of the text within the file. In general it would be expected that this is the same as the default project language. It is used as the basis for computing the hierarchy of the data. If your data does not have labels in the default project language that will still work, but when displayed in Graphologi the concepts will indicate that no label is available for the default.

You can optionally enter a title for the taxonomy or dataset.

You must also enter a base IRI for the taxonomy or dataset (e.g. 'https://example.com/vehicle'). This will form the first part of the IRIs that Graphologi will generate for your taxonomy or dataset.

In the same manner as creating a new taxonomy or dataset, you can choose whether to use slash or hash IRIs and whether UUIDs or labels will be used for IRIs.

Further to that, you can set advanced IRI options for the taxonomy by clicking on the icon. These options are the same as when creating a taxonomy. The additional SKOS-XL label options are activated for taxonomy projects if you choose to import labels as SKOS-XL labels.

The next step is to map the data in your file. If you have a header row in your file select 'Ignore Header Row'. If it is a taxonomy project and your project is SKOS-XL enabled you will also have the choice to generate labels as SKOS-XL. This will apply to any preferred, alternative or hidden labels.

By default the first five rows or your data are displayed for preview. You can increase this by changing the value on the right of the screen.

Note that the limits for import are 100 columns with the number of rows depending upon the subscription type. Also, you cannot import files that have non-text content.

The next step is to map the columns in the file to properties in Graphologi. You only need to map the columns that you want to import. For taxonomy projects there must be at least one column that is a preferred label in the language as selected above. For data projects there must be a column that is the label.

For taxonomy hierarchy the columns would generally be next to each other in the file, as in the following example.

Select all the columns that make up the hierarchy (assuming you want to import all the levels). So, for the example above, select both columns as Preferred Label and set the language as English. This is shown in the following image.

Continue to map other columns for other properties.

The following are points to keep in mind:

• For taxonomies, if the same preferred label is found in more than one row it will be assumed to be the same concept. For datasets this is not the case and multiple resources will be created.
• You can have multiple columns for the same property in the same language. For example, if you have two columns of alternative labels in English this will work fine.
• You can have multiple values over multiple rows. This is the approach that Graphologi TSV export takes. So, for example, if a single preferred label has three alternative labels over three rows that will also work.
• You can have newline characters in the SKOS note properties such as Definition or Scope Note, but not in the label columns.
• The limit for label columns is 500 characters for each label. For the other properties it is 5000.
• It is valid to not map all the columns.
• Notations are currently only supported as strings (with no datatype).

Completing the import

Once you have chosen the options click Upload. The import will start. The process may take some time and the screen should update as various steps are completed. These include uploading the file, validating it and then normalising the data, which is a step to ensure consistency within the data.

On successful completion you should see a Finish button, which, on clicking, will display the project home page.

If errors occur on import you will need to fix the data before attempting to import again.

Import notes

For SKOS notation, where the notation is a language string, the value will be converted to a non-language form. Graphologi does not support language tagged notations as it is highly unusual to do this.

XML literals will also be converted into strings.

Creating a version

To access or create versions click on the icon on the left. This will display a screen similar to the following image.

To create a version click on the Create Version button. You will need the appropriate entitlement to create versions, which is Manage snapshots.

This will display a dialog similar to the following image.

You can optionally enter a name and comment for your version.

To generate the version click on the Execute button. It will take a small amount of time to process.

Versions will appear in the list in a similar way to the following image.

You can view the history for a version by clicking on the icon. For versions that are not the first version it is possible to select the option to show 'Only Changes in This Version', which will restrict the history to only show changes since the previous version.

You can download a version (as a project) by clicking on the icon.

A version can be deleted by clicking on the icon. Whilst there is no project level limit for the number of versions, a subscription will have an overall limit across all projects.

Notes about versions

Versions are NOT read only. Versions are simply special projects connected to the original project. All groups for a version will still be there as at the time of creating the version. Version projects only show in the versions screen within the Graphologi application.

Graph references within the version history will be to the original project graph. This ensures that the information stays the same for each version.

The IRI of the actual project resource in the version will change for each version to match the graph in which the version exists. All other information about the project resource remains the same.

Hierarchy

Hierarchy shows the concepts in the taxonomy in a tree view. Note that multiple levels of hierarchy is optional and your taxonomy may be a flat list of concepts. For a complex taxonomy the tree may get very deep. As an example, the following image shows concepts from Agrovoc - a very large and deeply hierarchical taxonomy.

The number of narrower (child) concepts is shown in parentheses. For example, in the image above 'programmes' has six narrower concepts.

As taxonomies get deep in terms of levels it can be difficult to remember the context of the broader concepts. To aid with understanding the context a summary of the hierarchy is displayed when you hover over any concept that is below a top concept.

It may also be useful to adjust the display panels and there are various options to do this, which are accessed at the top of the hierarchy.

If you have expanded the hierarchy in multiple places and want to collapse it, you can do this by clicking on the icon.

For deep taxonomies you may want to use more screen space to display the hierarchy. The width can be altered by clicking on the icon. You can adjust the width up to three levels, after which the next click will return it to normal width.

Sometimes it is easier to work with just the hierarchy in view to simplify the display. To do this click on the icon. To return to the normal view click the icon again.

Concepts

Concepts shows a filtered set of the concepts in the taxonomy. This view can be very useful if you just want to look at particular concepts that have labels that match a string of text, or simply want to quickly look at some concepts.

As concepts can be removed from the hierarchy of a taxonomy this potentially leaves them disconnected from that hierarchy. That is, the concepts are still in a concept scheme but not 'positioned' as such. You can still find and view these concepts. However, if you want to explicitly see which concepts are not positioned you can select the 'Unused Concepts Only' option.

Labels

Labels is the list of SKOS-XL labels available within your taxonomy. The number of labels can get extremely large. For instance, the Agrovoc project has over seven hundred thousand labels across dozens of languages. Below is an example image of Agrovoc labels. Labels are language specific and the language filter allows you to select which language you want to choose from.

Controlling the language you are viewing

For projects using multiple languages it can be useful to switch the viewing language. This can be done using the language selector at the top right of the screen.

This controls various aspects of the editor. The hierarchy will reflect the language, as will the search and for certain dialog boxes the language will default to the viewing language.

If text in the viewing language is not available the view will try and use the default project language. Where the viewing language is not available the screen will highlight items in orange to indicate this information is not available.

Changing the IRI of a concept or label

IRIs should be persistent if at all possible. Changing IRIs can cause problems because they are unique identifiers for resources and changing a unique identifier can break any connection to it. You should do whatever you can to avoid needing to change IRIs.

However, it may be that you do need to change an IRI, possibly because a legacy IRI has been imported, or that the IRI generated by Graphologi isn't exactly as you would like.

You can change the IRI of both concepts and SKOS-XL labels. The approach is the same for either. Click the on the right hand side of the screen. This will display a dialog box as in the following image.

Update the IRI in the 'New IRI' field to that value that you want. This must not clash with any existing IRI that the system has and a check will be run.

Most IRIs will probably use the base IRI of the taxonomy. To copy this value click the and then add the additional part of the IRI for the concept or label.

There are two approaches to applying changes to IRIs within Graphologi. The original method simply recorded a change and in many parts of the application automatically displayed or exported the change even though the underlying IRI for the resource did not physically change (meaning that SPARQL queries and some API calls did not 'see' the new IRIs easily). This option is still available. However, the default is now to apply the change permanently. The 'Make All Changes Permanent' option is selected by default. If you leave this checked then the system will physically update this IRI and any other IRIs not permanently changed. This operation is a batch operation and so the project will be locked whilst this happens.

When applying IRIs permanently there are several points to keep in mind:

• Any history for resources with updated IRIs will be wiped. Essentially the new IRIs are treated as new resources from a history perspective.
• There are potential impacts for linked taxonomy projects. Please see the section below for more information.

You can view any old IRIs in the 'IRI History' panel of the concept.

Linked taxonomy projects

By default it is only possible to make links within a single project. However, it may be desirable to allow connections to other projects.

For details on how to link projects please see: Viewing and managing information about a taxonomy.

When there are linked projects it then becomes possible to use them for the SKOS match properties and ontology relationships. An additional tab will be available on certain dialogs with the title 'Linked projects', similar to the image below.

There are certain important constraints to keep in mind when using linked projects:

• A user must have access to the linked projects to be able to make connections to it. If they do not and there are connections to it they will simply see IRIs in the display and these will be treated as external links for that user.
• If a linked project contains any SKOS-XL based concepts these will only be found if the project you are linking from is SKOS-XL enabled.
• If a resource in a linked project is deleted that will not remove the connection in the source project. It is a manual task to remove these connections. Note that we recommend deprecating resources rather than deleting them because this ensures the persistence of IRIs, which can be helpful in situations such as this.
• If a linked resource has its IRI edited in a non-permanent fashion the application will display the edited IRI. However, if IRI changes are made permanent, which is the default setting for Graphologi, then connections to those resources will not be updated. It is a manual task to do this. You can use the SPARQL console to find out any connections that may be impacted by an IRI change.
• If a linked project is subsequently removed any connections to it will remain and be treated as external links.

Linked data

There are many useful linked data sources available on the web. One of the most popular is DBpedia, which contains a wealth of information. It is possible to make connections to DBpedia (English version) within Graphologi by selecting the DBpedia option for a taxonomy. For details on how to do this see: Viewing and managing information about a taxonomy.

When this option is selected it then becomes possible to use DBpedia for the SKOS match properties and ontology relationships. An additional tab will be available on certain dialogs with the title 'DBpedia', similar to the image below.

Please note that DBpedia search is not range aware.

Once you have made connections to DBpedia resources you can see more information about them by clicking on the chip. This will display a dialog similar to the following image:

Taxonomy detail

You can edit the title and description of the taxonomy. You can add additional titles and descriptions in any of the project languages. The title in the default language cannot be removed.

Note the IRI of the taxonomy, the slash/hash pattern option and the IRI format option are fixed once a taxonomy is created and cannot be edited.

Depending upon the project setup you may see additional options as in the following image:

If workflow is available for your subscription you will see an option to activate for the taxonomy.

If SKOS-XL is enabled there will be an option to use XL labels as the default for new concepts.

If there are associated ontology projects you can set the default classes for new concepts (including those created via suggestions) by clicking on the icon in the 'Classes for New Concepts' panel. Start typing the name of the class you want to add. A list of matching classes will be displayed. You can only select from classes that are associated. For more information on associating ontologies with taxonomies please see the section Configuring ontologies for use with projects.

If there are associated ontology projects you can override the default sorting for the hierarchy. To do this click on the icon in the 'Use Custom Property for Sorting' panel. Select the property you wish to use. You can select to 'Treat as Numeric' if applicable for the property by toggling that option. For example, without the numeric option '34' would come before '4', whilst the opposite is true if numeric is selected. Most property types will be usable but it is up to you to select an appropriate property for ordering given the possible values.

By default all the SKOS properties are displayed for a concept. This can sometimes cause unnecessary screen clutter if the properties are not used for a taxonomy. If you want to hide certain properties from the view you can do this in the 'Hide Properties from View' panel by selecting those that you do not want to be visible. Note that this option is also available for collections.

By default it is only possible to make relationships within a project. However, in some circumstances it is useful to be able to make connections to other projects. You can add a linked project by clicking on the icon in the 'Linked Taxonomy Projects' panel.

You may want to create links to an external repository. Currently you can link to DBpedia, which is like a semantic version of Wikipedia. To allow links to DBpedia check that option.

Graphologi will set the default IRI options for a taxonomy when you create it. However, sometimes you may want more control over the creation of IRIs.

In the 'IRI Options' panel you can adjust the following for label based IRIs:

• Whether or not the IRI editing box should appear by default when creating concepts or SKOS-XL labels. By default if will be hidden and there will be a toggle that users can use.
• It is not always desirable to have spaces in IRIs. Graphologi will escape them by default, but if you want them removed check the 'Remove Spaces' option.
• Alternatively, rather than remove spaces it may be desirable to replace them. If you check the 'Replace Spaces' option then spaces will be replaced with hyphens. Note that removing spaces takes priority over replacing spaces.
• In a similar way it is not always desirable to have 'special' characters in IRIs. You have options to remove or replace these by checking the appropriate options.
• Certain characters need to be escaped in IRIs in order to not cause issues with reserved characters. By default Graphologi minimises encoding to only those essential characters. If you wish to encode a wider range of characters uncheck this option.

If SKOS-XL is enabled then further options are available:

• By default Graphologi will prepend SKOS-XL labels IRIs with 'label-'. You have the option to stop this happening or to change the prepended text. (Note that Graphologi will still insert a hyphen if text is used).
• Also, by default Graphologi will append SKOS-XL label IRIs with a hyphen and the language code of the label. You can stop this happening by unchecking the applicable option.

The default behaviours for SKOS-XL labels are there to try and avoid unnecessary IRI clashes. For instance, if the default SKOS-XL label behaviour was not in place then a concept and its label would potentially generate the same IRI. If you turn off the prepend or append options, clashes will be more likely.

You can tell Graphologi to handle IRI clashes for SKOS-XL labels automatically by checking the appropriate option. This will append a random sequence of characters to the generated IRI to ensure it is unique. Using this option still allows a user to edit the IRI if they want to.

Triples

Display all of the triples that exist for the resource. Note that for imported data there may be additional data that shows up here that is not editable in the application. If there is data which is not editable there will be a icon for each row, allowing you to remove those triples.

History

This allows you to view all changes made to the taxonomy (concept scheme). (Note that history for each concept can also be viewed separately in the detail view for a concept.)

Within this view you can control the scope of history to show only changes to the concept scheme resource itself, or for all changes to resources related to the concept scheme.

You can refine the details of what is shown by a date range and by a user. To filter by date simply select the start and end dates that you wish to see using the 'Date Range' filter. To view history only for a particular user select that user.

The history view contains a lot of detail, which can make it difficult to view easily on smaller screens. You can reduce the number of columns displayed by clicking on the icon and selecting those columns that you wish to view.

History can also be downloaded in either TSV or JSON format by clicking on the Download button and selecting the required format. The filters on date range and user also apply to any downloads.

Statistics

This displays concept and SKOS-XL label counts and individual language counts for preferred and alternative labels. A typical example output is shown below.

Quality

This runs a set of checks that cover various aspects that are generally accepted as SKOS mandated guidelines for taxonomies, plus some further checks. Note that, in general, Graphologi will not permit actions that cause quality violations. However, the quality checks are there as a fallback to reinforce that.

Where there are quality issues they will be presented similarly to the following image.

Export

There are two different methods available for exporting data - export as RDF, or generate a grid-like output in either CSV, TSV (tab-separated values), HTML or XLSX. By default you are shown the 'Download Data' option, which is for exporting RDF.

'Concept Scheme' is a full RDF download of the data for the concept scheme (taxonomy). If the project has SKOS-XL enabled you will be able to select whether to include XL labels. If the taxonomy has annotations activated you will be able to select whether to include them. Simply select the RDF format in which you require your data and click the Download button.

The 'Generate CSV/HTML/TSV/XLSX' option allows you to completely customise the output by selecting which columns you want and in which order. You can also, if required, add a header row. As export is something you may want to do more than once you can also save a configuration as a template to use again at a later date.

When you first go into this option you will see the template selection screen. Click on the blank template to begin.

You can now start to add columns for your export. Select the property you want in the column. The special value 'Hierarchy' will include the hierarchy of the taxonomy. Note that although this only displays as one column (to avoid the display getting too complicated) in the actual output multiple columns will be generated to reflect the actual levels in the taxonomy. If the property is language based you can select the language you want for that column. For example, you may want to add a preferred label column in English and another in French.

If you want to include a header row check the 'Include Header Row' option.

Once you have added a few columns your screen will look similar to the following.

Where possible the display will give you examples from the actual data to help show you what will be in the output.

If you need to change the order of the columns you can drag them around or, to switch any two columns, click on the icon.

When you are happy with your setup click the Generate button and select the required output option to create and download your file. Note for very large amounts of data this may take a little time.

To save your setup click on the Save as Template button. You can give your template a name. The template will then be displayed on the template selection screen.

To throw away any setup and go back to the template screen click on the Discard button.

Lifecycle

What appears on the Lifecycle tab will depend upon whether workflow is activated or not. The 'Deprecated' tab will always appear. If workflow is activated additional tabs will be displayed. See Viewing concepts, labels or resources with particular statuses for more details.

The 'Deprecated' tab displays a list of all deprecated concepts, which you can filter by label name and language. Note that links to concepts will show in orange. You can click on the concept to go to the detailed view for it.

Suggestions

This displays a summary of all the suggestions across the taxonomy as a whole. The source concept for each suggestion will be shown and you can click on this to go to the detailed view for that concept. There you can see the full details of the suggestions including any discussion.

Add a top level concept

To add a top level concept click on the icon on the left of the screen (or use the keyboard shortcut Alt+N). This will display the following dialog box:

Enter a preferred label. The language for the label will be the default project language. You can add additional labels in other languages, if configured, once the concept is created.

The preferred label must be unique within the concept scheme (taxonomy). You will see a prompt if it is not.

If SKOS-XL is enabled for the project you can select the option to create the label as a SKOS-XL label. Additionally, if your entered label matches an existing unused SKOS-XL label you will be prompted as to whether you wish to use that unused label rather than create a new label.

If you wish to edit the automatically generated IRI for a concept (and its SKOS-XL label if appropriate) you can do so by selecting the 'View/Edit IRI' option (it may already be selected if set at the taxonomy level). The edited IRI must be unique within the project. Graphologi will not allow you to proceed until a unique IRI is entered.

To add the concept click Add. If you are entering a large amount of concepts you can click Multiple (or use the keyboard shortcut Ctrl+Enter), which will add the concept and keep the dialog box open ready for you to add another concept.

If you have selected to create or use a SKOS-XL label for your concept this will appear in a different way to a standard label, as in the example image below:

You can click on the label to jump to its detailed view page.

If you wish to convert the SKOS-XL label to a normal SKOS label click on the icon. This will replace the SKOS-XL label with a label property, but does not delete the SKOS-XL label. If you wish to remove the label for the concept click on the icon, which again does not delete the label but merely removes it from the concept.

Reuse an existing concept

The approach is similar to above but, as you type, suggested concepts will appear similarly to the following image. If you have multiple taxonomies in your project you will have access to the concepts in the other taxonomies when adding a top concept. Further, you will also be able to make use of any free-floating concepts within the project.

If you wish to use an existing concept click on it. You may already see that some concepts have been detected as conflicting and these will be highlighted red.

Even though suggestions may appear you can ignore them and create a new concept. There is the choice to reuse an existing concept (by clicking on it) or create a new concept by clicking Add.

Concept schemes (inScheme)

Where a concept is reused from another taxonomy (concept scheme) it will be added to the current taxonomy. This will mean that the concept is in two concept schemes. You will see information similar to the below example for Egyptology, where the 'In Scheme' panel shows the two concept schemes.

It also means that a concept is potentially narrower to multiple concepts across multiple concept schemes. This is perfectly fine. However, it is possible that you include a concept from another scheme that itself has narrower concepts. These will not be added to the current concept scheme, but will be displayed with a grey background. For example, in the screenshot below 'Adult education institutions' has been added to the current concept scheme but its narrower concept has not been added to the scheme (i.e. no skos:inScheme property is created for it).

It is possible to add these free-floating concepts to the scheme. If you hover over the concept you will see an image similar to the following image.

Click on the icon to add it to the concept scheme.

It is also possible to add all concepts in the hierarchy to the concept scheme in a single operation. This can be done by clicking on the icon on the taxonomy home page, located towards the right-hand side of the screen.

Polyhierarchy vs monohierarchy

By default Graphologi is in polyhierarchy editing mode, allowing a concept to have multiple broader concepts. The mode can be changed to monohierarchy by clicking on the icon. The mode icons are on the left-hand side of the screen as in the following image.

When in polyhierarchy mode adding narrower or broader relations creates an additional relationship. Any existing relationships will remain. In monohierarchy mode adding a broader relationship will replace any existing broader relationships.

It is also possible to set the editing mode for the taxonomy as a whole. This is done in the taxonomy detail view, as shown in the example image below. In that view you will see a panel called 'Editing Mode'. By default it is set to Flexible, meaning that the user can adjust the mode as described above. If the mode is set to Polyhierarchy or Monohierarchy then the mode is set for the entire taxonomy and the buttons above will not be available.

If in Monohierarchy mode an additional quality check is also run.

Add a narrower concept

Adding a narrower concept can be done in one of three ways. The first is by hovering over the concept label in the hierarchy view. This will display icons for breaking the link to the parent concept and adding a new narrower concept as shown in the following image. Click on the icon. You will see the same dialog box as above.

Alternatively, you can drag existing concepts from the hierarchy on to relations on the right of the screen or within the hierarchy itself.

Finally, you can click on the icon in the 'Narrower' panel. This will allow you to search for concepts within the taxonomy. Click on the desired search result to add it.

In the same way as for top concepts, it is also possible to reuse existing concepts. The approach is the same.

Remove a top or narrower concept

To remove a concept, either at the top level or a lower level, click on the icon. You will be asked to confirm the action. A quick way to do this is to use Alt+click which bypasses the confirmation. Alternatively, for narrower concepts, you can click on the cross in a concept's label such as in the 'Narrower' panel.

Note that breaking the link does not delete the concept, even if not used anywhere else - it simply removes it as a narrower concept of the parent concept. The concept will still be available to use.

Deprecate a concept

It may be that over time certain concepts become obsolete. However, if these concepts have been used then their identifiers - IRIs - may need retaining. Deprecating a concept allows you to indicate that a concept should no longer be updated or used without removing it from a concept scheme.

To deprecate a concept click on the icon on the right of the screen.

Deprecated concepts can no longer be edited and new relationships to them can no longer be formed.

If you realise that a concept has been deprecated by mistake you can simply undeprecate it by clicking on the icon on the right of the screen.

Delete a concept

To delete a concept click on the icon on the right of the screen. Note that once a concept is deleted it cannot be reused.

Editing a concept's labels

To change a label click into the text and start editing. You will be shown any matching labels as you type in a similar way to the following image. If your label is acceptable (that is, does not clash with other labels), a icon will be shown on the right of the field. Click to confirm the change.

To abandon a change simply click away from the field.

Add preferred, alternative and hidden labels

To add additional labels click on the icon in the appropriate label panel.

This will display a dialog box where you can select the language you want for the label and a field to type the label text. For preferred labels only languages that do not already have a label will be available to choose from as SKOS only permits one label per language for preferred labels.

Options for creating or reusing existing SKOS-XL labels are available in the same way as for adding concepts.

Labels must be unique within a concept for preferred, alternative and hidden labels. If you enter text that clashes with an existing label of one of these types you will see a warning.

Alternative label promotion and conversion

Sometimes existing data might need to be reorganised. Graphologi provides you with some features that work specifically with alternative labels

The first feature is promotion of alternative labels to preferred labels. You can do this by simply dragging an alternative label into the 'Preferred Labels' panel. If a preferred label exists in the same language it will be demoted to an alternative label. Note that you cannot promote an alternative label where it will cause a clash with a preferred label on another concept.

The second feature is the ability to convert alternative labels into narrower concepts. This only applies to labels in the default project language as all concept creation within a taxonomy must have a preferred label in the default language in Graphologi. To do this simply drag the label into the 'Narrower' panel. As long as no other concept has a preferred label that matches the alternative label a concept will be created.

Finally, where multiple languages are used in a project, it is common to also have alternative labels in those languages. If, for instance, you have made a default language alternative label into a narrower concept you may want to put the translations on to that concept. Simply drag the label onto the concept and it will be added as an alternative label. In a later release the option as to whether it becomes a preferred or alternative label will be made available. For now, to promote them to preferred labels you will need to click through to the concept and promote them as mentioned above.

Add broader, narrower or related relationships

To add relationships click on the icon in the appropriate relationship panel.

This will display a dialog box where you can start to type the name of the concept label that you wish to add. Potential matching labels from within the same taxonomy (concept scheme) will be displayed in a similar fashion to the image below. Click on the label that you wish to add.

Add broader, narrower, close, exact or related match relationships

These relationships are used to connect together concepts from different taxonomies (concept schemes).

To add matches click on the icon in the appropriate relationship panel. This will display a dialog box where you can start to type the name of the concept label that you wish to add. Potentially matching labels will be displayed. Click on the label that you wish to add.

You can also type an IRI directly into the field, which allows you to make connections to resources outside of Graphologi.

Adding definitions, examples and notes

To add a definition, example or note, click on the icon in the appropriate panel.

This will display a dialog box where you can select the language and a field to enter the actual text. This will look similar to the image below.

Note that you can enter multiple lines for these properties. Simply hit the Enter key to add a new line.

View the underlying RDF triples

To view the underlying triples for a concept click on the icon. This will display a table of triples similar to the following image.

The history of changes

To view or download the details about the changes for a concept click on the icon. This will display a table of history similar to the following image. You can filter by a date range and/or by a particular user.

Import (Merge data)

To import a subtree (a subtree is a hierarchy of narrower concepts) into a concept click on the icon. This can be done at the top level of the taxonomy on the taxonomy home page, where the icon is on the right of the screen, or, for a concept, where the icon is displayed to the left of the concept details.

Select a spreadsheet, TSV or CSV file and then click Next.

The base language of the text within the file will be assumed to be the same as the default project language. It is used as the basis for computing the hierarchy of the data.

The base IRI is assumed to be that of the taxonomy being imported in to. This will form the first part of the IRIs that Graphologi will generate for your taxonomy.

The taxonomy being imported into will also be used as the basis for whether to use slash or hash IRIs and whether UUIDs or labels will be used for IRIs.

The next step is to map the data in your file. If you have a header row in your file select 'Ignore Header Row'. If your project is SKOS-XL enabled you will also have the choice to generate labels as SKOS-XL. This will apply to any preferred, alternative or hidden labels.

By default the first five rows or your data are displayed for preview. You can increase this by changing the value on the right of the screen. Note that the limit on the number of rows you can import depends upon the subscription type.

The next step is to map the columns in the file to properties in Graphologi. You only need to map the columns that you want to import. There must be at least one column that is a preferred label in the default language. A simple example is given in the following screenshot:

You can map concepts to each other using the SKOS related property. If a project has associated ontology projects then it will be possible to map classes and properties from that association. This includes both object (relationship) properties and datatype properties. For those properties that are relationships you need to select the cross-reference. This can be either a preferred label or a particular column. There is also the option to cross-reference a preferred label in another taxonomy within the project, allowing you to make links across taxonomies. The labels for this must be in the default project language. Also, note that cross-referencing across taxonomies is range aware, meaning that, if a range is on the property, then for the relationship to be created the target concept must have an appropriate class.

For example, if you have a column in your spreadsheet that you want to map to an associated 'Connected to' property and the values in that column are the preferred labels of the target concepts, select 'Preferred Label' as the cross-reference. In the example below column 3 is being mapped to the 'Connected to' property. The cross-reference is using preferred labels. In this example it means that 'Burger' would be connected to 'Steak' and 'Chicken burger' would be connected to 'Chicken'.

If a column contains values from another column such as unique identifiers select that column as the cross-reference. In the example below column 4 is being mapped to the SKOS related property. The cross-reference is using the unique values in column 1. In this example it means 'Burger' would be related to 'Steak' and 'Chicken burger' would be related to 'Chicken'.

Cross-reference columns do not have to be included in the import.

If a value in a cross-reference column does not exist in the spreadsheet Graphologi will try to find a matching value in the existing concepts of the taxonomy. This allows you to create relationships to concepts not in the spreadsheet.

Points to note:

• For boolean properties the acceptable cell values are 'true', 'false', 'yes' and 'no'. These are case-insensitive.
• For other datatype properties the cell value must be acceptable for that datatype.
• For mapping to classes the cell value must exactly match the label of the class.
• Cross-reference values must exist or an error will be reported.

The import is actually a merge. If there are rows in the spreadsheet that match with existing concepts then any cells with values will be added to any existing values. No existing data is removed.

Once you have done the mapping click Upload. The import will start. On successful completion you should see a Finish button, which, on clicking, will update the screen. If errors occur on import you will need to fix the data before attempting to import again.

Import is case insensitive for preferred labels. That is, if 'car' is in the spreadsheet and an existing concept has the label 'Car' the existing concept will be used. It is also possible to import cyclical references if they exist in the data, which will be reported via quality checks.

For more details on importing spreadsheets see the section on Importing data into a project.

Export

To export a concept or its subtree click on the icon. This will display options to download a concept, and if it has narrower concepts, its subtree. A subtree includes all the narrower concepts for a concept.

If a project is SKOS-XL enabled you will be able to select whether to include XL labels. Simply select which download you require and the RDF format in which you require your data and click the Download button.

Positioning

To view how a concept fits into the hierarchical structure of the project click on the icon. This displays the paths down to a concept as well as some statistics about the position of the concept. For polyhierarchical taxonomies this can be very useful to see the different locations of a concept.

You can 'jump' to a particular location in the hierarchy on the left by clicking the corresponding chip in the positioning view.

Filtering labels

A project may contain many labels. For example, Agrovoc has over 700,000 labels in multiple languages. This generally makes it impracticable to display all labels for a project. Therefore, a filter box is provided where you can type a few letters for labels you are looking for. You can also select the language. Hit enter after typing some text to apply the filter.

Add a label

To add a label click on the icon on the left of the screen (or use the keyboard shortcut Alt+N). This will display the following dialog box:

Select a language for the label and enter the text for the label. A label only has one 'literal form' (skos:literalForm).

If you wish to edit the automatically generated IRI for a label you can do so by selecting the 'View/Edit IRI' option (it may already be selected if set at the taxonomy level). The edited IRI must be unique within the project. Graphologi will not allow you to proceed until a unique IRI is entered.

To add the label click Add. If you are entering a large amount of labels you can click Multiple (or use the keyboard shortcut Ctrl+Enter), which will add the label and keep the dialog box open ready for you to add another label.

Delete a label

To delete a label click on the icon on the right of the screen.

Editing a label's literal form

To change the literal form of a label click into the text and start editing. You will be shown any similar labels as you type in a similar way to the image below, and, if your label is acceptable, a icon will be shown on the right of the field. Click to confirm the change.

To abandon a change simply click away from the field.

Free-floating labels

It is possible that a label used on a concept is not in any concept scheme, even if the concept to which it is related is. If this is the case you will see something similar to the following image.

To add the label into the current concept scheme click the icon.

Additional features

Similarly to a concept you can also view the underlying label triples or its history of changes by clicking on the appropriate icon.

Add a new top level concept

If you are on the taxonomy home page you can suggest a new top level concept. (You can get back to the taxonomy home page by clicking on the taxonomy name in the breadcrumb near the top of the screen.)

Add a new narrower concept for an existing concept

This suggestion type allows you to propose the addition of a new concept as a narrower concept to that on which the suggestion is made.

Move a concept

A concept may be better positioned in a different location in the hierarchy. This suggestion type allows you to propose a new broader parent as in the following image. Note that the following is what you would see when suggesting a move on a top level concept as there are no broader concepts to choose from.

Note that, if the suggested new broader parent is in multiple locations in the hierarchy, the move would result in the moved concept being narrower to that concept in all locations. If you attempt to move a concept that has existing broader relationships you will be asked to select which broader parent it should be moved from.

Remove a concept from a particular location in the hierarchy

A concept may be in an incorrect location in the hierarchy. This suggestion type allows a user to propose the removal from that location. This is equivalent to removing a concept from the hierarchy by clicking on the icon. If you attempt to remove a concept that has multiple broader relationships you will be asked to select which broader parent it should be removed from.

Deprecate a concept

If a concept has reached the end of its useful life a suggestion to deprecate it can be made. On acceptance of this type of suggestion Graphologi will actually deprecate the concept. This is equivalent to deprecating a concept by clicking on the icon.

Fix the spelling, adjust the terminology or split a concept

These suggestion types are free text suggestions, where the action is left to the taxonomist to apply.

Spelling suggestions are hopefully self-explanatory. They should be used to suggest corrections to labels.

An example of a terminology suggestion might be something like `Change “Sexual Equality between Men and Women” to "gender equity"`.

A split, for example, might be something like `"Social Problems and Offences” should be split into "social issues", and "social crimes"`.

Resources

Resources shows a filtered set of the resources in the dataset.

Controlling the language you are viewing

For projects using multiple languages it can be useful to switch the viewing language. This can be done using the language selector at the top right of the screen.

This controls various aspects of the editor. The resource list will reflect the language, as will the search and for certain dialog boxes the language will default to the viewing language.

If text in the viewing language is not available the view will try and use the default project language. Where the viewing language is not available the screen will highlight items in orange to indicate this information is not available.

Linked taxonomy projects

Please see the section Linked taxonomy projects in relation to taxonomies for more information.

Linked data

Please see the section Linked data in relation to taxonomies for details.

Dataset detail

The options here are very similar to that for taxonomies. Please see the section Taxonomy detail for more information.

Triples

Display all of the triples that exist for the resource. Note that for imported data there may be additional data that shows up here that is not editable in the application. If there is data which is not editable there will be a icon for each row, allowing you to remove those triples.

History

This allows you to view all changes made to the dataset. (Note that history for each resource can also be viewed separately in the detail view for a resource.)

Within this view you can control the scope of history to show only changes to the dataset itself, or for all changes to resources related to the dataset.

For further details please see History in relation to taxonomies.

Statistics

This displays resource counts for the dataset.

Quality

This runs a set of checks that cover various aspects of your data. Note that, in general, Graphologi will not permit actions that cause quality violations. However, the quality checks are there as a fallback to reinforce that.

Export

Exporting datasets is very similar to exporting taxonomies. Please see the section Export for more information.

Lifecycle

What appears on the Lifecycle tab will depend upon whether workflow is activated or not. The 'Deprecated' tab will always appear. If workflow is activated additional tabs will be displayed. See Viewing concepts, labels or resources with particular statuses for more details.

Add a resource

To add a resource click on the icon on the left of the screen (or use the keyboard shortcut Alt+N). This will display the following dialog box:

Enter a label. The language for the label will be the default project language. You can add additional labels in other languages, if configured, once the resource is created.

If you wish to edit the automatically generated IRI you can do so. The edited IRI must be unique within the project. Graphologi will not allow you to proceed until a unique IRI is entered.

To add the resource click Add. If you are entering a large amount of resources you can click Multiple (or use the keyboard shortcut Ctrl+Enter), which will add the resource and keep the dialog box open ready for you to add another resource.

Reuse an existing resource

The approach is similar to above but, as you type, suggested resources will appear similarly to the following image. If you have multiple datasets in your project you will have access to the resources in the other datasets when adding a resource. Further, you will also be able to make use of any free-floating resources within the project.

If you wish to use an existing resource click on it.

Even though suggestions may appear you can ignore them and create a new resource. There is the choice to reuse an existing resource (by clicking on it) or create a new resource by clicking Add.

Datasets (inDataset)

Where a resource is reused from another dataset it will be added to the current dataset. This will mean that the resource is in two datasets.

Deprecate a resource

It may be that over time certain resources become obsolete. However, if these resources have been used then their identifiers - IRIs - may need retaining. Deprecating a resource allows you to indicate that a resource should no longer be updated or used without removing it from a dataset.

To deprecate a resource click on the icon on the right of the screen.

Deprecated resources can no longer be edited and new relationships to them can no longer be formed.

If you realise that a resource has been deprecated by mistake you can simply undeprecate it by clicking on the icon on the right of the screen.

Delete a resource

To delete a resource click on the icon on the right of the screen. Note that once a resource is deleted it cannot be reused.

View the underlying RDF triples

To view the underlying triples for a resource click on the icon.

The history of changes

To view or download the details about the changes for a resource click on the icon.

Class/property tree

The class and property tree is displayed on the left of the screen. For a large ontology the tree may get very deep. An example of how a deep ontology looks is shown in the following image.

As ontologies get deep in terms of levels it can be difficult to remember the context of a node in the tree. To aid with understanding the context a summary of the hierarchy is shown when you hover over any node that is below a top node.

It may also be useful to adjust the display panels and there are various options to do this, which are accessed at the top of the tree.

If you have expanded the tree in multiple places and want to collapse it, you can do this by clicking on the icon.

For deep ontologies you may want to use more screen space to display the tree. The width can be altered by clicking on the icon. You can adjust the width up to three levels, after which the next click will return it to normal width.

Sometimes it is easier to work with just the tree in view to simplify the display. To do this click on the icon. To return to the normal view click the icon again.

For situations where an ontology has a large number of classes or properties at any level in the tree Graphologi will start paging these parts of the tree to help keep the user interface responsive. You can navigate between the pages by using the page number or the previous and next page icons.

Class, object, datatype and annotation

These tabs are Classes, Object Properties, Datatype Properties and Annotation Properties.

The Classes tab allows you to manage the ontology classes, whilst the other property tabs allow you to manage the relevant properties of that type.

Controlling the language you are viewing

For projects using multiple languages it can be useful to switch the viewing language. This can be done using the language selector at the top right of the screen.

This controls various aspects of the editor. The hierarchy will reflect the language, as will the search and for certain dialog boxes the language will default to the viewing language.

If text in the viewing language is not available the view will try and use the default project language. Where the viewing language is not available the screen will highlight items in orange to indicate this information is not available.

Detail

You can edit the title and description of the ontology. You can add additional titles and descriptions in any of the project languages. The title in the default language cannot be removed.

You can also add additional information, such as version information, comments and notes.

For more information on using annotation properties with an ontology please see Selecting annotation properties.

If you wish to display (or hide) additional properties, such as comments, see also, or SKOS annotations, you can control the display by checking or unchecking values in the 'Hide Properties from View' panel.

Some ontologies may have a lot of top level deprecated resources (e.g. OBO ontologies). This may lead to unwanted numbers of classes or properties being displayed and can slow down the display. You can hide top level deprecated resources by checking 'Hide Deprecated Resources (Top Level Only)' in the 'Viewing Options' panel. Note that for imported OBO ontologies this is set by default.

Note the IRI of the ontology, the slash/hash pattern option and the IRI format option are fixed once an ontology is created and cannot be edited.

Graphologi will set the default IRI options for an ontology when you create it. However, sometimes you may want more control over the creation of IRIs.

In the 'IRI Options' panel you can adjust the following for label based IRIs:

• By default, when using the label option for IRIs, Graphologi will encode the label using the case of the label. However, in ontologies there is often a pattern of using a lowercase letter to start property names. You can get Graphologi to do this by checking the 'Properties Have Lower Case First Letter' option.
• It is not always desirable to have spaces in IRIs. Graphologi will escape them by default, but if you want them removed check the 'Remove Spaces' option.
• Alternatively, rather than remove spaces it may be desirable to replace them. If you check the 'Replace Spaces' option then spaces will be replaced with hyphens. Note that removing spaces takes priority over replacing spaces.
• In a similar way it is not always desirable to have 'special' characters in IRIs. You have options to remove or replace these by checking the appropriate options.
• Certain characters need to be escaped in IRIs in order to not cause issues with reserved characters. By default Graphologi minimises encoding to only those essential characters. If you wish to encode a wider range of characters uncheck this option.

Triples

Display all of the triples that exist for the resource. Note that for imported data there may be additional data that shows up here that is not editable in the application.

History

This allows you to view all changes made to the ontology. (Note that history for each class and property can also be viewed separately in the detail view for that resource.)

Within this view you can control the scope of history to show only changes to the ontology resource itself, or for all changes to resources related to the ontology.

You can refine the details of what is shown by a date range and by a user. To filter by date simply select the start and end dates that you wish to see using the 'Date Range' filter. To view history only for a particular user select that user.

The history view contains a lot of detail, which can make it difficult to view easily on smaller screens. You can reduce the number of columns displayed by clicking on the icon and selecting those columns that you wish to view.

History can also be downloaded in either TSV or JSON format by clicking on the Download button and selecting the required format. The filters on date range and user also apply to any downloads.

Statistics

This displays class and property counts. A typical example output is shown below.

Quality

This runs a set of checks that cover various aspects that are generally accepted as not desirable in an ontology. Note that, in general, Graphologi will attempt to not permit actions that cause quality violations. However, the quality checks are there as a fallback to reinforce that.

Where there are quality issues they will be presented similarly to the following image.

Export

The export allows you to choose from various RDF serialisations.

Deprecated

This displays a list of all deprecated classes and properties, which you can filter by label name, language and resource type. Note that links to resources will show in orange. You can click on a resource to go to the detailed view for it.

Add a top level class

To add a top level class click on the icon on the left of the screen (or use the keyboard shortcut Alt+N). This will display the following dialog box:

Enter a label. The language for the label will be the default project language. You can add additional labels in other languages, if configured, once the class is created.

If you wish to edit the automatically generated IRI for a class you can do so. The edited IRI must be unique within the project. Graphologi will not allow you to proceed until a unique IRI is entered.

To add the class click Add. If you are entering a large number of classes you can click Multiple (or use the keyboard shortcut Ctrl+Enter), which will add the button and keep the dialog box open ready for you to add another class.

Add a subclass

Adding a subclass can be done in one of three ways. The first is by hovering over the class label in the hierarchy view. This will display icons for breaking a link to the ontology or superclass and adding a subclass as in the following image. Click on the icon. You will see the same dialog box as above.

Alternatively, you can drag classes from the hierarchy on to the 'Is Subclass Of' panel on the right of the screen.

Finally, you can add subclasses via the icon in the 'Is subclass of' panel or the 'Subclasses' panel, depending upon which direction the subclass relationship is in. This is shown in the following image.

If you have multiple ontologies in your project you can include classes from any of those ontologies as a subclass.

You can also directly enter external IRIs for subclasses. Simply type in the IRI and if it is valid you can add it.

Remove a class from the hierarchy

To remove a class, either at the top level or a lower level, click on the icon. Alternatively, for subclasses, you can click on the cross in a class's label in the appropriate panel on the right. Note that breaking the link does not delete the class, even if not used anywhere else. The class will still be available to use.

Deprecate a class

It may be that over time certain classes become obsolete. However, if these classes have been used then their identifiers - IRIs - may need retaining. Deprecating a class allows you to indicate that it should no longer be updated or used without actually removing it from an ontology.

To deprecate a class click on the icon on the right of the screen.

Deprecated classes can no longer be edited and new relationships to them can no longer be formed.

If you realise that a class has been deprecated by mistake you can simply undeprecate it by clicking on the icon on the right of the screen.

Delete a class

To delete a class click on the icon on the right of the screen.

Editing a class's labels

To change a label click into the text and start editing. If your label is acceptable, a icon will be shown on the right of the field. Click to confirm the change.

To abandon a change simply click away from the field.

Disjoint classes

You can define a class as disjoint with other classes. Click on the icon in the 'Disjoint With' panel.

Adding a disjoint class can be done in two ways. You can drag classes from the hierarchy on to the 'Disjoint With' panel on the right of the screen. Alternatively, you can add classes via the icon in the 'Disjoint With' panel.

Please note that although you can add disjoint classes Graphologi does not guarantee the consistency and checks will only catch issues in certain scenarios. We will look at adding additional consistency checks in future versions. We recommend running the quality checks as an additional validation if required.

You can also directly enter external IRIs for disjoint classes. Simply type in the IRI and if it is valid you can add it.

Equivalent classes

You can define a class as equivalent to other classes. Click on the icon in the 'Equivalent Class' panel.

Adding an equivalent class can be done in two ways. You can drag classes from the hierarchy on to the 'Equivalent Class' panel on the right of the screen. Alternatively, you can add classes via the icon in the 'Equivalent Class' panel.

You can also directly enter external IRIs for equivalent classes. Simply type in the IRI and if it is valid you can add it.

Positioning

To view how a class fits into the hierarchical structure of the project click on the icon. This displays the paths down to a class as well as some statistics about the position of the class. For polyhierarchical class structures this can be very useful to see the different locations of a class.

You can 'jump' to a particular location in the hierarchy on the left by clicking the corresponding chip in the positioning view.

Inbound relationships

It can be useful to see which properties are connected to a class via certain relationships. This is especially true for domain and range, which are relationships that are inbound to a class (i.e. from the property to the class). To view this information click on the icon.

Additional features

Similarly to a concept you can also view the underlying class triples or its history of changes by clicking on the appropriate icon.

Information applicable to all property types

There are a few notable things to point out.

• Each property has a unique IRI. Within Ontology Manager IRI generation is currently based on the label used when a property is created.
• There can be multiple languages for a property's data. All language based properties support this, such as comments.
• In most places within the application you can click on class links to navigate to that property.

Add a top level property

To add a top level property select the appropriate property tab for the type of property you want to add click the icon on the left of the screen (or use the keyboard shortcut Alt+N). This will display the following dialog box:

Enter a label. The language for the label will be the default project language. You can add additional labels in other languages, if configured, once the property is created.

If you wish to edit the automatically generated IRI for a property you can do so. The edited IRI must be unique within the project. Graphologi will not allow you to proceed until a unique IRI is entered.

To add the property click Add. If you are entering a large amount of properties you can click Multiple (or use the keyboard shortcut Ctrl+Enter), which will add the button and keep the dialog box open ready for you to add another property.

Add a subproperty

Object and datatype properties allow subproperties. Adding a subproperty can be done in one of two ways. The first is by hovering over the property label in the hierarchy view. This will display icons for breaking a link and adding a subproperty as in the following image. Click on the icon. You will see the same dialog box as above.

Alternatively you can drag properties from the hierarchy on to the 'Is Subproperty Of' or 'Subproperties' panel on the right of the screen, depending on which direction the subproperty relation holds.

If you have multiple ontologies in your project you can include properties from any of those ontologies as a subproperty.

Remove a property from the hierarchy

To remove a property, either at the top level or a lower level, click on the icon. Alternatively, for subproperties you can click on the cross in a label in the 'Is Subproperty Of' panel. Note that breaking the link does not delete the property, even if not used anywhere else. The property will still be available to use.

Deprecate a property

It may be that over time certain properties become obsolete. However, if these properties have been used then their identifiers - IRIs - may need retaining. Deprecating a property allows you to indicate that it should no longer be updated or used without actually removing it from an ontology.

To deprecate a property click on the icon on the right of the screen.

Deprecated properties can no longer be edited and new relationships to them can no longer be formed.

If you realise that a property has been deprecated by mistake you can simply undeprecate it by clicking on the icon on the right of the screen.

Delete a property

To delete a property click on the icon on the right of the screen.

Selecting annotation properties

For annotation properties to display on classes and properties you need to select which you wish to use for a particular ontology. This is done in the ontology details page, which looks as in the following image.

For SKOS annotations to show simply uncheck the relevant properties in the 'Hide Properties From View' panel.

To add other annotations in the 'Annotation Properties' panel click on the icon. All annotation properties from any ontologies within the same project will be listed. Select those that you wish to use.

If you wish to see the usage statistics of annotation properties defined in ontologies loaded within the project, you can click on the Compute Suggestions to Add button. This will compute statistics for each property and you can then choose whether to add them.

One selected the properties should appear on classes and properties. Note that the view is domain aware, so, if an annotation property has a domain that is not applicable, it will not display. You should see something similar to the following image. Note, if the values already exist they will appear once the properties are selected for the ontology.

Adding values to annotation properties

For SKOS annotations simply click on the icon and enter the value in the dialog.

For other annotations, depending upon whether an annotation property has a range or not, the controls to add values will differ. If a range is defined there will simply be an icon in that property panel and you will be restricted to adding values suitable for the defined range.

If a range is not defined you will see multiple icons for adding different types of data.

• The icon allows you to add links to resources (including external resources by simply typing in the IRI you want to add).
• The icon allows you to add a boolean value. Note you can only have true or false.
• The icon allows you to add language tagged strings using the languages set up for the project.
• The icon allows you to add date time values.
• The icon is used to add all other datatypes. This will display a dialog from which you can select a particular datatype and enter a value.

Note that it is highly unusual for a property to contain a mix of datatypes, but because there is no range defined you do have that option.

Adding the configuration

Within the project sidebar for a taxonomy or data project you will see an 'Associated Ontology Projects' option. This allows you to find and associate one or more ontology projects. Click on the Add Project button on the right of the screen. Start typing the name of the ontology project you are looking for and select it when it appears. The ontology project will be added similarly to the following image.

For each associated ontology project you can select the set of classes that you wish to make available in your project (often you will not need all of them).

You can also select which properties you want to be made available globally throughout your project.

Finally, you can create templates, which allow you to create sets of properties for use on concepts, labels, etc., giving you more control and allowing you to tune the user interface to only display appropriate properties. Each template can be associated with as many taxonomies or collections as required for taxonomy projects, or as many datasets as required for data projects.

Adding classes

To add classes click on the icon in the 'Classes to Make Available' panel. A dialog box will be displayed. This will look similar to the following image:

Note that, if the ontology you want to search uses a language other than the default for the taxonomy or data project, you may need to select the language from the list. This list reflects the languages available to the project.

Up to 100 classes will be listed. Select the classes that you want to add. To filter the list start typing the label of the class that you want to add.

Adding global properties

To add properties of any type click on the icon in the 'Global Properties to Make Available' panel. A dialog box will be displayed. This will look similar to the following image.

Up to 100 properties will be listed. Domain and range information for each property will also be listed, if available, to help you decide whether it is the property that you are looking for. Select the properties that you want to add. To filter the list start typing the label of the property that you want to add.

Note that, even for global properties, the domain will control what that property appears on. If a domain exists on the property the concept, label or resource must have that class in order for the property to appear.

If a property is both global and in a template and is computed to apply for display, the property will only appear under the global properties list. It will not be displayed more than once.

Adding templates

To add a template click on the icon in the templates panel. This will display a dialog box similar to the following image.

Enter the title for your template and click Add. This will add a template panel to the screen similar to the following image:

Each template allows you to select one or more classes for which the template should be used. If you do not choose any classes the template will apply to all concepts, labels or resources where it is used. For taxonomy projects, if the project has SKOS-XL enabled, you will have the option to check a box to use the template on SKOS-XL labels. You can also include taxonomies, collections, datasets and annotations as target classes by checking the appropriate boxes. For taxonomies, collections and datasets property templates will appear in the 'Advanced Metadata' submenu. If you check these boxes you can still select other classes.

You can then select the properties that you want to be associated with the template. Your templates should eventually look similar to the following image:

If you have more than one template you can filter them using the filter box. Additionally you can 'jump' to a particular template by clicking on the panel for it in the summary list at the top of the templates area. To scroll back to this area you can use Alt+t, or, alternatively, if you have jumped to a template, click on the icon in the bottom right of the screen.

Note that property selection is not constrained by the class selection, but you will see warnings if there is a disconnect between the two. This is not necessarily an error, which is why Graphologi does not stop you doing so, but in most situations it would be expected that the classes and domains would match up.

You can have as many templates as you want. A good approach may be to group together properties based on a particular purpose or group of users that might want to edit the properties.

Sometimes the default label from the ontology for a property isn't ideal or suitable. You can override the name that will be displayed by adding a value using the icon in the name placeholder. Similarly, it can be useful to give users a bit of information about what they are expected to do, or what the property is for, and you can do this by adding a description, again using the icon in the description placeholder.

It may be that you want to further restrict the use of properties used in templates. You can set various constraints and options:

• The minimum number of times a property must be used.
• The maximum number of times a property may be used (note for functional properties this is automatically set to 1).
• For text properties, the maximum length of text.
• For text properties, a regular expression defining tha pattern the text must comply with.
• For text properties with a range of string or 'any URI' it is also possible to select how the content should be treated. The options will be from: an image link, markdown, HTML, SVG or MathML. If you select one of these then when data is entered it will be rendered accordingly. Note that the entered data is not validated other than for URIs.
• For relationships, an option to select the target from which the values must be selected, which can be any taxonomy or collection within the project. An example might be, say, an 'isInCountry' property that can only take values from a 'Country' taxonomy. To select a target click the Add button. For data projects it is still possible to use this feature, but you will have to change the target project to a taxonomy project to be able to select.

For each constraint Graphologi will indicate if that constraint is not being met. Graphologi will limit the input for a property to ensure that it complies with the constraints.

Please note the following important points:

• That having a cardinality constraint (minimum or maximum number of times a property may be used) does not 100% guarantee that the constraint cannot be broken. There are various possibilities where this might happen. For example, through import or through concurrent edits made by users. However, these will be rare situations.
• Due to the fact that properties can appear in more than one template and multiple templates may be used, constraints may conflict. Graphologi will display information about any conflict on the property. We would recommend restricting the use of a property to a single template if the use case permits this.
• Care should be taken when using constraints on properties that appear in multiple templates, used on separate concept schemes and where concepts are used in those multiple concept schemes. It may be that a property is then 'valid' in one concept scheme but not in another. This applies to datasets in a similar manner.
• Constraints do not apply to global properties, so, as mentioned above, if a property is both global and in a template it will be treated as global and the constraints will not be applied.

Enriching concepts, labels and resources

Configured ontology classes can be used on concepts, SKOS-XL labels or resources, whilst properties can be used on concepts, SKOS-XL labels, taxonomies, collections and datasets. The following image shows additional global properties being available for a label as an example.

The screen will display any global properties first, then the properties applicable for templates. All properties for all applicable templates will be grouped together. If properties are in templates and also global they will only appear in the global list.

Assigning a template

Templates can be assigned for taxonomies, collections and datasets. The approach is the same for each. To add a template go to the details page (by clicking on the down arrow next to the title of the taxonomy, collection or dataset). Scroll down to find the panel title 'Property Templates'. Click on the icon and select the templates that you wish to assign. Once selected it will look similar to the following image:

Annotations

Annotations allow you to add additional information about the values added for properties. The technical term for this is called 'reification'. For example, let's say you have a concept 'England' and it has a property 'population' with a value of '60 million'. You can annotate this 'triple' of England->population->60 million. This can be very useful to record the provenance of where the information came from, or potentially the context in which it should be used.

Annotation is done using templates. You might want to create specific templates just for annotations.

To activate annotations for a taxonomy, collection or dataset click on the 'Is Activated' option in the 'Annotate' panel.

Adding a class to a concept, SKOS-XL label or resource

To add an ontology class click on the icon in the 'Classes' panel. This will display a dialog. If you are adding to a concept on which there are narrower concepts and you want the class to be added to those concepts as well check the 'Add Class to Narrower Concepts' option (but note this will only apply to concepts that are in the same scheme). Start typing the name of the class you want to add. A list of matching classes will be displayed. This will look similar to the image below.

Select the class you want to add. The class will be added to the 'Classes' panel.

Adding default classes to all concepts or resources

To add any default classes for a taxonomy to all concepts in the hierarchy of the taxonomy (that are in the scheme), or to all resources in a dataset, click on the icon on the home page for the taxonomy or dataset, located towards the right-hand side of the screen. This operation is a batch operation and may take a little time to run if there are a lot of items to process.

Property display

For each ontology property configured for use and for which the concept, label or resource has the correct domain (if the ontology property has a defined domain), or, for properties that have no domain, will be listed in an area at the bottom of the details section for a concept, label, etc, similarly to the following image.

Adding a value

To add a value for a property click on the icon in the appropriate property panel. This will display a dialog similar to the following (if an integer range is defined on the property):

Enter a value and click Add.

For different range values different dialog boxes will be presented. The entered value must comply with the datatype. Where a property template indicates the text should be 'treated' in a particular way the dialog will be adjusted accordingly and the value rendered if the text is valid for that type. Note that, for markdown text, two newlines are required to display a linebreak.

Adding a relationship

Constraints on range also apply to object properties. That is, to make a relationship for an object property with a defined range, a concept must have the appropriate class associated with it.

To add a relationship for an object property click on the icon in the appropriate property panel. This will display a dialog box. Start typing the label for the item you wish to make the relationship to.

Select the desired value to add it. Once added it will display similarly to the image below:

Adding annotations

If annotations are activated an additional icon will be displayed to the left of a field or chip, as shown in the following image. A grey icon indicates no annotation exists for that value, a green icon indicates one does exist and an orange icon indicates the annotation is deprecated.

To add an annotation, or edit an existing one click on the icon. That will open a dialog box similar to the following image:

On this screen you can add data the same as elsewhere where templates are used. You also have access to the triples view and the history for the statement. You can also deprecate or delete the statement.

Note that IRI generation for statements is fixed. The IRIs will use the base IRI of the taxonomy or dataset and append a UUID to ensure uniqueness.

If a value is changed in a field or a relationship deleted then it is likely that the annotation will no longer be relevant. These annotations are not removed automatically. If you do wish to clean up disconnected annotations you can click on the icon on the home page for the taxonomy or dataset. Annotations that will be cleaned up are those where the subject of the annotation (the concept or resource) is still in the concept scheme or dataset.

Inverse and symmetric relationships

Graphologi will automatically manage inverse and symmetric relationships. However, if you have created data before making a property symmetric, or adding an inverse, you may end up with situations where the information does not exist in both directions. Graphologi will handle edits to these relationships and it will not cause any errors.

However, you may want to consider synchronising the relationships for consistency. To do this click on the icon on the taxonomy or dataset home page, located towards the right-hand side of the screen. This operation is a batch operation and may take a little time to run.

If the relationships in a taxonomy or datasets reference other taxonomies or datasets within the project you will need to run the synchronisation on each taxonomy or dataset.