Brick OpenRefine Reconciliation API

[Philip H.]

Hello Brick Community

A while back I encountered Gabes video Making a Brick Model with OpenRefine + BrickBuilder.

The example data looks vaguely similar to the data I have. I tried a variety of operations, but unfortunately the Reconciliation API was unable to recognize any point other than command.

Since a while has passed since the video was uploaded i wondered what the current state of the Reconciliation API and BrickBuilder is. Are the projects still worked on? If yes, what is the progress? If no, why were the projects discontinued? Did problems stop the project or is there a lack of manpower?

With regards

Philip

[Gabe Fierro]

Hi Philip:

Sorry to hear that the Reconciliation API is not working very well for you. You can see the abbreviations and components that the server is aware of here: https://github.com/BrickSchema/reconciliation-api/blob/main/abbrmap.py ; you can make changes to that file and it may generalize better to the data you have. Can you share any examples of what entity labels you are attempting to classify?

I am not currently working on the ReconciliationAPI, but I have made recent changes to BrickBuilder to add features or fix bugs. Erik Paulson has been in contact with the folks developing the ReconciliationAPI specification to see if there are ways we could expand the API to make it easier to have bidirectional information flow between the user input and the reconciliation service itself. In the meantime, I am happy to accept PRs or issues on the reconciliation server repository for additional inferences, tags, patterns, etc that would improve output. We also have a tooling working group (https://brickschema.org/blog/working-groups/) that could spend some time investigating better inference mechanisms for the reconciliation server.

Best,

Gabe

--
You received this message because you are subscribed to the Google Groups "Brick User Forum (Unified Building Metadata Schema)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to brickschema...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/d25d3ebc-01ae-43ae-b5ea-2a90ccfa93efn%40googlegroups.com.

[Philip H.]

Hi Gabe

Thank you for giving me more insight into the current state of the Reconciliation API.  The link with the abbreviations gives me a better insight into how the API works. I could open an issue with an list of the keywords used in the building data I have if that would help.

Some kind of bidirectional information flow would certainly be very useful. For example something like a revision request if the confidence for a match is very low, or a way to train the API.

I know that it can be revised afterwards, but the "Create new item" button, seems to do nothing and it just looks the same like it did before reconciling.

A specific issue I noticed is that in my data there is for example AHU1. I see AHU in the abbrmap, however since the string is different because of the number, the API just says Point with 50% confidence.

When I think about it, it reminds me a bit of when I tested Plaster online, where I could train the algorithm by entering some matches manually. That would be useful, but surely a lot of effort to implement.

If you want to replicate my steps, it is the same data as on my post here : Brickify help usage and operations. I predominantly worked with the first data set. I split it by delimiters like your tutorial showed. For the first data it only recognized command. For the other two files labeled example, the service got stuck before doing anything.

Best regards

Philip

[Gabe Fierro]

HI Philip:

When you are using the Reconciliation API, make sure that you choose "PointClass" or "EquipmentClass" in the OpenRefine UI -- this option is used in the server implementation to choose which set of classes to try.

Plaster did have a nice interface for training, but it seems as though development has stopped. I'm curious if it still works? Have you tried it recently? The OpenRefine + ReconciliationAPI approach is designed to reduce the amount of code that we have to maintain so that we can reduce bit rot. Unfortunately there still is some work to do to bring this stack up to speed

Best,

Gabe

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/df9480ea-ed0c-4733-b436-2d4a328af678n%40googlegroups.com.

[Philip H.]

Hi Gabe

Thank you for the instructions. Unfortunately when I choose the Reconciliation API in OpenRefine it looks like this:

Only the "PointClass" option is available. I also tried updating the server link from GitHub.

This is what the Result looks like when running it:

Taking a look at the data, another problem seems to be that most of the entries seem to be mixed between "EquipmentClasses" and "PointClasses". For example Pu is a pump, Vlv is a valve, DP is a difference pressure sensor, Cmd is a command, Mdlt is described as "Stetige Ansteuerung" which would translate to "continuous trigger". Two of these should be parts, two should be points. I'm not entirely sure about DP, since it's a Part that measures data. I lean towards classifying it as a point though. Here's a small excerpt of what it looks like:

Another issue with my format would be that there are to many split columns. B1 would be the building, Ahu the air handling unit, Erc the energy recovery, fan ex the fan exhaust, KickFnct.OpSta the current operation mode. Can you recommend a way to better adjust the format to the Reconciliation API? Some of these classes such as the energy recovery also seem to be missing in the Ontology.

About Plaster:

A while back I tried the online platform . I first tried to upload my data but the upload always failed. It only worked with the exampledata that was provided. There however, I saw a lot of potential. It showed excerpt of the data entry by entry and I had to select the class from a search with class suggestions. It then used the inputs to map all the data and had a quite good matching rate. The same abbreviations I answered were 100%, many were about 75% and a few were 25% confidence. This was with a training of about 20 entries. I wouldn't mind training all types of abbreviations once.

Unfortunately, it's true that the project has been discontinued. The web-platform completely stopped working and I didn't try the python implementation.

If you're interested we could talk about this some more.

Best regards

Philip

[Philip H.]

Hello once more

I just noticed that the images I posted are not visible.

This is how the Reconciliation API looks for me:

This is the result after running the API:

And finally the third Image is the excerpt of how the data looks like:

I hope this helps for a better understanding of my report.

Best regards

Philip

[Erik Paulson]

Thanks for the additional images, that made it easier to follow!

I'm not quite sure why you're not getting EquipmentType as an option for types to reconcile against - the server is sending back the right types, I can use a non-OpenRefine client and it displays both PointType and EquipmentType as an option. It's possible this is a bug in OpenRefine, or it's possible that the Brick server is sending back the info in a way that's slightly wrong and OpenRefine won't display it but the other client will, so we'll have to dig into that a bit more. 

As for the actual results coming back from the API, there are a couple of confusing things happening, mostly because of limitations in the current server's matching algorithm. This is simplifying what's happening a bit, but right now, the server takes what the client sends and tries to match that against its list of known mappings.  However, the server is very limited, and doesn't do much with anything that it doesn't have any sort of mapping for - for example, when you send 'dp' to the API, the server doesn't have any mapping for 'dp', so all it does is suggest its most generic mapping - in this case 'Point', because you told OpenRefine to reconcile against 'PointType'. (If you tell OpenRefine to 'reconcile against no particular type', the API should suggest both 'Point' and 'Equipment' for a bunch of things that it doesn't have a better answer for)

(There's another minor thing that we're doing in the protocol about types that's not quite right, but OpenRefine ignores it so I won't go into it)

As far as using all of the columns, what attracted us most to OpenRefine was that it helped make it easier to group data and do different operations on different groups of rows, potentially even using different columns in each step. It's a little tricky in that sometimes you have to "think a few moves ahead" - it's very common to create temporary columns and use those new columns as intermediate data, and use different columns with different groups, before "reassembling" the whole dataset and deleting all of those temporary columns. It's also likely that you'll want to use OpenRefine as one step in the overall workflow, and going to a final step of a Brick model would involve at least one more tool or script to convert the data from OpenRefine into a Brick model.

-Erik

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/f5f5119c-a6e7-44ee-9ca4-397feea9ff84n%40googlegroups.com.

[Philip H.]

Thank you very much for your Inputs.

I used OpenRefine because Gabe showed it in his video and when using it it was very user-friendly. I started using it for other projects as well. What is that other client you use? Is it readily available and user-friendly?

The issue you mentioned with the mapping is aggravated even more by the way the data is structured. Points and equipment are mixed in the same columns. I haven't come up with a solution to that yet.

I don't think splitting it into different columns for all "Equipment" and "Point" types is achievable with reasonable effort since all abbreviations would need to be manually distinguished and programmed , which is something that gives me a headache.

Of course it would be better if there was a good way to do it, since I'll need a way to transform this unstructured data akin to the example data I manually created when building a brickify operator like I tired in my github issue.

If this would help to get it done better, then I would gladly contribute to the abbreviation-map Gabe mentioned by adding the abbreviations from my datasets.

The operator that I'm currently writing uses a manually edited sheet, but I have to start somewhere. Of course, something that could work through a bigger excel would certainly be much better.

Best regards

Philip

[Gabe Fierro]

Hi Philip:

The Brick server that is attempting the inference of types uses the W3C Reconciliation API; you can see other clients here: https://reconciliation-api.github.io/census/clients/. I am not sure which one Erik is using, but the API is documented so you should be able to develop your own if you desire.

It should be possible to have the Brick reconciliation API implementation handle both equipment types and point types in the same column, but this will take development time to do well. I developed the server with the impression that users would leverage the OpenRefine UI to separate points from equipment using heuristics specific to the particular dataset. That said, I made a small adjustment to the reconciliation API server which may help it return either Equipment or Point types (there should be a "BrickClass" option in the API now to support this -- I am having issues with my local OpenRefine install so I can't verify that the option shows up, but it seems to infer Equipment and Point types in the same column now). Either way, it would be great to have your abbreviations added to the map! Hopefully I will have some time to improve the inference algorithm soon.

Even if we have Equipment and Point classes in the same column, having them mixed in this way will complicate the creation of a Brick model later on. I find it is helpful to organize entities and types into a tabular format where the relationship between the columns is consistent. You may find it necessary to break up the spreadsheet or pointlist into several chunks of similar labels in order to facilitate this, though I suppose that is what Brickify is attempting to assist with. I saw that Shreyas self-assigned your issue yesterday so you should get a response soon.

Best,

Gabe

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/cdc84f93-b22e-4062-b6dd-ab5e5edf3717n%40googlegroups.com.

[Philip H.]

Hi Gabe

I might try to use a different client, but I probably can't develop my own.

Thank you for adjusting the reconciliation API. I tested it out right away.

The Option is now empty for me, but I ran it anyways.

I manually added a few entries above the red arrow to test other mappings.

Luckily it was only a visual error. It looks like the reconciliation is working as intended and reconciles over all Brick classes now. I should be able to use it, if I manage to add my abbreviations and group same entries into the same columns, so I can hopefully use my brickify operator to read it. I'll try that and get back to you later.

Best Regards

Philip

[Gabe Fierro]

Hi Philip:

I am also getting the visual bug where the Option pane is empty for me; I'm not quite sure why that happens despite spending ~30 min digging around in the clientside code of OpenRefine. I did make one small fix so that at least one type (generic "BrickClass") shows up in the Option pane now. I've updated the server at reconciliation.brickschema.org and the code online.

Best,

Gabe

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/d1c8650e-eb6a-4269-a7ff-079d63908d6en%40googlegroups.com.

[Philip H.]

Hi Gabe

I can confirm, the Visual Error is gone. Thank you very much for your efforts!

I downloaded the  abbrmap.py  and added quite a few abbreviations from my data set. I attached my version to this message. Since some abbreviations are built upon each other, I wasn't sure if some of the entries I made might be redundant and how the API handles these cases:

    'Ti':['time'],
    'TiEld: ['time', 'elapsed'],
    'TiMod': ['timer' , 'modus'],

In addition some might be double in slightly different writing :

    'occsched': ['occupancy', 'schedule'],
vs.

    'Sched' : [ 'schedule'],

Can it be used like this? How would I use this for reconciliation?

Of course if one or multiple of the abbreviations I added are of use to you, feel free to import them. I'd be glad to have helped a little bit.

Best Regards

Philip

[Gabe Fierro]

Hi Philip:

For editing abbrmap.py, you will want to map the abbreviations to lists of Brick tags. You can find the Brick tags associated with various classes here: https://github.com/BrickSchema/Brick/tree/master/bricksrc . The ReconciliationAPI attempts to find the Brick class with the most tags in common with what is produced from accessing the lookup table. The examples you listed in your email look fine and wouldn't be redundant with each other; as long as the lookup keys are unique, you are ok.

To use them for reconciliation, run the reconciliation API server at https://github.com/BrickSchema/reconciliation-api on a server, with your additions to abbrmap.py. Then, when you are in OpenRefine, you can add a new reconciliation endpoint that points to your local server.

Best,

Gabe

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/eeb8b0ff-dbbf-4559-9797-fc6340f18f47n%40googlegroups.com.

[Erik Paulson]

This might be a bug in OpenRefine: 

https://github.com/OpenRefine/OpenRefine/issues/4224

The TestBench reconciliation app, which is meant to be, well, a test application for the API, does show all three types as options, but there are a few warnings that Brick should fix https://reconciliation-api.github.io/testbench/ (use the 'Test Bench' tab at the top to be able to test the Brick endpoint)

-Erik

To view this discussion on the web visit https://groups.google.com/d/msgid/brickschema/87be471f-5e46-4b54-d478-6e7980cd9ea7%40berkeley.edu.