docs: alg usage & impl details #408
Conversation
Documentation build overview
Show files changed (20 files in total): 📝 20 modified | ➕ 0 added | ➖ 0 deleted
|
Co-authored-by: Anthony Gitter <agitter@users.noreply.github.com>
|
I based off this documentation off of the different alg |
Co-authored-by: Neha Talluri <78840540+ntalluri@users.noreply.github.com>
There was a problem hiding this comment.
I think all of the algorithms lack consistency on how the directionality is being written for the input interactome and the output subnetworks. Please update all of the algorithms in the data usage sections to include the input directionality requirements (fully directed, fully undirected, or allows for both undirected and directed edges to be in an interactome (mixed directionality). Also include what the output subnetworks directionality is. #107 This issue will have a lot of that information; otherwise the information will be in the wrappers.
I don't think we need to add in the Implementation Details part for directionality changes to the edges; this can be a whole different section in the docs in the input data and output formats that explains how the code changes the edges. If you do want to keep the implementation of the edges, please add what is happening for the input and output edges for every algorithm.
|
Who is the audience for directionality? This matters more to algorithm implementers than pathway reconstruction users, which is why I left it in implementation details. I've left a note about directionality under PRMs, and moved details about conversions inside implementation details. |
|
Directionality is important for both users and developers, but in different ways. For users, directionality affects how they interpret results and choose their inputs. It determines which interactomes can be used, how molecules are represented as interacting with one another, and what to expect from the reconstructed subnetworks. For example, in the Pathway Commons SIF format (see here), edge direction can encode whether an interaction is activating, inhibiting, or otherwise directional; this directly can impacts how users understand interactions. For developers, the responsibility lies in ensuring that each wrapped algorithm correctly handles the directionality required by its implementation for the input and output. So when someone is looking at the PRMs documentation, they should also know how the input and output directionality is being handled by an algorithm. |
|
It does absolutely impact how users interpret results, but SPRAS abstracts directionality, so it shouldn't affect how users prepare their inputs. (Does the new documentation update suffice?) |
|
I added some comments in the APSP about how things should be updated for consistency in the documentation for each of the algorithms. |
Sorry yes, not prepare, I meant choose their inputs. |
|
Hm, how about this change? |
I think it still doesn't matter how the algorithm converts undirected/directed edges, as long as it incorporates directed edges in some way? The user should put in the graph that incorporates the most information, regardless of what each individual algorithm is doing. |
|
I skimmed the discussion here and think users do want to understand how SPRAS will convert (un)directed edges for different algorithms and which of those algorithms can use them. If a user provides a full directed graph, they may want to avoid running algorithms that are going to remove the directionality from their edges. The language about what an algorithm does "internally" to contrast that with what SPRAS accepts as input and provides as output makes sense to me. |
3 participants
Work on #26.