Citation and supports in NiceCXNetwork

[bgyori]

I am trying to build networks using the NiceCXNetwork class and have run into some questions/issues. If I understand correctly, to assign a citation as support for an edge, I would do the following:

• Call add_citation to obtain a data structure representing a citation for the given paper
• Call add_support to obtain a data structure representing evidence text and the associated citation
• Call add_edge_supports to assign the given support data structure to the given edge.

The first issue is that these methods are not documented, so I'm looking at the code directly to understand how to use them.

The second thing I'm confused about is that add_citation and add_support take an id as their first argument. This implies that I, as the user, would need to keep track of existing element IDs and then have the ability to generate a new unique ID for these elements. It would be much easier if NiceCXNetwork allowed me to create these elements without having to specify an ID up front, rather, figure out what ID to generate for them internally, and then return the generated ID. This behavior would be consistent with other methods like create_node which generate a new element ID internally and then return it.

[coleslaw481]

Hi, Sorry about the current state of this code base. We are working on making it better.

For documentation you can now visit the up to date and improved documentation here:

https://ndex2.readthedocs.io/en/latest/

I'm not sure about the history of the undocumented methods add_citation, add_support, and add_edge_supports What I did hear about this code base is undocumented methods are ones not designed for public consumption. I will find out from my boss if they should be properly documented and supported or if we should deprecate them and let them fade away at some point. For now I would avoid those methods.

Really want you want to do is add some attributes to edges and that can be done with:

NiceCXNetwork.set_edge_attribute()

For citations just set the attribute name to citation and set the value to list of your citations (as strings). If you want those links to be clickable (assuming they are pubmed ids) just prefix the id values with pubmed:

Example (assuming mynet is your NiceCxNetwork object and edge_id is the id of the edge as int):

mynet.set_edge_attribute(edge_id, 'citation', ['pubmed:123', 'pubmed:4'], type='list_of_string')

For the above link to work you'll need to add a special network attribute named @context to your network just once. This @context is basically a mapping of prefixes to URL links in a python dict() (which is converted to a string via json.dumps()) This network attribute can be set via the NiceCXNetwork.set_network_attribute() method like so:

Example (assuming mynet is your NiceCxNetwork object):

# below assumes import json was set at top of file with this call

mycontext = {'pubmed': 'http://identifiers.org/pubmed/'}
mynet.set_network_attribute('@context', json.dumps(mycontext))

For any node/edge attribute with pubmed: NDEx website will make those links clickable using the url set via the @context network attribute. Multiple prefixes can be defined in the dict() which is set above in the mycontext variable.

hope this helps,

chris

[bgyori]

Thanks, that's really helpful! I'll look into implementing it with set_network_attribute. One convention for marking methods as ones that the user is not intended to call directly is to prefix the name with underscore, e.g., _add_citation.

[coleslaw481]

I agree, adding underscores is the convention I follow as well. Now it is just a matter of getting this codebase to follow that convention. I'm going to close this ticket. If you have other issues/problems please feel free to re-open or create a new ticket.

chris