generic_fns.exp

1 ############################################################################### 2 # # 3 # Copyright (C) 2008-2012 Edward d'Auvergne # 4 # # 5 # This file is part of the program relax. # 6 # # 7 # relax 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 2 of the License, or # 10 # (at your option) any later version. # 11 # # 12 # relax 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 relax; if not, write to the Free Software # 19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # 20 # # 21 ############################################################################### 22 23 # Module docstring. 24 """Module containing functions for specifying the experimental details.""" 25 26 # relax module imports. 27 from info import Info_box 28 from data.exp_info import ExpInfo 29 from generic_fns import pipes 30 from relax_errors import RelaxError 31 from relax_io import open_read_file 32 from version import version_full 33 34

35 -class Software_store:

36 """Software storage container.""" 37

38 - def __init__(self):

39 """Initialise all variables.""" 40 41 self.name = None 42 self.authors = None 43 self.url = None 44 self.tasks = None

45 46 47 # Software data structure. 48 SOFTWARE = {} 49 50 # relax software. 51 SOFTWARE['relax'] = Software_store() 52 SOFTWARE['relax'].name = "relax" 53 SOFTWARE['relax'].authors = "The relax development team" 54 SOFTWARE['relax'].url = "http://www.nmr-relax.com" 55 SOFTWARE['relax'].tasks = ["data processing"] 56 57 # NMRPipe software and citation. 58 SOFTWARE['NMRPipe'] = Software_store() 59 SOFTWARE['NMRPipe'].name = "NMRPipe" 60 SOFTWARE['NMRPipe'].authors = "Delaglio, F., Grzesiek, S., Vuister, G. W., Zhu, G., Pfeifer, J., and Bax, A" 61 SOFTWARE['NMRPipe'].url = "http://spin.niddk.nih.gov/NMRPipe/" 62 SOFTWARE['NMRPipe'].tasks = ["processing"] 63 64 # Sparky software and citation. 65 SOFTWARE['Sparky'] = Software_store() 66 SOFTWARE['Sparky'].name = "Sparky" 67 SOFTWARE['Sparky'].authors = "Goddard, T. D. and Kneller, D. G." 68 SOFTWARE['Sparky'].ref = "Goddard, T. D. and Kneller, D. G., SPARKY 3, University of California, San Francisco." 69 SOFTWARE['Sparky'].url = "http://www.cgl.ucsf.edu/home/sparky/" 70 SOFTWARE['Sparky'].tasks = ["spectral analysis"] 71 72 # Bruker Dynamics Center software. 73 SOFTWARE['DC'] = Software_store() 74 SOFTWARE['DC'].name = "Bruker Dynamics Center" 75 SOFTWARE['DC'].authors = "Bruker BioSpin GmbH" 76 SOFTWARE['DC'].url = "http://www.bruker-biospin.com/software_nmr.html" 77 SOFTWARE['DC'].tasks = ["relaxation analysis"] 78 79

80 -def bmrb_write_citations(star):

81 """Generate the Citations saveframe records. 82 83 @param star: The NMR-STAR dictionary object. 84 @type star: NMR_STAR instance 85 """ 86 87 # Test if the current pipe exists. 88 pipes.test() 89 90 # Loop over the citations. 91 if hasattr(cdp, 'exp_info') and hasattr(cdp.exp_info, 'citations'): 92 for citations in cdp.exp_info.citations: 93 # Rearrange the author list. 94 author_given_name = [] 95 author_family_name = [] 96 author_first_init = [] 97 author_mid_init = [] 98 author_family_title = [] 99 for i in range(len(citations.authors)): 100 author_given_name.append(citations.authors[i][0]) 101 author_family_name.append(citations.authors[i][1]) 102 author_first_init.append(citations.authors[i][2]) 103 author_mid_init.append(citations.authors[i][3]) 104 author_family_title.append(None) 105 106 # Add the citation. 107 star.citations.add(citation_label=citations.cite_id, author_given_name=author_given_name, author_family_name=author_family_name, author_first_init=author_first_init, author_mid_init=author_mid_init, author_family_title=author_family_title, doi=citations.doi, pubmed_id=citations.pubmed_id, full_citation=citations.full_citation, title=citations.title, status=citations.status, type=citations.type, journal_abbrev=citations.journal_abbrev, journal_full=citations.journal_full, volume=citations.volume, issue=citations.issue, page_first=citations.page_first, page_last=citations.page_last, year=citations.year)

108 109

110 -def bmrb_write_methods(star):

111 """Generate the Software saveframe records. 112 113 @param star: The NMR-STAR dictionary object. 114 @type star: NMR_STAR instance 115 @return: A list BMRB software IDs and a list of software labels. 116 @rtype: tuple of list of int and list of str 117 """ 118 119 # Test if the current pipe exists. 120 pipes.test() 121 122 # The scripts. 123 if hasattr(cdp, 'exp_info') and hasattr(cdp.exp_info, 'scripts'): 124 for script in cdp.exp_info.scripts: 125 # Get the citation ID numbers. 126 cite_id_nums = [] 127 if script.cite_ids: 128 for cite in script.cite_ids: 129 cite_id_nums.append(cdp.exp_info.get_cite_id_num(cite)) 130 131 # The name. 132 name = script.file + " relax script" 133 134 # The method info. 135 star.method.add(name=name, details=None, cite_ids=cite_id_nums, file_name=script.file, file_text=script.text)

136 137

138 -def bmrb_write_software(star):

139 """Generate the Software saveframe records. 140 141 @param star: The NMR-STAR dictionary object. 142 @type star: NMR_STAR instance 143 @return: A list BMRB software IDs and a list of software labels. 144 @rtype: tuple of list of int and list of str 145 """ 146 147 # Test if the current pipe exists. 148 pipes.test() 149 150 # Loop over the software. 151 software_ids = [] 152 software_labels = [] 153 if hasattr(cdp, 'exp_info') and hasattr(cdp.exp_info, 'software'): 154 for software in cdp.exp_info.software: 155 # Get the citation ID numbers. 156 cite_id_nums = [] 157 for cite in software.cite_ids: 158 cite_id_nums.append(cdp.exp_info.get_cite_id_num(cite)) 159 160 # The program info. 161 id = star.software.add(name=software.name, version=software.version, vendor_name=software.vendor_name, vendor_eaddress=software.url, task=software.tasks, cite_ids=cite_id_nums) 162 163 # Append the software info. 164 software_ids.append(id) 165 software_labels.append(software.name) 166 167 # relax cannot be the only program used! 168 else: 169 raise RelaxError("relax cannot be the only program used in the analysis - spectral analysis programs, etc. must also have been used. Please use the relevant BMRB user functions to specify these.") 170 171 # Return the software info. 172 return software_ids, software_labels

173 174

175 -def citation(cite_id=None, authors=None, doi=None, pubmed_id=None, full_citation=None, title=None, status=None, type=None, journal_abbrev=None, journal_full=None, volume=None, issue=None, page_first=None, page_last=None, year=None):

176 """Store a citation. 177 178 @keyword cite_id: The citation ID string. 179 @type cite_id: str 180 @keyword authors: The list of authors. Each author element is a list of four elements: the first name, last name, first initial, and middle initials. 181 @type authors: list of lists of str 182 @keyword doi: The DOI number, e.g. "10.1000/182". 183 @type doi: None or str 184 @keyword pubmed_id: The identification code assigned to the publication by PubMed. 185 @type pubmed_id: None or int 186 @keyword full_citation: A full citation in a format similar to that used in a journal article by either cutting and pasting from another document or by typing. Please include author names, title, journal, page numbers, and year or equivalent information for the type of publication given. 187 @type full_citation: str 188 @keyword title: The title of the publication. 189 @type title: str 190 @keyword status: The publication status. Can be one of in "preparation", "in press", "published", "retracted", or "submitted". 191 @type status: str 192 @keyword type: The publication type. Can be one of "abstract", "BMRB only", "book", "book chapter", "internet", "journal", "personal communication", or "thesis". 193 @type type: str 194 @keyword journal_abbrev: A standard journal abbreviation as defined by the Chemical Abstract Services for the journal where the data are or will be published. If the data in the deposition are related to a J. Biomol. NMR paper, the value must be 'J. Biomol. NMR' to alert the BMRB annotators so that the deposition is properly processed. If the depositor truly does not know the journal, a value of 'not known' or 'na' is acceptable. 195 @type journal_abbrev: str 196 @keyword journal_full: The full journal name. 197 @type journal_full: str 198 @keyword volume: The volume number. 199 @type volume: int 200 @keyword issue: The issue number. 201 @type issue: int 202 @keyword page_first: The first page number. 203 @type page_first: int 204 @keyword page_last: The last page number. 205 @type page_last: int 206 @keyword year: The publication year. 207 @type year: int 208 """ 209 210 # Test if the current pipe exists. 211 pipes.test() 212 213 # Set up the experimental info data container, if needed. 214 if not hasattr(cdp, 'exp_info'): 215 cdp.exp_info = ExpInfo() 216 217 # Place the data in the container. 218 cdp.exp_info.add_citation(cite_id=cite_id, authors=authors, doi=doi, pubmed_id=pubmed_id, full_citation=full_citation, title=title, status=status, type=type, journal_abbrev=journal_abbrev, journal_full=journal_full, volume=volume, issue=issue, page_first=page_first, page_last=page_last, year=year)

219 220

221 -def script(file=None, dir=None, analysis_type=None, model_selection=None, engine=None, model_elim=False, universal_solution=False):

222 """Specify the scripts used in the analysis. 223 224 @keyword file: The name of the file to open. 225 @type file: str 226 @keyword dir: The directory containing the file (defaults to the current directory if None). 227 @type dir: None or str 228 @keyword analysis_type: The type of analysis performed. 229 @type analysis_type: str 230 @keyword model_selection: The model selection technique used, if relevant. 231 @type model_selection: None or str 232 @keyword engine: The software engine used in the analysis. 233 @type engine: str 234 @keyword model_elim: A model-free specific flag specifying if model elimination was performed. 235 @type model_elim: bool 236 @keyword universal_solution: A model-free specific flag specifying if the universal solution was sought after. 237 @type universal_solution: bool 238 """ 239 240 # Test if the current pipe exists. 241 pipes.test() 242 243 # Check. 244 allowed = ['frame order', 245 'jw', 246 'mf', 247 'N-state', 248 'noe', 249 'relax_fit' 250 ] 251 if analysis_type not in allowed: 252 raise RelaxError("The analysis type '%s' should be one of %s." % (analysis_type, allowed)) 253 254 # Set up the experimental info data container, if needed. 255 if not hasattr(cdp, 'exp_info'): 256 cdp.exp_info = ExpInfo() 257 258 # Extract the text. 259 f = open_read_file(file, dir) 260 text = f.read() 261 f.close() 262 263 # Init the citation structures. 264 cite_id = [] 265 cite_key = [] 266 267 # Model selection. 268 if model_selection in ['AIC', 'AICc', 'BIC', 'Bootstrap', 'CV', 'Expect', 'Overall']: 269 cite_id.append('model-free model selection') 270 cite_key.append('dAuvergneGooley03') 271 272 # Model-free model elimination. 273 if model_elim: 274 cite_id.append('model-free model elimination') 275 cite_key.append('dAuvergneGooley06') 276 277 # Universal solution citation. 278 if universal_solution: 279 cite_id.append('model-free set theory') 280 cite_key.append('dAuvergneGooley07') 281 282 # Get the info box. 283 info = Info_box() 284 285 # Loop over all citations. 286 for id, key in zip(cite_id, cite_key): 287 # Alias the bib entry. 288 bib = info.bib[key] 289 290 # Add the citation. 291 cdp.exp_info.add_citation(cite_id=id, authors=bib.author2, doi=bib.doi, pubmed_id=bib.pubmed_id, full_citation=bib.cite_short(doi=False, url=False), title=bib.title, status=bib.status, type=bib.type, journal_abbrev=bib.journal, journal_full=bib.journal_full, volume=bib.volume, page_first=bib.page_first, page_last=bib.page_last, year=bib.year) 292 293 # Place the data in the container. 294 cdp.exp_info.setup_script(file=file, dir=dir, text=text, cite_ids=cite_id, analysis_type=analysis_type, model_selection=model_selection, engine=engine, model_elim=model_elim, universal_solution=universal_solution)

295 296

297 -def software(name=None, version=None, url=None, vendor_name=None, cite_ids=None, tasks=None):

298 """Select by name the software used in the analysis. 299 300 @param name: The name of the software program. 301 @type name: str 302 @keyword version: The program version. 303 @type version: None or str 304 @keyword url: The program's URL. 305 @type url: None or str 306 @keyword vendor_name: The name of the company or person behind the program. 307 @type vendor_name: str 308 @keyword cite_ids: The citation ID numbers. 309 @type cite_ids: None or str 310 @keyword tasks: The tasks performed by the program. 311 @type tasks: list of str 312 """ 313 314 # Test if the current pipe exists. 315 pipes.test() 316 317 # Set up the experimental info data container, if needed. 318 if not hasattr(cdp, 'exp_info'): 319 cdp.exp_info = ExpInfo() 320 321 # Place the data in the container. 322 cdp.exp_info.software_setup(name=name, version=version, url=url, vendor_name=vendor_name, cite_ids=cite_ids, tasks=tasks)

323 324

325 -def software_select(name, version=None):

326 """Select by name the software used in the analysis. 327 328 @param name: The name of the software program. 329 @type name: str 330 @keyword version: The program version. 331 @type version: None or str 332 """ 333 334 # Test if the current pipe exists. 335 pipes.test() 336 337 # Unknown program. 338 if name not in ['relax', 'NMRPipe', 'Sparky', 'Bruker DC']: 339 raise RelaxError("The software '%s' is unknown. Please use the user function for manually specifying software details instead." % name) 340 341 # Set up the experimental info data container, if needed. 342 if not hasattr(cdp, 'exp_info'): 343 cdp.exp_info = ExpInfo() 344 345 # Init. 346 cite_ids = [] 347 keys = [] 348 software_keys = [] 349 versions = [] 350 351 # relax. 352 if name == 'relax': 353 # The info. 354 cite_ids.append(['relax_ref1', 'relax_ref2']) 355 keys.append(['dAuvergneGooley08a', 'dAuvergneGooley08b']) 356 software_keys.append('relax') 357 versions.append(version_full()) 358 359 # NMRPipe. 360 elif name == 'NMRPipe': 361 # The info. 362 cite_ids.append(['nmrpipe_ref']) 363 keys.append(['Delaglio95']) 364 software_keys.append('NMRPipe') 365 versions.append(version) 366 367 # Sparky. 368 elif name == 'Sparky': 369 # Check if the version information has been supplied. 370 if not version: 371 raise RelaxError("The Sparky version number has not been supplied.") 372 373 # The info. 374 cite_ids.append(['sparky_ref']) 375 keys.append(['GoddardKneller']) 376 software_keys.append('Sparky') 377 versions.append(version) 378 379 # Bruker Dynamics Center. 380 elif name == 'Bruker DC': 381 # The info. 382 software_keys.append('DC') 383 versions.append(version) 384 385 # Get the info box. 386 info = Info_box() 387 388 # Loop over the citations. 389 for i in range(len(cite_ids)): 390 for j in range(len(cite_ids[i])): 391 # Alias the bib entry. 392 bib = info.bib[keys[i][j]] 393 394 # Add the citations. 395 cdp.exp_info.add_citation(cite_id=cite_ids[i][j], authors=bib.author2, doi=bib.doi, pubmed_id=bib.pubmed_id, full_citation=bib.cite_short(doi=False, url=False), title=bib.title, status=bib.status, type=bib.type, journal_abbrev=bib.journal, journal_full=bib.journal_full, volume=bib.volume, issue=bib.number, page_first=bib.page_first, page_last=bib.page_last, year=bib.year) 396 397 # Add the software info. 398 cdp.exp_info.software_setup(name=SOFTWARE[software_keys[i]].name, version=versions[i], vendor_name=SOFTWARE[software_keys[i]].authors, url=SOFTWARE[software_keys[i]].url, cite_ids=cite_ids, tasks=SOFTWARE[software_keys[i]].tasks)

399 400

401 -def thiol_state(state=None):

402 """Set the thiol state of the system. 403 404 @keyword state: The thiol state of the molecule. 405 @type state: str 406 """ 407 408 # Test if the current pipe exists. 409 pipes.test() 410 411 # Set up the experimental info data container, if needed. 412 if not hasattr(cdp, 'exp_info'): 413 cdp.exp_info = ExpInfo() 414 415 # Place the data in the container. 416 cdp.exp_info.setup_thiol(state=state)

417

Source Code for Module generic_fns.exp_info