Source Code for Module user_functions.model_selection

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2003,2008-2009,2012 Edward d'Auvergne                         # 
  4  #                                                                             # 
  5  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  6  #                                                                             # 
  7  # This program is free software: you can redistribute it and/or modify        # 
  8  # it under the terms of the GNU General Public License as published by        # 
  9  # the Free Software Foundation, either version 3 of the License, or           # 
 10  # (at your option) any later version.                                         # 
 11  #                                                                             # 
 12  # This program is distributed in the hope that it will be useful,             # 
 13  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 14  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 15  # GNU General Public License for more details.                                # 
 16  #                                                                             # 
 17  # You should have received a copy of the GNU General Public License           # 
 18  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 19  #                                                                             # 
 20  ############################################################################### 
 21   
 22  # Module docstring. 
 23  """The model_selection user function definitions.""" 
 24   
 25  # relax module imports. 
 26  from graphics import WIZARD_IMAGE_PATH 
 27  from pipe_control import model_selection, pipes 
 28  from user_functions.data import Uf_info; uf_info = Uf_info() 
 29  from user_functions.objects import Desc_container 
 30   
 31   
 32  # The model_selection user function. 
 33  uf = uf_info.add_uf('model_selection') 
 34  uf.title = "Select the best model from a set of optimised models." 
 35  uf.title_short = "Model selection." 
 36  uf.display = True 
 37  uf.add_keyarg( 
 38      name = "method", 
 39      default = "AIC", 
 40      basic_types = ["str"], 
 41      desc_short = "model selection method", 
 42      desc = "The model selection technique (see below).", 
 43      wiz_element_type = 'combo', 
 44      wiz_combo_choices = [ 
 45          "Akaike's Information Criteria", 
 46          "Small sample size corrected AIC", 
 47          "Bayesian or Schwarz Information Criteria", 
 48          "Bootstrap model selection", 
 49          "Single-item-out cross-validation", 
 50          "Expected overall discrepancy", 
 51          "Farrow et al., 1994", 
 52          "Mandel et al., 1995", 
 53          "Realised overall discrepancy" 
 54      ], 
 55      wiz_combo_data = [ 
 56          "AIC", 
 57          "AICc", 
 58          "BIC", 
 59          "Bootstrap", 
 60          "CV", 
 61          "Expect", 
 62          "Farrow", 
 63          "Palmer", 
 64          "Overall" 
 65      ], 
 66      wiz_read_only = True 
 67  ) 
 68  uf.add_keyarg( 
 69      name = "modsel_pipe", 
 70      basic_types = ["str"], 
 71      desc_short = "model selection data pipe name", 
 72      desc = "The name of the new data pipe which will be created by this user function by the copying of the selected data pipe." 
 73  ) 
 74  uf.add_keyarg( 
 75      name = "bundle", 
 76      basic_types = ["str"], 
 77      desc_short = "pipe bundle", 
 78      desc = "The optional pipe bundle is a special grouping or clustering of data pipes.  If this is specified, the newly created data pipe will be added to this bundle.", 
 79      wiz_element_type = 'combo', 
 80      wiz_combo_iter = pipes.bundle_names, 
 81      wiz_read_only = False, 
 82      can_be_none = True 
 83  ) 
 84  uf.add_keyarg( 
 85      name = "pipes", 
 86      basic_types = ["str"], 
 87      container_types = ["list"], 
 88      dim = (None,), 
 89      desc_short = "data pipes", 
 90      desc = "An array containing the names of all data pipes to include in model selection.", 
 91      wiz_element_type = 'combo_list', 
 92      wiz_combo_iter = pipes.pipe_names, 
 93      wiz_read_only = True, 
 94      can_be_none = True 
 95  ) 
 96  # Description. 
 97  uf.desc.append(Desc_container()) 
 98  uf.desc[-1].add_paragraph("The following model selection methods are supported:") 
 99  uf.desc[-1].add_item_list_element("AIC", "Akaike's Information Criteria.") 
100  uf.desc[-1].add_item_list_element("AICc", "Small sample size corrected AIC.") 
101  uf.desc[-1].add_item_list_element("BIC", "Bayesian or Schwarz Information Criteria.") 
102  uf.desc[-1].add_item_list_element("Bootstrap", "Bootstrap model selection.") 
103  uf.desc[-1].add_item_list_element("CV", "Single-item-out cross-validation.") 
104  uf.desc[-1].add_item_list_element("Expect", "The expected overall discrepancy (the true values of the parameters are required).") 
105  uf.desc[-1].add_item_list_element("Farrow", "Old model-free method by Farrow et al., 1994.") 
106  uf.desc[-1].add_item_list_element("Palmer", "Old model-free method by Mandel et al., 1995.") 
107  uf.desc[-1].add_item_list_element("Overall", "The realised overall discrepancy (the true values of the parameters are required).") 
108  uf.desc[-1].add_paragraph("For the methods 'Bootstrap', 'Expect', and 'Overall', the Monte Carlo simulations should have previously been executed with the monte_carlo.create_data method set to Bootstrapping to modify its behaviour.") 
109  uf.desc[-1].add_paragraph("If the data pipes have not been specified, then all data pipes will be used for model selection.") 
110  # Prompt examples. 
111  uf.desc.append(Desc_container("Prompt examples")) 
112  uf.desc[-1].add_paragraph("For model-free analysis, if the preset models 1 to 5 are minimised and loaded into the program, the following commands will carry out AIC model selection and to place the selected results into the 'mixed' data pipe, type one of:") 
113  uf.desc[-1].add_prompt("relax> model_selection('AIC', 'mixed')") 
114  uf.desc[-1].add_prompt("relax> model_selection(method='AIC', modsel_pipe='mixed')") 
115  uf.desc[-1].add_prompt("relax> model_selection('AIC', 'mixed', ['m1', 'm2', 'm3', 'm4', 'm5'])") 
116  uf.desc[-1].add_prompt("relax> model_selection(method='AIC', modsel_pipe='mixed', pipes=['m1', 'm2', 'm3', 'm4', 'm5'])") 
117  uf.backend = model_selection.select 
118  uf.menu_text = "m&odel_selection" 
119  uf.gui_icon = "relax.discrepancy_curve" 
120  uf.wizard_height_desc = 450 
121  uf.wizard_size = (900, 750) 
122  uf.wizard_image = WIZARD_IMAGE_PATH + 'discrepancy_curve.png' 
123