For Developers
==============================

NLA allows for adding custom tests to the codebase

Creating additional edge-level tests
-----------------------------------------------

Current tests are located in ``+nla/+edge/+test``. This is also where any user-created custom tests 
will need to be saved. All edge-level test objects must inherit from ``nla.edge.BaseTest``

* **Test object**

..
    commenting this out because it's broken right now. filed report on github
    .. mat:module:: edge

    .. mat:autoclass:: BaseTest

        .. mat:automethod:: run(input_struct)

        .. mat:automethod:: inputs = requiredInputs()


* **Result object**
  
  A result object must be defined for the test edge-level results. If no custom data fields are needed, then the object in ``+nla/+edge/+result/Base.m``
  may be used and this step can be skipped. If a new result is needed, a permutation result inheriting ``+nla/+edge/+result/PermBase``
  must also be created

  .. mat:module:: edge.result

  .. mat:autoclass:: Base

    .. mat:automethod:: output(net_atlas, flags, prob_label)

Creating additional network-level tests
----------------------------------------------------------

All custom created tests must be saved in ``+nla/+net/+test``; the tests present can also be used as templates. 
All network-level results must fit into the ``NetworkTestResult`` object.

Since these tests are all different with different results and statistics, there is no base test to inherit.
The only requirements are below

* Constant properties required
    ::
    
      properties (Constant)
        name = "students_t"
        display_name = "Student's T-test"
        statistics = ["t_statistic", "single_sample_t_statistic"]
        ranking_statistic = "t_statistic"
      end

  
  :name: The name of the test with no special characters (spaces, &, etc)
  :display_name: A formal name that will be used for displaying in the GUI. Any string will work
  :statistics: All statistics that will be generated by the test. No special characters
  :ranking_statistic: The statistic used for ranking and calculating *p*-values. Note: if there is a single sample version of the statistic in addition to a two-sample statistic, the GUI will automatically add "single_sample\_" during rankings for non-permuted and within network pair ranking.

* A ``run`` method
  
    ::

      result = run(obj, test_options, edge_test_results, network_atlas, permutations)


  :test_options: Also called ``input_struct`` in edge-level tests. Parameters needed to run the test.
  :edge_test_results: The output from the edge-level test.
  :network_atlas: A network atlas of the form ``nla.NetworkAtlas``
  :permutations: Boolean to determine if the test is being run with permutations (``true``) or without (``false``)
  :result: :doc:`NetworkTestResult </network_level_results>`

* ``requiredInputs`` See :ref:`Edge-level tests <requiredInputs>`