New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New commands: connectome2metric, connectomeedit #714

Open
Lestropie opened this Issue Jul 9, 2016 · 1 comment

Comments

Projects
None yet
2 participants
@Lestropie
Member

Lestropie commented Jul 9, 2016

Command that would duplicate some BCT functionality, generating scalar / node-wise measures based on connectivity matrices. Not something I'm really a fan of, but would probably be well-used. Limit to weighted undirected measures (at least for now).

Functionality could be re-used in a command such as connectomestats, which would import the subject matrices and compute the scalar metric of interest for each before performing permutation testing. (The alternative would be a command that imports subject data as a single vector file, one scalar value for each subject, then run the stats - not sure what to call such a command)

@Lestropie Lestropie added this to the Stanford Coding Sprint milestone Jul 15, 2016

@Lestropie Lestropie changed the title from New command: connectome2metric to New commands: connectome2metric, connectomeedit Aug 22, 2016

@Lestropie

This comment has been minimized.

Show comment
Hide comment
@Lestropie

Lestropie Aug 22, 2016

Member

Results of discussion regarding how this functionality should behave / be interfaced with.

Now there will be two commands: connectome2metric and connectomeedit. Hopefully the reasons will come out in the description.

connectome2metric

void usage()
{

  ARGUMENTS
  + Argument("matrix_in", "the connectome matrix file(s)").type_file_in().allow_multiple();

  OPTIONS
  + OptionGroup ("Options for selecting the metric(s) to calculate")
    + Option ("nodewise", "Only calculate the requested node-mise metrics (can specify more than one in a comma-separated list); options are: " + join (nodewise_metric_choices, ",")).type_text()
    + Option ("global",   "Only calculate the requested global metrics (can specify more than one in a comma-separated list); options are: " + join (global_metric_choices, ",")).type_text();

  + OptionGroup ("Other options for connectome2metric")
    + Option ("lut", "Import a lookup table to use when labelling rows of the -nodewise output")
      + Argument ("file").type_file_in();

}

Note that we decided on comma-separated strings for -nodewise and global, which means manually checking the validity of each string after comma-splitting, but usage should be neater.

Usage cases:

  • Don't allow -nodewise and -global to both be specified
  • Don't allow multiple input matrices and multiple node-wise metrics
  • If -nodewise specified:
    • Generate semi-pretty terminal output, that could alternatively be piped to a file and become a .csv
    • For multiple metrics, one matrix:
Node,  Metric #1,   Metric #2, ...
        1,       23.4,        56.7, ...
  • For multiple matrices, one metric:
     Node, Subject #1,  Subject #2, ...
        1,       23.4,        56.7, ...
  • For both of these, if -lut option provided, replace node indices with names in the tabular output
  • If -global specified:
    • Write each resulting scalar value to terminal in succession on single line; e.g. 23.4,56.7
    • Newline separates multiple input matrices
  • If neither -nodewise nor -global specified:
    • Pretty-printed terminal output, similar to mrinfo
    • Name of each connectome file above the printout, in case of multiple input files
    • Either:
      • Text string name & symbol of each metric, one per line, e.g. mrinfo
      • Header row w. metric symbols, then data line, e.g. mrstats
  • If multiple connectomes input:
    • If -nodewise specified, must be single metric, files form columns in resulting table printout
    • If -global specified, separate subjects between lines (commas separating metrics for each subject)
    • If neither, require large file name header similar to mrinfo

connectomeedit

Options for editing a connectome, e.g. prior to calculations in connectome2metric:

  • Zero the diagonal
  • Make the matrix symmetric (throw an error if the input data are directional; that is, corresponding entries above/below the diagonal are both non-zero and are not equal)
  • Make the matrix upper triangular
  • Remove nodes from the connectome
    • Additional option for LUT import & export (single option with two parameters), that will also remove the corresponding entries from the lookup table, ensuring that the results of any node-wise measures can be cross-referenced to a LUT. Note that the input LUT must contain a single valid entry for every integer up to the node count.
Member

Lestropie commented Aug 22, 2016

Results of discussion regarding how this functionality should behave / be interfaced with.

Now there will be two commands: connectome2metric and connectomeedit. Hopefully the reasons will come out in the description.

connectome2metric

void usage()
{

  ARGUMENTS
  + Argument("matrix_in", "the connectome matrix file(s)").type_file_in().allow_multiple();

  OPTIONS
  + OptionGroup ("Options for selecting the metric(s) to calculate")
    + Option ("nodewise", "Only calculate the requested node-mise metrics (can specify more than one in a comma-separated list); options are: " + join (nodewise_metric_choices, ",")).type_text()
    + Option ("global",   "Only calculate the requested global metrics (can specify more than one in a comma-separated list); options are: " + join (global_metric_choices, ",")).type_text();

  + OptionGroup ("Other options for connectome2metric")
    + Option ("lut", "Import a lookup table to use when labelling rows of the -nodewise output")
      + Argument ("file").type_file_in();

}

Note that we decided on comma-separated strings for -nodewise and global, which means manually checking the validity of each string after comma-splitting, but usage should be neater.

Usage cases:

  • Don't allow -nodewise and -global to both be specified
  • Don't allow multiple input matrices and multiple node-wise metrics
  • If -nodewise specified:
    • Generate semi-pretty terminal output, that could alternatively be piped to a file and become a .csv
    • For multiple metrics, one matrix:
Node,  Metric #1,   Metric #2, ...
        1,       23.4,        56.7, ...
  • For multiple matrices, one metric:
     Node, Subject #1,  Subject #2, ...
        1,       23.4,        56.7, ...
  • For both of these, if -lut option provided, replace node indices with names in the tabular output
  • If -global specified:
    • Write each resulting scalar value to terminal in succession on single line; e.g. 23.4,56.7
    • Newline separates multiple input matrices
  • If neither -nodewise nor -global specified:
    • Pretty-printed terminal output, similar to mrinfo
    • Name of each connectome file above the printout, in case of multiple input files
    • Either:
      • Text string name & symbol of each metric, one per line, e.g. mrinfo
      • Header row w. metric symbols, then data line, e.g. mrstats
  • If multiple connectomes input:
    • If -nodewise specified, must be single metric, files form columns in resulting table printout
    • If -global specified, separate subjects between lines (commas separating metrics for each subject)
    • If neither, require large file name header similar to mrinfo

connectomeedit

Options for editing a connectome, e.g. prior to calculations in connectome2metric:

  • Zero the diagonal
  • Make the matrix symmetric (throw an error if the input data are directional; that is, corresponding entries above/below the diagonal are both non-zero and are not equal)
  • Make the matrix upper triangular
  • Remove nodes from the connectome
    • Additional option for LUT import & export (single option with two parameters), that will also remove the corresponding entries from the lookup table, ensuring that the results of any node-wise measures can be cross-referenced to a LUT. Note that the input LUT must contain a single valid entry for every integer up to the node count.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment