diff --git a/docs/prms/allpairs.rst b/docs/prms/allpairs.rst index 1efb7b997..48e173ea7 100644 --- a/docs/prms/allpairs.rst +++ b/docs/prms/allpairs.rst @@ -8,3 +8,17 @@ with respect to a cartesian product. All Pairs does not take any arguments. Its source code is at https://github.com/Reed-CompBio/all-pairs-shortest-paths licensed under MIT. + +Dataset Usage +------------- + +All Pairs Shortest Paths uses ``sources``, ``targets``, and edge weights. +All Pairs Shortest Paths uses edge direction information. +However, All Pairs Shortest Paths always returns an undirected subnetwork. + +Implementation Details +---------------------- + +Internally, All Pairs Shortest Paths only accepts fully undirected or directed graphs. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. diff --git a/docs/prms/bowtiebuilder.rst b/docs/prms/bowtiebuilder.rst index c86d59fcf..674d986cb 100644 --- a/docs/prms/bowtiebuilder.rst +++ b/docs/prms/bowtiebuilder.rst @@ -1,5 +1,5 @@ BowTieBuilder -========== +============= BowTieBuilder is a pathway reconstruction algorithm which constructs pathways in a 'bowtie'-like fashion, finding the intersections of shortest paths between sources and targets and using those nodes as a basis @@ -9,3 +9,15 @@ BowTieBuilder does not take in any arguments. * Repository: https://github.com/Reed-CompBio/BowTieBuilder-Algorithm * Paper: https://doi.org/10.1186/1752-0509-3-67 + +Dataset Usage +------------- + +BowTieBuilder uses ``sources``, ``targets``, edge weights, and edge direction information. + +Implementation Details +---------------------- + +BowTieBuilder's internal implementation only takes in directed interactomes. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. diff --git a/docs/prms/domino.rst b/docs/prms/domino.rst index f562cf449..f5365748e 100644 --- a/docs/prms/domino.rst +++ b/docs/prms/domino.rst @@ -9,8 +9,15 @@ DOMINO has two optional parameters: * slice_threshold: the p-value threshold for considering a slice as relevant * module_threshold: the p-value threshold for considering a putative module as final module -Wrapper Details -=============== +Dataset Usage +------------- + +DOMINO requires the `active` column to be set. DOMINO does not consider edge weights, +nor graph directionality: directed edges are treated as undirected edges, and DOMINO +returns an undirected subnetwork. + +Implementation Details +---------------------- If the input dataframe is empty or too 'small' (where no modules are found), SPRAS will instead emit an empty output file. diff --git a/docs/prms/meo.rst b/docs/prms/meo.rst index 55157174a..6a712cc45 100644 --- a/docs/prms/meo.rst +++ b/docs/prms/meo.rst @@ -12,3 +12,16 @@ MEO takes in three optional parameters: * local_search: a "Yes"/"No" parameter that enables MEO's local search functionality. See "Improving approximations with local search" in the associated paper for more information. This should almost always be yes. * rand_restarts: the number (int) of random restarts to use. + +Dataset Usage +------------- + +MEO uses ``sources``, ``targets``, and edge weights. MEO also uses +edge direction information, and the output sub-network is directed. + +Implementation Details +---------------------- + +Internally, MEO only accepts directed interactomes. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. diff --git a/docs/prms/mincostflow.rst b/docs/prms/mincostflow.rst index f519465f9..f4b7558e2 100644 --- a/docs/prms/mincostflow.rst +++ b/docs/prms/mincostflow.rst @@ -11,6 +11,19 @@ MinCostFlow takes two optional parameters: * flow: (int) the amount of flow going through the graph * capacity: the (float) max capacity for edges +Dataset Usage +------------- + +MinCostFlow uses the input's ``sources``, ``targets``, and edge weights. MinCostFlow also +edge direction information. + +Implementation Details +---------------------- + +MinCostFlow's internal implementation only accepts directed interactomes. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. + External links ++++++++++++++ diff --git a/docs/prms/oi1.rst b/docs/prms/oi1.rst index f5a55db1a..3380a64a3 100644 --- a/docs/prms/oi1.rst +++ b/docs/prms/oi1.rst @@ -24,3 +24,12 @@ OI1 takes some optional arguments: * ``all``: connect the dummy node to all nodes in the interactome (i.e. full set of nodes in graph) * ``others``: connect the dummy node to all nodes that are not terminal nodes (i.e. nodes without prizes) * ``file``: connect the dummy node to a specific list of nodes provided in a file + +Dataset Usage +------------- + +OmicsIntegrator1 prefers ``prize``s, but will take the union of ``sources`` and ``targets`` +and set their 'prize' to 1 if ``prize`` is not specified. If any ``dummy_nodes`` are specified, +these are passed to OmicsIntegrator1 and can have their behavior configured with ``dummy_mode``. + +OmicsIntegrator1 uses edge direction information. diff --git a/docs/prms/oi2.rst b/docs/prms/oi2.rst index f0c5b876b..6d034e8ec 100644 --- a/docs/prms/oi2.rst +++ b/docs/prms/oi2.rst @@ -18,3 +18,13 @@ OI2 takes a few optional arguments: * "others" = connect to all nodes except for terminals * "all" = connect to all nodes in the interactome. * seed: The random seed to use for this run. + + +Dataset Usage +------------- + +OmicsIntegrator2 prefers ``prize``s, but will take the union of ``sources`` and ``targets`` +and set their 'prize' to 1 if ``prize`` is not specified. + +OmicsIntegrator2 does not use edge direction information: all edges are treated as undirected, +and the output sub-network is undirected. diff --git a/docs/prms/pathlinker.rst b/docs/prms/pathlinker.rst index cb3e045dd..617ad6490 100644 --- a/docs/prms/pathlinker.rst +++ b/docs/prms/pathlinker.rst @@ -10,6 +10,20 @@ PathLinker takes one optional argument: * k: The number of paths to find (*k* shortest paths). +Dataset Usage +------------- + +PathLinker uses ``sources``, ``targets``, and edge weights. PathLinker +uses edge direction information. + +Implementation Details +---------------------- + +Internally, PathLinker only takes in directed graphs. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. + + External links ++++++++++++++ diff --git a/docs/prms/prms.rst b/docs/prms/prms.rst index d661e3d85..36f398ebe 100644 --- a/docs/prms/prms.rst +++ b/docs/prms/prms.rst @@ -6,6 +6,29 @@ Pathway Reconstruction Methods there are other sub-types of algorithms that have more specialized capabilities than the rest. Currently, SPRAS also supports edge orientation algorithms (e.g. MEO) and active module identifiers/disease module mining methods (e.g. DOMINO). +This is the list of SPRAS's supported pathway reconstruction methods. Each subpage comes with a description of the algorithm, +its source code and associated paper (if one exists), and its 'dataset usage,' or parts of a dataset that it will utilize when +running pathway reconstruction. Implementation details are also provided, for users wondering about any +important decisions that differentiate the SPRAS-wrapped version from the original +algorithm. + +.. _directionality: + +Directionality Details +---------------------- + +Some algorithms only accept fully undirected or fully directed interactomes as input. For input +data, SPRAS will try to preserve as much directionality information as possible. Mixed interactomes +are also accepted in SPRAS. + +SPRAS will automatically convert the input interactome to the desired directionality by the algorithm: +this can mean that, for some algorithms, interactome direction may be ignored. Other algorithms will +consider interactome directionality, whether by accepting mixed interactomes directly, +or converting undirected edges into directed edges. + +For converting undirected edges to directed edges, unless otherwise specified, undirected edges +will be converted into two directed edges pointing opposite of one another. + .. toctree:: :maxdepth: 1 :caption: All Pairs diff --git a/docs/prms/responsenet.rst b/docs/prms/responsenet.rst index ec7586d4f..d6a5f9e3e 100644 --- a/docs/prms/responsenet.rst +++ b/docs/prms/responsenet.rst @@ -9,3 +9,16 @@ https://github.com/Reed-CompBio/ResponseNet. ResponseNet takes one optional parameter: * gamma: (int) controls the size of the output graph: more gamma means more 'flow' gets passed along starting from the sources. + +Dataset Usage +------------- + +ResponseNet uses ``sources``, ``targets``, and edge weights. ResponseNet +uses edge direction information, but returns an undirected subnetwork. + +Implementation Details +---------------------- + +Internally, ResponseNet only takes in directed graphs. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. diff --git a/docs/prms/rwr.rst b/docs/prms/rwr.rst index b4873332f..f0388380a 100644 --- a/docs/prms/rwr.rst +++ b/docs/prms/rwr.rst @@ -1,5 +1,5 @@ RWR -========== +=== RWR, or random walk with restarts, is a source and target independent pathway reconstruction algorithm that performs PathRank on the input interactome, using the provided prizes. @@ -11,3 +11,20 @@ RWR takes in two parameters: * alpha: The damping factor of the internal PathRank algorithm. This is the probability that RWR randomly chooses a neighbor instead of restarting. RWR is implemented at https://github.com/reed-compbio/rwr. + +Dataset Usage +------------- + +RWR considers the union of ``sources`` and ``targets`` as the +input active nodes. Input interactome directionality is considered, and the +output subnetwork is also directed. + +Implementation Details +---------------------- + +RWR returns a ranked list of nodes: SPRAS returns the induced subgraph +from the number of nodes corresponding to the user-specified ``threshold``. + +Internally, RWR only takes in directed graphs. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `. diff --git a/docs/prms/strwr.rst b/docs/prms/strwr.rst index 48caa10be..e0c79a75a 100644 --- a/docs/prms/strwr.rst +++ b/docs/prms/strwr.rst @@ -1,7 +1,7 @@ ST_RWR -========== +====== -ST_RWR, or random walk with restarts, is a source and target dependent pathway reconstruction algorithm +ST_RWR, or source-target random walk with restarts, is a source and target dependent pathway reconstruction algorithm that performs PathRank on the input interactome, using its edge weights, prizes, sources, and targets. For a random walk with restarts implementation that does not use sources and targets, see RWR. @@ -10,3 +10,19 @@ For a random walk with restarts implementation that does not use sources and ta * alpha: The damping factor of the internal PathRank algorithm. This is the probability that RWR randomly chooses a neighbor instead of restarting. ST_RWR is implemented at https://github.com/reed-compbio/rwr. + +Dataset Usage +------------- + +ST_RWR considers ``sources`` and ``targets``. ST_RWR considers interactome directionality, +and the output subnetwork is also directed. + +Implementation Details +---------------------- + +ST_RWR returns a ranked list of nodes: SPRAS returns the induced subgraph +from the number of nodes corresponding to the user-specified ``threshold``. + +Internally, ST_RWR only takes in directed graphs. +SPRAS will automatically convert edges to directed edges as necessary. +For more information, see the section on :ref:`algorithm directionality `.