New methods for cyjs use cases

[AlexanderPico]

Re: Barry's work with Novartis use case: saving and recalling networks and styles as JSON in a database.

• getVisualStyleJSON(style.name=NULL, css=FALSE, base.url=.defaultBaseUrl)

  • (default) GET /v1/styles/{name} – Produced the JSON that CytoscapeJS accepts and that CyREST accepts via POST /v1/styles … this is key
  • (css=TRUE) GET /v1/styles/{name}.json – Produced the CSS … we get it for free, and it’s useful to CytoscapeJS
  • Compatibiltle with createVisualStyle
  • Documentation should contrast with exportVisualStyles, which supports saving a style in default JSON format to file.

• createVisualStyle - https://github.com/cytoscape/RCy3/blob/master/R/Styles.R#L81

  • No changes needed. This method should already be able to take "defaults" and "mappings" as subsets from getVisualStyle return. Add test for this usage.

• createNetworkFromCytoscapejs(cytoscapejs, title=NULL, collection='My CytoscapeJS Network Collection', base_url=.defaultBaseUrl)

  • Add to Networks.R with other createNetworkFrom... methods
  • POST /v1/networks - can take json a body as an alternative to file or url references. Only impl as json object; leave file refs for importNetworkFromFile. Also leave "title" blank to use info from cyjs json object; will override if provided. Set "format" to "json".
  • Documentation should contrast with importNetworkFromFile which can also create a network from JSON as a file reference.

• createCytoscapejsFromNetwork(network=NULL, base_url=.defaultBaseUrl)

  • GET /v1/networks/{networkId}/views/first - Returns network in cytoscape.js format if file param is empty
  • Compatible with createNetworkFromCytoscapejs
  • Documentation should contrast with exportNetwork

[bdemchak]

For createCytoscapejsFromNetwork, use GET /v1/networks/{networkId}/views/first so that node positions are returned. This is essential for a clean round trip.

[AlexanderPico]

@bdemchak Ok, I get it. I updated the original description accordingly for clarity.

I think the final discussion is about alternative names for getVisualStyle. See the last bullet under this method above. The alternative names are clearer and would alleviate some of the need to document contrasting methods, lack of symmetry with setVisualStyle, etc. Do you favor any of the suggested alts?

[bdemchak]

@AlexanderPico Thanks for taking the time for this ... the collaborative result is much better than I could have achieved on my own.

For getVisualStyle, the current alterego is createVisualStyle, which seems symmetric to me: 'get' vs 'create' accurately reflects what we're doing.

For the alternatives:

• getVisualStyleDetails: the "Details" doesn't appear anywhere else in the API, so I'm left wondering what's special about a function with this name
• extractVisualStyle: the "extract" word is different from "get", but from the user perspective, is a distinction without a difference. We don't use 'extract' anywhere else, so I'm left wondering what's special about a function with this name
• getVisualStyleJSON: speaks directly to the format being returned, and would be OK, but drifts from the symmetry of createVisualStyle (which doesn't have JSON in its name)

getVisualStyle doesn't seem to me to be deficient ... can you explain further why you'd choose a different name?

[AlexanderPico]

Here are my issues with getVisualStyle:

1. The false symmetry with setVisualStyle (i.e., the common getters and setters pattern). These two functions have nothing to do with each other. The set function deals with the Visual Style as a named entity. Adding "details" to the get function would help distinguish these.
2. The implied synonymy with getCurrentStyle. One might assume these return the same thing, but one is for the currently applied style while the other supports a styleName param. Again, adding "details" or using "extract" would help distinguish these.

These can be explained in the documentation, but compared to other methods, it seems to me that getVisualStyle would raise more than average confusion.

[bdemchak]

@AlexanderPico I see ... and I think I agree. Given this, would getVisualStyleAsJSON be clear enough?

[AlexanderPico]

Very clear! I'm also okay with getVisualStyleJSON for concision. IIRC, you may have suggested this method name weeks ago and I wasn't initially sold. Sorry :)

[bdemchak]

OK ... you do the honors ... I can make the change, whichever you choose. Py4cytoscape 1.4.0 is releasable at any time once we get agreement, and I get final-confirm functionality buy-in from Novartis.

[AlexanderPico]

Excellent. I've updated the original post in this issue to reflect the plan.

@yihangx Can you clone that plan as an issue in py4cy repo with python-syntax method names and params? And, of course, and input you have on the method and param names.

[yihangx]

Sure. @bdemchak I can rename these functions in py4cytoscape if you want.

[bdemchak]

@yihangx I have sent you the pre-release e-mail that I just sent to Novartis ... I think you'll find the names you need in there. Please feel free to ask questions or point out problems. Thanks.

[yihangx]

@AlexanderPico Barry implemented delete_all_visual_styles (https://github.com/cytoscape/py4cytoscape/blob/f9aa59fc756a9376747bd8f59c9a4cf92235e7d6/py4cytoscape/styles.py#L199) in py4cytoscape 1.4.0. Should we implement this method in RCy3?

[AlexanderPico]

yes, please

[yihangx]

All methods are implemented. Still need to add test cases.

[yihangx]

Test cases were added. I just forgot to close this issue.