Provide diagrams for examples

[azaroth42]

Using the style developed and tested with new users throughout the Open Annotation / Web Annotation work. See: https://www.w3.org/TR/annotation-vocab/ (and the many iterations before that, each of which improved the style via feedback from the community)

The suggestion of rdfpuml is nice as it is automated, but the style was confusing to newcomers (e.g. the students) during the AAC project. For automated, internal review and discussion rdfpuml is great... but we can spend more time to have more attractive and easier to follow diagrams. The intent of the site is to be as clear as possible.

[workergnome]

Agreed—though it would also be nice to have an automated way to generated similar diagrams, since we're likely to need to produce many of them, and I would like to not have the need to redraw the diagrams prevent us from being willing to make changes.

[azaroth42]

Having spent 7 years drawing the same annotation diagrams over and over and over again ... having an automated way to generate them would be worth an awful lot to me! Automated placement typically does not do a good enough job for documentation, but even if it could create the boxes to then move around would be lovely.

[azaroth42]

Propose the following set of color / class alignment:

[azaroth42]

Dropped the idea into the Arches issue list: https://github.com/archesproject/arches/issues/2379

[azaroth42]

A couple of visualization possibilities:

Elipses: https://bl.ocks.org/jpurma/6dd2081cf25a5d2dfcdcab1a4868f237 Ontology: http://visualdataweb.de/webvowl/#

[VladimirAlexiev]

not have the need to redraw the diagrams prevent us from being willing to make changes.

Exactly! The biggest value of generation is that it's true to the RDF representation (there is not any hand-waving in the diagram), and saves time.

color / class alignment:

• rdfpuml can do a colored circle, but there can only be a single letter in the circle (plus any guillemeted <>). Doc: http://plantuml.com/class-diagram#Specific; example: https://github.com/duraspace/pcdm/wiki/Diagrams-with-rdfpuml
• puml can also do colored node, but rdfpuml can't yet do that. Doc: http://plantuml.com/class-diagram#SkinnedStereotypes

Automated placement typically does not do a good enough job for documentation

I agree about a complex diagram like https://github.com/linked-art/linked.art/issues/86#issuecomment-324876268: one crossing arrow and the arrows are curved splines not straight. (graphviz uses curving to make space for the arrow labels)

BTW it uses these control triples:

# a few inlines to save on nodes
aat:300054766 a puml:Inline; skos:prefLabel "exhibition (event)".
aat:300404620 a puml:Inline; skos:prefLabel "catalog number".
aat:300026096 a puml:Inline; skos:prefLabel "exhibition catalog".
<thes/title/exhibition_label> a puml:Inline.

# AttributeAssignment typically benefits from being shown as a puml Association class, but in this case I opted not
<catalog-number/assignment> a puml:NoReify.
<exhibition-label/assignment> a puml:NoReify.

# Fix relative position of 2 nodes (sort of cheating)
<catalog-number/assignment> puml:hidden-left <exhibition-label/assignment>.

# Fix the direction of some arrows
crm:P20_had_specific_purpose puml:arrow puml:up.
crm:P9i_forms_part_of        puml:arrow puml:up.

But this one is complex on purpose since it shows all possible alternatives. Eg the prev diagram in that issue is perfect. If you don't show too many nodes (10-15 is ideal), then most of the time the diagram is perfect.

but even if it could create the boxes to then move around would be lovely

puml can output SVG, and the arrows can also be useful. Can you edit SVG?

[VladimirAlexiev]

plantuml supports colors, unicode chars (http://plantuml.com/creole) and icons (http://plantuml.com/openiconic). For example

[VladimirAlexiev]

Combining colors, icons and tooltips (to show RDF rendition of JSONLD terms and vice versa). Go to this example to exercise the tooltips.

[VladimirAlexiev]

Add "scale 1.5" to make it bigger so the icons are better readable:

[azaroth42]

To take this back to the actual issue of diagrams, I think the requirements/desiderata are:

Required:

• Colored ovals for resources, with the URI slug within the oval. The color is an indication of the sort of resource, as per the comment above, but is not the only source of the information (re color blindness)
• Boxes for classes. They need to be visually distinct as they're the ontology level, not the instance level.
• Lozenges for literals. Again they need to be distinct to avoid giving the impression that they're either classes or resources.
• Arrows between shapes to establish the connections
• Labels on the arrows, from the JSON-LD context.
• Some non-terrible automated layout

Nice to Have:

• The diagram should be SVG to allow interaction, and in particular to have hovers for the labels and aat concepts, as per the embedded JSON examples
• A layout similar to a linguistic parse tree seems like the easiest -- the serialization is intentionally breadth first to make bushy shrubs, rather than tall trees. Thus the non tree connections will always be leaf to leaf, and can be curved overlapping arrows at the bottom.
• Graphical icons (if space allows, and they're distinct enough to be useful)

Pull requests that implement at least all of the required functionality are very welcome, or suggestions as to examples that could easily be adapted and added to the build process as either Python (for static images) or Javascript (for dynamic interaction).

[VladimirAlexiev]

I agree with many of the requirements, with the following notes:

• "boxes for classes, lozenges for literals" means that you want to make separate nodes for every rdf:type and literal property. This will waste a lot of space and won't go very far (slightly complex graphs will generate very complex diagrams). In contrast, rdfpuml inlines a lot: types, literals. You can also inline lookup values (eg aat:30001234 that has only a label).
• SVG is better than PNG because it's zoomable and self-contained (here's the above image as SVG. But it's not a prerequisite for tooltips: png with cmapx does the same (as you can exercise above example at plantuml site)
• rdfpuml by default goes down, and you can control directions of individual arrows (or all arrows with a given prop). So it satisfies the above req.
  • But you'll have some "non-horizontal" connections (eg A-B-C and A-C) and if you use inverses, some backward connections too. It's important to be able to control direction for such cases
• rdfpuml uses Perl and plantuml uses Java, producing png+cmapx or svg. Is this ok for deployment?

[VladimirAlexiev]

Nice to have

• collect several parallel props in one arrow
• arrow direction control
• arrowhead (eg symmetric props should have bidirectional or no arrow)
• arrow linetype and color

[azaroth42]

means that you want to make separate nodes for every rdf:type and literal property

Yes, that's by design. The UML version makes it very hard to understand that these are all just relationships in a graph.

SVG is better than PNG because it's zoomable and self-contained ... But it's not a prerequisite for tooltips

Agreed, though SVG would be better in general.

Several parallel properties as one arrow

I don't think we ever have this.

Arrow direction

Seems like a requirement for arrows at all that we have control over the direction :) Maybe I'm missing the point?

0 or 2 arrowheads

I don't think we ever have this.

Arrow styling

Agreed, optional extra.

[VladimirAlexiev]

you want to make separate nodes for every rdf:type and literal property. This will waste a lot of space and won't go very far Yes, that's by design. The UML version makes it very hard to understand ...

Such understanding is learned easily. The tradeoff to be unable to render any modestly complex situation is worse. And many piecemeal diagrams are often harder to understand than one bigger diagram. @workergnome What do you think?

requirement for arrows at all that we have control over the direction :) Maybe I'm missing the point?

As you required, and by default, arrows go down. But in some case you may want them to go left/right, or even up (if you have a cycle).

[mdlincoln]

Sample size of 1 here: I appreciate having types and literal properties displayed as separate nodes. I understand the concept of inlining that information in UML, but I find that density very difficult to parse.

[azaroth42]

Sample size of hundreds agree with @mdlincoln. Please stop wasting everyone's time, Vlad.

[VladimirAlexiev]

I'm sure you've done a proper survey before claiming that. OK, I see my help is not welcome here, so I'll go back to paid work. (A lot of the paid modeling work I do is with these diagrams).

[azaroth42]

Yes, we tested with all of the various iterations of diagrams in many groups, of different sizes and types of people, and when Open Annotation and the Annotation Ontology groups merged for the OA Community Group, we took the best parts of each, to then re-test over the following years. We never did a survey or automated A/B testing ... but the feedback and discussions were extensive.

So it's not that help is not welcome, but constantly insisting on the use of your own tool is not very helpful. No offense intended, just trying to move the discussion forwards rather than constantly circling.

[workergnome]

https://twitter.com/aboutgeo/status/903537886594813952 is also worth looking at in this context.

[VladimirAlexiev]

@azaroth42 I'm insisting on the more reasonable approach of representing data models. Please redraw this model in your style, and let's see what comes out:

@workergnome This is from the upcoming book "Validating RDF" that I'm reviewing and that I described in our chat the other day. Cheers!

[azaroth42]

That's a model, not an example with instance level data. And we would never generate a single example which was that complex. So no, I won't waste my time further beyond this reply.

[azaroth42]

Latest version of Omnigraffle Pro is scriptable with javascript. I'll explore as an interim solution if we can auto-generate static example images, perhaps even as SVG.

[azaroth42]

Confirmed at outreach and WG meeting that the lack of diagrams are a blocking point.

[atiro]

Not to get into a game of my favourite graphing library, but would https://mermaidjs.github.io/ work ? If cromulent could generate the graph in graphviz form for the page it would turn it into SVG on the fly. But that generating bit is probably not trivial.

[azaroth42]

Will take a look. One slight pain point is getting the nodes to be the same size rather than fluctuating a lot based on the text. Also, ellipse is a separate SVG element compared to circle, so would need some tweaking to the code to approximate the current style of diagrams. But if it does a good job for the layout, then it's at least entirely automated and might be worth spending a bit of time to add ellipses or whatever. My Omnigraffle automation would need to be run offline and uploaded, as it can't be integrated into a build workflow.

[azaroth42]

I have gotten this far with automated diagram drawing.

I'm somewhat ambivalent, but the code to generate this from JSON is straight forward.

[edgartdata]

This graph is clear and easy to read. If it is easy to generate in a automated fashion then that's even better!

[azaroth42]

Styling needs work still but here's a first attempt to integrate.

[beaudet]

Nice!

[azaroth42]

Classes are all handled, with the right (approximately) colors, fixed some bugs with special characters in strings, and when the relationship appears multiple times in the JSON, it now doesn't generate multiple links in the diagram.

Some of the diagrams get quite wide, and thus appear quite small when constrained into the width of the page. We could swap to Left to Right orientation instead of Top to Bottom, but then they get equivalently long.

Example: https://new-diagrams--linked-art.netlify.com/model/provenance/production.html#reproduction-from-an-identifiable-source

[azaroth42]

I tried left to right orientation and it's incomprehensible, as the information is so spread out up and down the page, beyond the visible window.

[beaudet]

Maybe use a IIIF server to render them in zoomable view? 😁

On Oct 15, 2019 13:48, Rob Sanderson notifications@github.com wrote:

Classes are all handled, with the right (approximately) colors, fixed some bugs with special characters in strings, and when the relationship appears multiple times in the JSON, it now doesn't generate multiple links in the diagram.

Some of the diagrams get quite wide, and thus appear quite small when constrained into the width of the page. We could swap to Left to Right orientation instead of Top to Bottom, but then they get equivalently long.

Example: https://new-diagrams--linked-art.netlify.com/model/provenance/production.html#reproduction-from-an-identifiable-source

— You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://github.com/linked-art/linked.art/issues/90?email_source=notifications&email_token=AAAS7A5DMH6H6STKYVTLX2DQOX6W3A5CNFSM4DYMXWVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBJUKFI#issuecomment-542328085, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAAS7A3HV4Y4R5WXTZ7FMG3QOX6W3ANCNFSM4DYMXWVA.