improved docs

README.md

@@ -11,7 +11,8 @@
 
 Histogram-weighted Networks for Feature Extraction and Advanced Analysis in Neuroscience
 
-Network-level analysis of various features, esp. if it can be individualized for a single-subject is proving to be a valuable tool in many applications. Ability to extract the networks for a given subject individually on its own, would allow for feature extraction conducive to predictive modeling, unlike group-wise networks which can only be used for descriptive and explanatory purposes. This package extracts single-subject (individualized, or intrinsic) networks from node-wise data by computing the edge weights based on histogram distance between the distributions of values within each node. Individual nodes could be an ROI or a patch or a cube, or any other unit of relevance in your application. This is a great way to take advantage of the full distribution of values available within each node, relative to the simpler use of averages (or another summary statistic) to compare two nodes/ROIs within a given subject.
+Network-level analysis of various features, esp. if it can be individualized for a single-subject,
+ is proving to be a valuable tool in many applications. Ability to extract the networks for a given subject individually on its own, would allow for feature extraction conducive to predictive modeling, unlike group-wise networks which can only be used for descriptive and explanatory purposes. This package extracts single-subject (individualized, or intrinsic) networks from node-wise data by computing the edge weights based on histogram distance between the distributions of values within each node. Individual nodes could be an ROI or a patch or a cube, or any other unit of relevance in your application. This is a great way to take advantage of the full distribution of values available within each node, relative to the simpler use of averages (or another summary statistic) to compare two nodes/ROIs within a given subject.
 
 Rough scheme of computation is shown below:
 ![illustration](docs/illustration.png)

hiwenet/more_metrics.py

@@ -23,7 +23,7 @@ def diff_medians(array_one, array_two):
  Computes the difference in medians between two arrays of values.
 
  Given arrays will be flattened (to 1D array) regardless of dimension,
- and any bon-finite/NaN values will be ignored.
+ and any non-finite/NaN values will be ignored.
 
  Parameters
  ----------
@@ -54,7 +54,7 @@ def diff_medians_abs(array_one, array_two):
  Computes the absolute (symmetric) difference in medians between two arrays of values.
 
  Given arrays will be flattened (to 1D array) regardless of dimension,
- and any bon-finite/NaN values will be ignored.
+ and any non-finite/NaN values will be ignored.
 
  Parameters
  ----------
@@ -83,7 +83,7 @@ def diff_means(array_one, array_two):
  Computes the difference in means between two arrays of values.
 
  Given arrays will be flattened (to 1D array) regardless of dimension,
- and any bon-finite/NaN values will be ignored.
+ and any non-finite/NaN values will be ignored.
 
  Parameters
  ----------
@@ -114,7 +114,7 @@ def diff_means_abs(array_one, array_two):
  Computes the absolute (symmetric) difference in means between two arrays of values.
 
  Given arrays will be flattened (to 1D array) regardless of dimension,
- and any bon-finite/NaN values will be ignored.
+ and any non-finite/NaN values will be ignored.
 
  Parameters
  ----------

hiwenet/non_pairwise.py

@@ -16,15 +16,12 @@
  raise NotImplementedError('hiwenet supports only 2.7 or 3+. Upgrade to Python 3+ is recommended.')
 
 
-def relative_to_all(features, groups, edges, weight_func,
+def relative_to_all(features, groups, bin_edges, weight_func,
  use_orig_distr,
  group_ids, num_groups,
  return_networkx_graph, out_weights_path):
  """
- Computes the difference in medians between two arrays of values.
-
- Given arrays will be flattened (to 1D array) regardless of dimension,
- and any bon-finite/NaN values will be ignored.
+ Computes the given function (aka weight or distance) between histogram from each of the groups to a "grand histogram" derived from all groups.
 
  Parameters
  ----------
@@ -44,8 +41,13 @@ def relative_to_all(features, groups, edges, weight_func,
  but this could also be a list of strings of length p, in which case a tuple is returned,
  identifying which weight belongs to which pair of patches.
 
+ bin_edges : list or ndarray
+ Array of bin edges within which to compute the histogram in.
+
+ weight_func : callable
+ Function to compute the edge weight between groups/nodes.
 
- use_original_distribution : bool, optional
+ use_orig_distr : bool, optional
  When using a user-defined callable, this flag
  1) allows skipping of pre-processing (trimming outliers) and histogram construction,
  2) enables the application of arbitrary callable (user-defined) on the original distributions coming from the two groups/ROIs/nodes directly.
@@ -55,6 +57,19 @@ def relative_to_all(features, groups, edges, weight_func,
  This option is valid only when weight_method is a valid callable,
  which must take two inputs (possibly of different lengths) and return a single scalar.
 
+ group_ids : list
+ List of unique group ids to construct the nodes from (must all be present in the `groups` argument)
+
+ num_groups : int
+ Number of unique groups in the `group_ids`
+
+ return_networkx_graph : bool, optional
+ Specifies the need for a networkx graph populated with weights computed. Default: False.
+
+ out_weights_path : str, optional
+ Where to save the extracted weight matrix. If networkx output is returned, it would be saved in GraphML format.
+ Default: nothing saved unless instructed.
+
  Returns
  -------
  distance_vector : ndarray
@@ -68,7 +83,7 @@ def relative_to_all(features, groups, edges, weight_func,
  """
 
  # notice the use of all features without regard to group membership
- hist_whole = compute_histogram(features, edges, use_orig_distr)
+ hist_whole = compute_histogram(features, bin_edges, use_orig_distr)
 
  # to identify the central node capturing distribution from all roi's
  whole_node = 'whole'
@@ -82,7 +97,7 @@ def relative_to_all(features, groups, edges, weight_func,
 
  for src in range(num_groups):
  index_roi = groups == group_ids[src]
- hist_roi = compute_histogram(features[index_roi], edges, use_orig_distr)
+ hist_roi = compute_histogram(features[index_roi], bin_edges, use_orig_distr)
  edge_value = weight_func(hist_whole, hist_roi)
  if return_networkx_graph:
  graph.add_edge(group_ids[src], whole_node, weight=float(edge_value))