Documentation Request: How to Control Edge Length

[machineghost]

I imagine that if you already understand Cytoscape, it's trivially easy to control the length of edges (ie. the spacing between nodes). But to someone new to the library, the documentation is very opaque, and does not provide any clear explanation on how to control edge length.

I did go through all of the demos, and there is one that involves edge length (http://js.cytoscape.org/demos/2ebdc40f1c2540de6cf0/). In fact, it even has a UI just for controlling edge length. But unfortunately I couldn't learn anything from the demo, because it relies on an edgeLengthVal parameter being passed to makeLayout ... and the term edgeLengthVal doesn't even appear in the documentation.

So as a new user I see three possibilities:

1. edgeLengthVal is part of Cola.js (which the demo was also demonstrating), and there is no way to control edge length with Cytoscape proper
2. edgeLengthVal is part of Cola.js, but there's another way to control edge length with only Cytoscape ... but the documentation for that way doesn't make it clear how to use it
3. edgeLengthVal is not part of Cola.js, it's just not documented

Cytoscape seems pretty powerful so I'm hoping it's not #1. But whether I'm supposed to use edgeLengthVal or whether I'm supposed to use some other mechanism, increased documentation would be very helpful.

[maxkfranz]

edgeLengthVal isn't a part of any API -- extension or core. It's probably just some intermediary variable used to send some actual parameter to Cola.

Edge length is inferred based on node positions, and how node positions are set is based on the used layout. Each layout has different options. Some are force-directed layouts that can set an edge length hint directly, but this will pretty much never be exact. Some more deterministic layouts have indirect options for setting edge length -- like a spacing option -- but again, this is indirect.

There is no way to directly set edge length in a general purpose, interactive graph visualisation. It's up to the developer to work this out for the sort of layout he wants to use and the sort of limitations he wants to impose on the graph (e.g. locking, infinite layout, constraints, etc.).

[machineghost]

Thanks for the explanation. However, I would argue that a better place for that explanation (than here) would be in the documentation. For instance, you said that the "how node positions are set is based on the used layout" ... but the entirety of the "breadthfirst" layout documentation is:

 The breadthfirst layout puts nodes in a hierarchy, based on a breadthfirst traversal of the graph.

Simply adding a single sentence to that documentation would greatly clarify how the library works:

In a breadthfirst layout the distance between nodes is controlled by __________.

If similar lines were added to each layout's documentation section I believe it would be a significant improvement.

[maxkfranz]

I don't own every layout. Most layouts are extensions, many of which are third party and I have no write access to those repos. A generalised note could be added to the "Layout" section, but otherwise there's not much I can do to cover all layouts.

[machineghost]

A generalised note could be added to the "Layout" section, but otherwise there's not much I can do.

Have you ever heard the quote "Don't Let the Perfect Be the Enemy of the Good"?

If you can control the documentation for X layouts, then why does it matter that you can't control the documentation of Y layouts ... why not improve the documentation of the X layouts you can control? Especially since we're only talking about a single sentence per layout.

EDIT Ok, to be fair maybe two sentences:

In a breadthfirst layout the overall distance between nodes is controlled by the `spacingFactor` option, or the `boundingBox` option if the `fit` option is set to `true`.
The distance between specific nodes is controlled by ____ (their relative weight?).

But the point is, these two simple lines would be of immense help to someone new to the library, and having them for some layouts would be better than not having them at all.

[maxkfranz]

Yes, that usually holds true. In this instance, I'm thinking of the different cases a dev comes across the docs. For example, if a dev sees text like that per layout and sees nothing mentioned in a particular third-party layout, then it's inconsistent and confusing. Even worse, if the dev only looks at the layout intro and the third party layout readme, it looks like edge length is never mentioned.

In my opinion, it's better to discuss the topic in the intro for layouts in general terms so that the dev can apply that info to any layout -- even one that he writes himself. You're right that there's value in explaining edge length, but I think it belongs in the layout intro.

[machineghost]

Well the location isn't really important: I'd appreciate improved documentation anywhere.

[maxkfranz]

I've taken an initial stab at improving the docs re. edge length in the "Notation" and "Layouts" sections. Please take a look at the commit diff and let me know what you think.

Thanks for your feedback

[maxkfranz]

Closing for now for the 2.7.9 release. Feel free to continue to comment on the issue for further improvements in later releases.

[machineghost]

Well, thanks for trying, but I really don't think the new documentation is any better. Telling people "Each layout has its own algorithm for setting the position for each node." doesn't help anyone.

Remember, the point of documentation is to inform people who don't know what you do. You know how the algorithm for each layout works. You know how to control the edge distance in each layout. But someone trying to use your library has no way of knowing that, and your latest changes don't provide them any way to learn.

[gbader]

Would you be able to suggest better wording? The best perspective on these things comes from people reading the docs for the first time and that feedback from new readers is highly valuable.

[maxkfranz]

@gbader It's generally better to create a new issue and link it to the old one for issues associated with a milestone. Otherwise, milestone changelogs become broken. I've reassigned the milestone of this issue to 2.7.10, because this particular case is just a docs issue.

[machineghost]

Would you be able to suggest better wording?

There's a real disconnect here. I'm saying "it is impossible to figure out how to control edge length by reading the documentation." The response has been "we'll update the documentation to mention that it's impossible to figure out" ... because that's what you're saying when you write "Each layout has its own algorithm for setting the position for each node" and don't actually explain what those algorithms are.

This isn't anything complex: all you need to do to fix this ticket (if you genuinely want to) is tell people how they can control edge length in the documentation. Since this evidently varies by layout, that means updating the documentation for each layout (or at least each layout whose documentation you can control) to say something like "In the breadthfirst layout, edge distance is controlled by A, B, and C".

[maxkfranz]

The algorithm of each layout is in its description -- and the details are in the options. For example, the circle layout puts the nodes in a circle and each option affects the circle and how the nodes are organised along it.

Edge length is affected by every option, because every option affects the positions of the nodes. If you're asking for an itemised list of what factors affect edge length, you need look no further than the layout options.

Have you taken a careful look at the options for the layout(s) you are interested in? Have you tried experimenting with different values for the options, especially the types of options I mentioned in the docs update?

The position of nodes A and B determines the length of edge AB. The math involved for line/curve lengths is straightforward (i.e. secondary-school/high-school level math). It's just the Pythagorean Theorem for (straight) lines proper, and quadratic Bezier curves otherwise.

Even without doing any math, you can instead tinker with the options until you get a visual approximation of the length you'd like.

[machineghost]

Have you taken a careful look at the options for the layout(s) you are interested in? Have you tried experimenting with different values for the options, especially the types of options I mentioned in the docs update?

When I started this project I reviewed several different libraries. I looked at Cytoscape, D3, Sigma, Vis.js, and Treant. Every library had an example which was close to what I wanted. However, with every library except Cytoscape, I was able to use the library's documentation to convert the example to something that looked like what I actually wanted.

Cytoscape was the only library where my nodes were really far away, and despite poring through the documentation I was unable to figure out how to move them closer together. It's not like the other libraries have a neon red sign saying "here's the magic option that does what you want!" However, with all of them I was able to read the documentation, understand the relevant arguments, and then play with those arguments until I had a graph with nodes closer together (or whatever other aspect I was trying to control; distant nodes wasn't always a problem).

Look, D3 charts involve math too. However, D3 has documentation explaining what each programming argument does. If the foo arg affects how far apart every node on the graph is, the library's documentation says as much under the definition of foo. But with Cytoscape, when I started with an example and tried to read the documentation to take the example to the next level, I couldn't because the documentation didn't tell me how even a single options impacted something as basic as node distance.

Personally, I've given up on Cytoscape, and I'm giving up on trying to convince you that you could serve your users better by explaining further what your arguments/options actually do. Let's blame the user and my insufficient understanding of geometry, ignore my experience with all those other libraries, and close this ticket.

[maxkfranz]

I think you're taking things personally. Don't. I realise that you're frustrated that you haven't got things working, but don't take things the wrong way. I'm only trying to help you.

If your needs are basic, then using something like D3 or Sigma is just fine. They're both great open source projects that fill a different niche: They work very well for simple usecases. To my knowledge, all the graph libs you listed include/are one layout each -- so that probably makes things easier for you.

Just as D3 and Sigma have a force-directed layout, Cytoscape has a built-in force-directed layout (CoSE) and several force-directed layout extensions (like Cola, which you mentioned specifically in your initial post as one that you had looked at).

As I've explained before in more detail: Force-directed layouts tend to be more straightforward w.r.t. edge length, and other layouts are more indirect. The docs have been updated already to give a intro to how and why edge length is generally affected and to point devs towards the options -- because the details are in the options.

As you pored through -- as you put it -- the documentation of these layouts, you must have noticed that those layouts have options called idealEdgeLength and edgeLength respectively. I've verified just now that those layouts create exactly the specified distance, without the nodes far away at all. If you have specific, constructive feedback on how options like these can be made clearer, I'd be interested in hearing it.

Thanks in advance

[machineghost]

I think you're taking things personally. Don't.

Rest assured, it's nothing personal. But a person can only spend so much time/energy trying to convince an open source author before they start feeling like the author would rather defend their documentation than improve it.

As I've explained before in more detail: Force-directed layouts

Let's stop right there: what is a force-directed layout? I mean, I know what one is, but as a new user of your library, how do I know? The term "force-directed" appears exactly once in the documentation, where it only refers to (not defines) them.

Similarly, nothing in the documentation says "these layouts are force directed", nor does the documentation for the layouts themselves say "This is a force directed layout". Breadth-first has a directed option, but that's just whether the tree goes up or down.

So, with your knowledge of the library, you may well be aware of commonalities between a certain set of layouts. But as a new user, I have absolutely no way of knowing that the bezier layout even is force-directed, let alone what the magic common option, shared by all force-directed layouts, controls edge length.

you must have noticed that those layouts have options called idealEdgeLength and edgeLength

I feel like you're a little out of touch with your own documentation. edgeLength is literally not mentioned on http://js.cytoscape.org/. A single layout (cose) has an idealEdgeLength. And that layout isn't bezier or breadth-first, so once again I'm left with documentation that gives me no indication of how I can possibly move my nodes closer together.

If you have specific, constructive feedback on how options like these can be made clearer

Honestly, I feel like I've been doing nothing but that throughout this thread. So allow me to simplify further, with a "unit test":

If you can grab a random person who doesn't know Cytoscape, show them the documentation page, and then ask them "how do I make nodes closer together in a Bezier layout?", and they can answer correctly, you've won.

Close the ticket, drop the mic, pop the champagne. But until then, there's nothing else I can really offer you.