A very simple example to get familiar with the syntax

[HRezaei]

Hi and thank you for opening up the discussion section.

I'm trying to learn pyreason, executed the hello world example successfully, and saw the csv files in the output folder. But I need to know the API, the syntax, by which a problem must be encoded. Thus decided to start with a very smaller example. Let's say we have just Mary and John, the only fact we know is that Mary owns a cat, and the only rule we know is that John will be friends with whoever owns a pet, i.e:
$\forall x,y(Owns(x, y) \land pet(y)\implies Friends(John, x))$

Here is my graph file:

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
<key id="type" for="node" attr.name="type" attr.type="string"/>
<key id="name" for="node" attr.name="name" attr.type="string"/>

<graph id="G" edgedefault="directed">
<node id="Mary"><data key="type">person</data></node>
<node id="John"><data key="type">person</data></node>

<node id="Cat"><data key="name">cat</data><data key="type">pet</data></node>

<edge id="e0" source="Mary" target="Cat"></edge>
</graph>
</graphml>

The first question is: Should I add another edge like <edge id="e1" source="Mary" target="John"></edge>? Is it necessary? How can I define the graph as fully connected?

The second question is how to encode the only rule we have. Here is my rules file:

---
# All Rules come under here
rule_1:
    target: friends     # Target label

    target_criteria:       # List of all target criteria
        # All criteria come here in the form [label, lower_bound, upper_bound]
        - [friends, 0, 1]

    delta_t: 1             # Delta t, time when this rule is applicable

    neigh_criteria:        # List of all neighbour criteria in the form [criteria on node/edge, variable, label, [lower_bound, upper_bound], [equal/greater/less/greater_equal/less_equal, number/[percent, total/available], value]]
        - [node, [x1], ???, [1,1], [greater_equal, number, 1]]  # should I replace ??? with pet? But pet is a type, not a label. Are types considered as labels?
        - [edge, [target, x1], owns, [1,1], [greater_equal, number, 1]]

    edges: [John, target, ???]  # Also, not sure if the reference to John is correct or not?

    ann_fn: [1,1]          # Annotation function name or bound. See annotation_functions.py for list of available functions. The name of that function comes here
                           # Could be func_name or [l, u]

It's not clear how to define: if there is an x1, of type pet, and there is a target node who owns the x1, then a label friends should be added to the edge between John and the target?

[dyumanaditya]

Hi @HRezaei, apologies for the late reply.

For your first question:

There are two ways of doing this:

1. You can have a rule that creates an edge between two people (by using the edge option in rules.yaml) if the conditions are satisfied. In this case it would create a node between Mary and John with a friends attribute set to [1,1]. This is recommended since it will be simpler. I will show you how to make this specific case work below.
2. You can have a rule that modifies the friends attribute from [0,0] to [1,1]. In which case, you would need to have a pre-defined edge between Mary and John with friends set to [0,0] in the graphml file.

For your second question:

Your graphml file is not entirely optimal, based on your graphml, type-pet, type-person and name-cat will be labels and not the desired pet. Also node the edge label owns is not present in your graph edge between Mary and Cat Please see below:

Solution walkthrough

I'll walk you through how to make this example work:

1. Create a graph using networkx. It is easy to create new graphs and add attributes to nodes/edges. Use the following code:

import networkx as nx

g = nx.DiGraph()

# Two people with attribute `person = [1,1]`
g.add_node('Mary', person=1)
g.add_node('John', person=1)

# Create a node Cat with attribute pet=1 (in PyReason this attribute will act as a fact setting `pet = [1,1]`)
g.add_node('Cat', pet=1)

# Create an edge between Mary and Cat, with the edge attribute `owns = [1,1]`
g.add_edge('Mary', 'Cat', owns=1)

nx.write_graphml_lxml(g, 'graph.graphml', named_key_ids=True)

This will create the desired graph, I'm attaching the graph file below.

2. Create the rules.yaml file:

# All Rules come under here
rule_1:
    target:     # You do not need a target label since you are adding a new edge and not modifying an existing label

    target_criteria:       # The Target node has to be a person
        - [person, 1, 1]

    delta_t: 1             # Delta t, time when this rule is applicable

    neigh_criteria:        # List of all neighbour criteria in the form [criteria on node/edge, variable, label, [lower_bound, upper_bound], [equal/greater/less/greater_equal/less_equal, number/[percent, total/available], value]]
        - [node, [x1], pet, [1,1]]          # you can omit [greater_equal, number, 1] because this is the default
        - [edge, [target, x1], owns, [1,1]] # you can omit [greater_equal, number, 1] because this is the default

    edges: [John, target, friends]  # To create an edge or edges, specify the node or subset of nodes and the label to add/modify

    ann_fn: [1,1]          # Annotation function name or bound. See annotation_functions.py for list of available functions. The name of that function comes here
                           # Could be func_name or [l, u]

Please take a look at the comments inside the file.

x1 will be Cat and since the edge (Mary, Cat) has the attribute owns: [1,1], this rule will create an edge between (John, Mary) with attribute friends: [1,1].

3. Run Pyreason:

import pyreason as pr

pr.settings.verbose = True
pr.settings.atom_trace = True
pr.load_graph('graph.graphml')
pr.load_rules('rules.yaml')
interpretation = pr.reason()
pr.save_rule_trace(interpretation)

You should be able to see the change in friends in the edge rule-trace.

Graphml file generated in step 1:

<?xml version='1.0' encoding='utf-8'?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
  <key id="owns" for="edge" attr.name="owns" attr.type="long" />
  <key id="pet" for="node" attr.name="pet" attr.type="long" />
  <key id="person" for="node" attr.name="person" attr.type="long" />
  <graph edgedefault="directed">
    <node id="Mary">
      <data key="person">1</data>
    </node>
    <node id="John">
      <data key="person">1</data>
    </node>
    <node id="Cat">
      <data key="pet">1</data>
    </node>
    <edge source="Mary" target="Cat">
      <data key="owns">1</data>
    </edge>
  </graph>
</graphml>

[HRezaei]

Thank you very much @dyumanaditya!
It solved some other questions too!

However, there are other questions:

1. Now, with the above working example, if I want to remove $\land pet(y)$ from the rule, and restrict the Owns relation to accept only pets as the second argument, how should I populate the ipl.yaml file?
2. How to add other logical operators such as or? For example, $\forall x,y,z(Owns(x, y) \lor (Popular(x) \land Popular(z)) \implies Friends(z, x))$
3. Is it possible to define rules programatically, rather than using yaml files?

It would be appreciated if you please provide insights regarding the above questions as well!

[kmukherji]

@HRezaei let me jump in and answer what I can.

1. To make that change, you do not need to modify ipl.yaml. Instead, when you write the labels.yaml file, specifically in the section:

edge_specific_labels:
- special_edge_label: [] #replace with something like:
- owns: [[person1, pet1], [person2, pet2]]

What this will do is limit owns(x,y) to the edges you specify.

2. or in the rule body like: a or b => c is equivalent to two rules: a => c and b => c. And in this case it is beneficial to write it that way as it allows you trace the cause of each change in bounds.

3. Short answer is yes, but the user needs to write a script to convert such a program into .yaml.
   Long answer: .yaml files are the input format to PyReason and has been selected solely because a number of enterprise frameworks produce output in .yaml format - which would then serve as input to PyReason. However, we recognize that some in the logic community might want to use Prolog or Datalog programs with PyReason. We are working on creating a parser specifically to handle Prolog. However, as this sits outside PyReason - the user can easily write their own parsers for their own preferred language to interface with .yaml files.

[dyumanaditya]

Hi @HRezaei,

Just to add to what @kmukherji mentioned:
For point 1:
You do not necessarily need to modify anything (not even the labels.yaml). The graphml file was built in such a way (see the networkx script in the selected answer) that there is only one edge with the attribute owns and that is (Mary, Cat). Therefore the clause $$\wedge pet(y)$$ is redundant and not necessary in the body of the rule. It is clear that the label owns is specific to a human -> pet edge.

The labels.yaml can be modified in the way @kmukherji suggested only if there are any labels that are not in the graphml file that you would like to add to specific nodes/edges.

[kmukherji]

In short, by limiting the definition of owns to edges between people and pets (whether you use labels.yaml or graphml - is a personal preference/convenience) ensures that owns is specific to a human -> pet edge while grounding the rules.