Updated explain command

[matentzn]

Various updates

Resolves [#756, #329, #686]

• docs/ have been added/updated

• tests have been added/updated

• mvn verify says all tests pass <- cant run
  

• mvn site says all JavaDocs correct <- cant run (see mvn site fails because of some problem with DiffOperation #777)

• CHANGELOG.md has been updated

This pull request contains a number of changes to the explain command. The original command behaviour (which I refer to as entailment explanations) are untouched. See updated documentation for details.

Summary of changes:

1. We can now generate explanations for
   • inconsistent ontologies
   • unsatisfiable classes (all at once, root unsats, random subset)
2. Markdown exports get a summary which shows the most frequently used axioms across all found ontologies. This will help with debugging by focusing the attention on likely culprits.
3. Added some unit tests to explain and updated docs.

To achieve the above, there are now two new options:

• -M\--mode: allows switching between entailment (default), inconsistency and unsatisfiablity.
• -u\--unsatisfiable: allows various fine grained options for generating explanations for unsatisfiable classes:
  • all (generate explanations for all unsats)
  • root (generate explanations for root unsats)
  • random:n subset (generate explanations for n random unsatisfiable classes.

Example entailment summary (under the normal explanations in the markdown export):

uvular muscle SubClassOf Nothing

• uvular muscle SubClassOf palatal muscle
• palatal muscle DisjointWith uvular muscle

epimysium SubClassOf Nothing

• epimysium SubClassOf dense irregular connective tissue
  • dense irregular connective tissue SubClassOf irregular connective tissue
    • irregular connective tissue SubClassOf connective tissue
      • connective tissue SubClassOf tissue
        • tissue SubClassOf multicellular anatomical structure
  • dense irregular connective tissue SubClassOf dense connective tissue
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure

skeletal muscle tissue SubClassOf Nothing

• skeletal muscle tissue SubClassOf part of some skeletal muscle organ
  • skeletal muscle organ EquivalentTo muscle organ and (develops_from some myotome) and (surrounded_by some epimysium) and (composed primarily of some skeletal muscle tissue) and (synapsed by some motor neuron)
    • epimysium SubClassOf dense irregular connective tissue
      • dense irregular connective tissue SubClassOf irregular connective tissue
        • irregular connective tissue SubClassOf connective tissue
          • connective tissue SubClassOf tissue
            • tissue SubClassOf multicellular anatomical structure
      • dense irregular connective tissue SubClassOf dense connective tissue
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure

dense irregular connective tissue SubClassOf Nothing

• dense irregular connective tissue SubClassOf irregular connective tissue
  • irregular connective tissue SubClassOf connective tissue
    • connective tissue SubClassOf tissue
      • tissue SubClassOf multicellular anatomical structure
• dense irregular connective tissue SubClassOf dense connective tissue
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure

skeletal muscle organ SubClassOf Nothing

• skeletal muscle organ EquivalentTo muscle organ and (develops_from some myotome) and (surrounded_by some epimysium) and (composed primarily of some skeletal muscle tissue) and (synapsed by some motor neuron)
  • epimysium SubClassOf dense irregular connective tissue
    • dense irregular connective tissue SubClassOf irregular connective tissue
      • irregular connective tissue SubClassOf connective tissue
        • connective tissue SubClassOf tissue
          • tissue SubClassOf multicellular anatomical structure
    • dense irregular connective tissue SubClassOf dense connective tissue
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure

palatal muscle SubClassOf Nothing

• palatal muscle EquivalentTo skeletal muscle organ and (part of some soft palate)
  • skeletal muscle organ EquivalentTo muscle organ and (develops_from some myotome) and (surrounded_by some epimysium) and (composed primarily of some skeletal muscle tissue) and (synapsed by some motor neuron)
    • epimysium SubClassOf dense irregular connective tissue
      • dense irregular connective tissue SubClassOf irregular connective tissue
        • irregular connective tissue SubClassOf connective tissue
          • connective tissue SubClassOf tissue
            • tissue SubClassOf multicellular anatomical structure
      • dense irregular connective tissue SubClassOf dense connective tissue
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure

Axiom Impact

Axioms used 5 times

• dense irregular connective tissue SubClassOf dense connective tissue [uberon-base.owl]
• dense irregular connective tissue SubClassOf irregular connective tissue [uberon-base.owl]
• DisjointClasses: multicellular anatomical structure, dense connective tissue, developing mesenchymal structure [uberon-base.owl]
• tissue SubClassOf multicellular anatomical structure [uberon-base.owl]
• irregular connective tissue SubClassOf connective tissue [uberon-base.owl]
• connective tissue SubClassOf tissue [uberon-base.owl]

Axioms used 4 times

• epimysium SubClassOf dense irregular connective tissue [uberon-base.owl]

Axioms used 3 times

• skeletal muscle organ EquivalentTo muscle organ and (develops_from some myotome) and (surrounded_by some epimysium) and (composed primarily of some skeletal muscle tissue) and (synapsed by some motor neuron) [uberon-base.owl]

Axioms used 1 times

• uvular muscle SubClassOf palatal muscle [uberon-base.owl]
• palatal muscle EquivalentTo skeletal muscle organ and (part of some soft palate) [uberon-base.owl]
• skeletal muscle tissue SubClassOf part of some skeletal muscle organ [uberon-base.owl]
• palatal muscle DisjointWith uvular muscle [uberon-base.owl]

Ontologies used:

• uberon-base.owl (http://purl.obolibrary.org/obo/uberon/uberon-base.owl)

[matentzn]

@dosumis @cmungall FYI

[matentzn]

I have just added a way to see which ontologies an axiom comes from in the markdown overview. Note this only works with real imports, not with the source_ontology annotation.

[matentzn]

I walked @cmungall through this PR and he is happy

[balhoff]

This is great!

I have just added a way to see which ontologies an axiom comes from in the markdown overview.

Does this also work with the previous entailment mode?

[matentzn]

It does! But only in the summary at the bottom. So for a 1 explanation scenario it will be redundant, but yes, you get that information!

[beckyjackson]

Overall code looks good - see comments.

[matentzn]

I converted this to draft to incorporate all of @beckyjackson feedback from the measure command first before giving this up for review.

#778

[jamesaoverton]

I tried updating the japicmp pluging in robot-core/pom.xml to the latest version 0.15.2. Then the integration tests passed under Java 8. Under Java 15 (in Docker) I got one failure involving the order of prefixes in one test file. I don't think that's a problem with the code here. I also made a general issue about updating plugins #798.

[jamesaoverton]

Sorry for the delay @matentzn.

@beckyjackson Please merge when ready.