FAQ

How do I change the grounding?

There are two ways to think of this question. First, if you want only to select which of the existing Grounders to use when grounding, this is determined in eidos.conf with ontologies.ontologies. The value for this key is a list of strings, where the strings correspond to the user-provided paths to the available ontologies. By including a path here, the grounder will be enabled and the corresponding groundings will be included in the output.

On the other hand, if you want to implement a new grounder, you would extend the EidosOntologyGrounder class. The main entry points are:

• groundEidosMention: for when you're (re)grounding an Eidos Mention (almost always what we're doing)
• groundText: for when you're (re)grounding a string (NOTE: This is only used when using the reground API endpoint through the webapp, as that's the only time we don't have an Eidos Mention.)

These are the things you should override/start with if you want to make a custom implementation. Do look through the methods available in the super class, though, as there are many things that are likely useful for you. These include (but are not limited to):

• newOntologyGrounding: a method that can be used to easily make an instance of our grounding info. Note that because of the defaults, this can also be used to easily make an empty grounding.
• conceptEmbeddings: these are the internal representations of the ontology nodes in terms of their examples. Each node has a ConceptEmbedding, which essentially has a name and a vector representation that is more or less the average of the example/definition terms. See class definition for more detail.
• conceptPatterns: similar to above, each node in the ontology here is represented in terms of its (optional) regex. Thus, each ConceptPattern essentially has a name and an optional array of Regex.
• groundPatternsThenEmbeddings: method that first applies the regexes for the nodes, and then only if no regexes match, tries to ground using the Embeddings.

How do I change the rules?

The rules are spread through several files, all of which are imported through a master file (e.g., the master.yml for english). There are many ways to change rules, and at many levels:

1. I want to add or remove a trigger. Often, when looking at new data, it appears that either we need a new trigger to get additional extractions or else an existing trigger has a different usage in a given domain and so is producing noisy extractions. To adjust the triggers, modify triggers.yml. The triggers in this file are akin to word stems, they don't include endings most of the time. In general, the triggers are used in the grammars to specify what a word starts with. There are triggers for many of the things we extract: increases and decreases (those that could serve as causal triggers too distinct from those which can't), triggers for positive and negative affect (i.e., if something got better or worse), causality, reverse direction causality (i.e., causal triggers, but ones in which the subject is the effect and the object is the cause), and correlation. Edit away!

2. I want to adjust the dependencies that apply in a particular pattern, but all I see is something like ${agents}, what does that mean? The Eidos grammars make use of Odin variables, which are indicated using the ${...} syntax. Most of the rules import these variables from vars.yml. Here you will see lots of regex patterns, and you can adjust them or add new ones as desired.

3. I want to add a new rule. Select which imported rule file is most relevant to what you want to add (or make a new file and import it). Many of the triggers are used with generic syntactic patterns found in one of the template files, e.g., linkersTemplate.yml, so these are good places to add/tweak a template. Note that changes made here will apply to many triggers/extraction types. Additionally, if you want a more restricted application, consider adding the rule to one of the explicit files, e.g., explicitModifiers.yml. These receive only the corresponding triggers. Finally, there are some files that are single relation only, e.g., causal.yml

4. I want to use a completely different set. Ok, you can point the system to a different master file in eidos.conf by setting causal.rulesPath to the relative path to the new master in the resources. However, please note that Eidos is not a general purpose reading system, so there are several places in the code where things will really only work properly with causal relations -- e.g., assumptions about the existence of cause and effect args, etc. So, keep that in mind. If you want more of a blank slate, consider using this repo as a starting point: odin-quick-start

How can I build a minimal Eidos?

Building a minimal Eidos is useful for many reasons, including that not all the components are useful or applicable in a given domain or there are resource constraints. Luckily, for most purposes a minimal Eidos can be specified changing only the config (i.e., eidos.conf). Here are things you can do:

• disable some finders: you can set EidosSystem.finders = ["rulebased", "causal"]. If you want to have locations/times, you can include context and optionally timenorm and geonorm.
• turn off grounding: you can disable grounding by setting ontologies.useGrounding = false.
• disable gradable adjectives: set adjectiveGrounder.useAdjectives = false.
• disable sentence classifier: ensure that sentenceClassifier.enable = false.