Documentation Request: How to Control Edge Length

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.

[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.

[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.