Skip to content

Extend and patch the knowledge graph

Introduction

In Studio it is possible to extend the project's knowledge graph by adding syncons, relationships between existing syncons and user data to existing syncons.

You can also patch the existing knowledge graph by adding, deleting and modifying existing lemmas and many more actions described in detail in the dedicated page.

Warning

Extension and patching are not available if the project was imported from an old project based on the legacy technology without updating the format of the knowledge graph.

You do this using the Knowledge Graph Editor Settings window.

The extension—and patch—operations are divided into four common phases:

  1. (Outside Studio) Prepare the files containing the specification of the changes to be made to the knowledge graph.
  2. Import the above files in your Studio project: source files are pre-processed to produce files with .kge extension inside the project's kge folder which are suitable for the build operation.
  3. Build the knowledge graph with the .kge files produced by the pre-processing referred to in the previous point.
  4. Reload the knowledge graph to make the extended and/or patched KG available.

All the actions described below are applied for both extension and patch operations.

Info

If the project was imported from an old Cogito Studio project, please read carefully about the implications on knowledge graph customization of the choices made during the import procedure.

Source files preparation

Files with the .txt extension allow you to easily add entities (people, organizations, brands, products, etc.) to the knowledge graph. Files with the .csv extension allow for more operations.

A few things to remark:

  • While for the knowledge graph extension you can use both .txt and .csv files, for the knowledge graph patches, only .csv files are allowed.

  • If you have to extend and patch the knowledge graph, two files are necessary:

    • One with the patch operations in the Patch tab.
    • One with the extension operations in the Extension tab.

Read the article in the appendix to learn how to prepare these files according to your needs.

Import .txt files

To import a .txt file, in the Knowledge Graph Editor Settings window:

  1. Select the Extension tab and select Add Import File .
  2. Select the .txt file to import. The Import into Knowledge Graph dialog will appear.
  3. In KGE Filename enter the name to give to the corresponding pre-processed file (.kge extension).
  4. In Separator select the character possibly used in your .txt files to separate multiple lemmas for the same syncon.

  5. Select the button representing a funnel to look for the parent syncon. The search dialog has the same properties of the Knowledge Graph Search tool window. Your selection will fill the Parent Syncon field.

    Info

    The parent syncon is the syncon to which the syncons of the entities created with the extension operation will be connected with the supernomen/subnomen link. Entities syncons will be "children" (subnomen) of the specified parent syncon.

  6. In Definition enter the gloss for all the syncons listed in the file (all the syncons will have the same gloss)1.

  7. Check Copy in project folder to create a copy of your file in the kge\source folder of the project.
  8. Select Import. The file is added to the imported files list and corresponding files with .kge and .import extensions are created under the project's kge folder. Also, the kge\main.kge file is updated.

Import .csv files

To import a .csv file, in the Knowledge Graph Editor Settings window:

  1. Select the Extension tab for extension operations or the Patch tab for patch operations.
  2. Select Add Import File .
  3. Select the .csv file to import. The Import into Knowledge Graph dialog will appear.
  4. In KGE Filename enter the name to give to the corresponding pre-processed file (.kge extension).

  5. In CSV Type select:

    • EXT for .csv files used to extend the knowledge graph.
    • PATCH for .csv files used to patch the knowledge graph.

  6. Check Copy in project folder to create a copy of your file in the kge\source folder of the project.

  7. Select Import. The file is added to the imported files list and corresponding files with .kge and .import extensions are created under the project's kge folder. Also, the kge\main.kge file is updated.

Note

Some example files and Excel templates are already downloadable and ready to be used.

Errors and warnings

During import, Studio analyzes files for validity and find errors that prevent the use of one or more files and other non-blocking problems. For each imported file, errors and warnings are written to a text file in MarkDown format with the extension .md saved in the kge sub-folder of the report folder. This report file contains a table in which, for each report, the following are indicated:

  • The line of the import file to which the problem refers to or -1 for file-wide problems.
  • The type of problem: ERR for blocking errors, WARN for warnings.
  • The description of the problem.

Even if you do not get errors but only warnings, it is advisable to read the report files.

Remove a file

To remove an imported file, in the Knowledge Graph Editor Settings window:

  1. Select the Extension tab or the Patch tab.
  2. Select the file from the list, then select Remove Import File .
    Corresponding files with .kge and .import extensions inside the project's kge folder are deleted and the kge\main.kge file is updated.

Change the evaluation order

Pre-processed files—those with .kge extension in the project's kge folder—are evaluated one after the other during the build operation, using the same order in which they are listed in the Knowledge Graph Extension Settings window.

To change the order in which files are evaluated during the build operation, in the Knowledge Graph Editor Settings window:

  1. Select the Extension or Patch tab.

  2. Select a file, then select:

    • Up to move the file up one step.

    Or:

    • Down to move the file down one step.

Re-import a file

To re-import a source file after some changes, in the Knowledge Graph Editor Settings window:

  1. Select the Extension or Patch tab.
  2. Select the file, then Reimport File .

Create the new knowledge graph

  1. Select Build to build the extended and/or patched knowledge graph.
  2. In the dialog, select Yes. Studio will be restarted to apply changes.

After reloading, the extended and/or patched knowledge graph is available and changes are accessible via the Knowledge Graph and the Knowledge Graph Search tool windows.

Remove the extensions

To build a new baseline knowledge graph out of a previously extended knowledge graph, in the Knowledge Graph Editor Settings window:

  1. Select Remove Extensions.
  2. In the dialog, select Yes. Studio will be restarted after the operation.

Possible patches are not undone.

Reset the knowledge graph

To restore the original baseline knowledge graph:

  1. In the Knowledge Graph Editor Settings window, select Reset.
  2. In the dialog, select Yes. Studio will be restarted after the operation.

  1. Glosses may be invisible inside the Knowledge Graph and the Knowledge Graph Search tool windows depending on the type of knowledge graph. ↩