Documenting shape-to-template process and adding some QoL improvements

[gtfierro]

@MatthewSteen is this what you were looking for?

[MatthewSteen]

Did some testing with this on the shapes from #263 and #265.

1. I think it would be nice to have a way to generate the YAML templates, is there a way to save to do that to save users the time to write them?

2. I got some errors with the 4.10-chilled-water-plant.ttl (after adding : a owl:Ontology to it, 4.11 and 4.12 seemed to work). First lines are from a print('', root_param, path, param, '') statement added to line 242.

 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p13 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p14 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p15 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPart urn:___param___#p16 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p17 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPart urn:___param___#p18 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p19 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPart urn:___param___#p20 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p21 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPart urn:___param___#p22 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPart urn:___param___#p23 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p24 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p25 
 urn:___param___#name https://brickschema.org/schema/Brick#hasPoint urn:___param___#p26 
 urn:___param___#name None urn:___param___#p27 
---------------------------------------------------------------------------
AssertionError                            Traceback (most recent call last)
/home/ubuntu22/BuildingMOTIF/notebooks/shape-to-template.ipynb Cell 4 line 5
      [2](vscode-notebook-cell://wsl%2Bubuntu-22.04/home/ubuntu22/BuildingMOTIF/notebooks/shape-to-template.ipynb#W4sdnNjb2RlLXJlbW90ZQ%3D%3D?line=1) hhw = "../libraries/ashrae/guideline36/4.11-hot-water-plant.ttl"
      [3](vscode-notebook-cell://wsl%2Bubuntu-22.04/home/ubuntu22/BuildingMOTIF/notebooks/shape-to-template.ipynb#W4sdnNjb2RlLXJlbW90ZQ%3D%3D?line=2) fcu = "../libraries/ashrae/guideline36/4.12-fan-coil-unit.ttl"
----> [5](vscode-notebook-cell://wsl%2Bubuntu-22.04/home/ubuntu22/BuildingMOTIF/notebooks/shape-to-template.ipynb#W4sdnNjb2RlLXJlbW90ZQ%3D%3D?line=4) lib = Library.load(ontology_graph=chw)

File [~/BuildingMOTIF/buildingmotif/dataclasses/library.py:183](https://vscode-remote+wsl-002bubuntu-002d22-002e04.vscode-resource.vscode-cdn.net/home/ubuntu22/BuildingMOTIF/notebooks/~/BuildingMOTIF/buildingmotif/dataclasses/library.py:183), in Library.load(cls, db_id, ontology_graph, directory, name, overwrite)
    179         ontology_graph = rdflib.Graph()
    180         ontology_graph.parse(
    181             ontology_graph_path, format=guess_format(ontology_graph_path)
    182         )
--> 183     return cls._load_from_ontology(ontology_graph, overwrite=overwrite)
    184 elif directory is not None:
    185     if resource_exists("buildingmotif.libraries", directory):

File [~/BuildingMOTIF/buildingmotif/dataclasses/library.py:275](https://vscode-remote+wsl-002bubuntu-002d22-002e04.vscode-resource.vscode-cdn.net/home/ubuntu22/BuildingMOTIF/notebooks/~/BuildingMOTIF/buildingmotif/dataclasses/library.py:275), in Library._load_from_ontology(cls, ontology, overwrite)
    273 for candidate in candidates:
    274     assert isinstance(candidate, rdflib.URIRef)
--> 275     partial_body, deps = get_template_parts_from_shape(candidate, ontology)
    276     templ = lib.create_template(str(candidate), partial_body)
    277     dependency_cache[templ.id] = deps

File [~/BuildingMOTIF/buildingmotif/utils.py:243](https://vscode-remote+wsl-002bubuntu-002d22-002e04.vscode-resource.vscode-cdn.net/home/ubuntu22/BuildingMOTIF/notebooks/~/BuildingMOTIF/buildingmotif/utils.py:243), in get_template_parts_from_shape(shape_name, shape_graph)
    241     param = _gensym()
...
--> 455 assert isinstance(p, Node), "Predicate %s must be an rdflib term" % (p,)
    456 assert isinstance(o, Node), "Object %s must be an rdflib term" % (o,)
    457 self.__store.add((s, p, o), self, quoted=False)

AssertionError: Predicate None must be an rdflib term

[gtfierro]

@MatthewSteen regarding your comment here:

I think it would be nice to have a way to generate the YAML templates, is there a way to save to do that to save users the time to write them?

What do you think of the (now old) prototype I have in https://github.com/NREL/BuildingMOTIF/blob/develop/libraries/pointlist-test/list.yml? It uses the template "compilation" macro framework here to do rewriting of the YAML files so there is less RDF in them. Could definitely be improved, but do you think the direction is worth pursuing?

[MatthewSteen]

2. above was fixed by your comment in 265.

[gtfierro]

@MatthewSteen I figure I will look into better YAML generation in a future issue/PR, but I'm going to merge this for now