1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 """Module containing the BMRB user function class."""
25 __docformat__ = 'plaintext'
26
27
28 from base_class import User_fn_class, _build_doc
29 import arg_check
30 from generic_fns import bmrb, exp_info
31 from relax_errors import RelaxBoolError, RelaxIntError, RelaxNoneStrError, RelaxStrError, RelaxStrFileError
32
33
34 -class BMRB(User_fn_class):
35 """Class for interfacing with the BMRB (http://www.bmrb.wisc.edu/)."""
36
37 - def citation(self, cite_id=None, authors=None, doi=None, pubmed_id=None, full_citation=None, title=None, status='published', type='journal', journal_abbrev=None, journal_full=None, volume=None, issue=None, page_first=None, page_last=None, year=None):
38
39 if self._exec_info.intro:
40 text = self._exec_info.ps3 + "bmrb.citation("
41 text = text + "cite_id=" + repr(cite_id)
42 text = text + ", authors=" + repr(authors)
43 text = text + ", doi=" + repr(doi)
44 text = text + ", pubmed_id=" + repr(pubmed_id)
45 text = text + ", full_citation=" + repr(full_citation)
46 text = text + ", title=" + repr(title)
47 text = text + ", status=" + repr(status)
48 text = text + ", type=" + repr(type)
49 text = text + ", journal_abbrev=" + repr(journal_abbrev)
50 text = text + ", journal_full=" + repr(journal_full)
51 text = text + ", volume=" + repr(volume)
52 text = text + ", issue=" + repr(issue)
53 text = text + ", page_first=" + repr(page_first)
54 text = text + ", page_last=" + repr(page_last)
55 text = text + ", year=" + repr(year) + ")"
56 print(text)
57
58
59 arg_check.is_str(cite_id, 'citation ID string')
60 arg_check.is_str_list(authors, 'authors', list_of_lists=True)
61 arg_check.is_str(doi, 'DOI number', can_be_none=True)
62 arg_check.is_str(pubmed_id, 'Pubmed ID number', can_be_none=True)
63 arg_check.is_str(full_citation, 'full citation')
64 arg_check.is_str(title, 'title')
65 arg_check.is_str(status, 'status')
66 arg_check.is_str(type, 'type')
67 arg_check.is_str(journal_abbrev, 'journal abbreviation', can_be_none=True)
68 arg_check.is_str(journal_full, 'full journal name', can_be_none=True)
69 arg_check.is_int(volume, 'volume', can_be_none=True)
70 arg_check.is_int(issue, 'issue', can_be_none=True)
71 arg_check.is_int(page_first, 'first page number', can_be_none=True)
72 arg_check.is_int(page_last, 'last page number', can_be_none=True)
73 arg_check.is_int(year, 'publication year')
74
75
76 exp_info.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)
77
78
79 citation._doc_title = "Specify a citation to be added the BMRB data file."
80 citation._doc_title_short = "Add a citation."
81 citation._doc_args = [
82 ["cite_id", "The citation ID string."],
83 ["authors", "The list of authors. Each author element is a list of four elements (the first name, last name, first initial, and middle initials)."],
84 ["doi", "The DOI number, e.g. '10.1000/182'."],
85 ["pubmed_id", "The identification code assigned to the publication by PubMed."],
86 ["full_citation", "The full citation as given in a reference list."],
87 ["title", "The title of the publication."],
88 ["status", "The publication status."],
89 ["type", "The type of publication."],
90 ["journal_abbrev", "The standard journal abbreviation."],
91 ["journal_full", "The full journal name."],
92 ["volume", "The volume number."],
93 ["issue", "The issue number."],
94 ["page_first", "The first page number."],
95 ["page_last", "The last page number."],
96 ["year", "The publication year."]
97 ]
98 citation._doc_desc = """
99 The full_citation should be 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.
100
101 The journal status can only be one of:
102
103 "preparation",
104 "in press",
105 "published",
106 "retracted",
107 "submitted".
108
109 The citation type can only be one of:
110
111 "abstract",
112 "BMRB only",
113 "book",
114 "book chapter",
115 "internet",
116 "journal",
117 "personal communication",
118 "thesis".
119
120 The standard journal abbreviation is that 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.
121 """
122 citation._doc_examples = """
123 To add the citation "d'Auvergne E. J., Gooley P. R. (2007). Set theory formulation of the
124 model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7),
125 483-494.", type:
126
127 relax> bmrb.citation(authors=[["Edward", "d'Auvergne", "E.", "J."], ["Paul", "Gooley", "P.",
128 "R."]], doi="10.1039/b702202f", pubmed_id="17579774",
129 full_citation="d'Auvergne E. J., Gooley P. R. (2007). Set theory
130 formulation of the model-free problem and the diffusion seeded
131 model-free paradigm. Mol. Biosyst., 3(7), 483-494.", title="Set theory
132 formulation of the model-free problem and the diffusion seeded
133 model-free paradigm.", status="published", type="journal",
134 journal_abbrev="Mol. Biosyst.", journal_full="Molecular Biosystems",
135 volume=3, issue=7, page_first=483, page_last=498, year=2007)
136 """
137 _build_doc(citation)
138
139
149
150
151 display._doc_title = "Display the BMRB data in NMR-STAR format."
152 display._doc_title_short = "Display the BMRB data."
153 _build_doc(display)
154
155
156 - def read(self, file=None, dir=None, version=None, sample_conditions=None):
157
158 if self._exec_info.intro:
159 text = self._exec_info.ps3 + "bmrb.read("
160 text = text + "file=" + repr(file)
161 text = text + ", dir=" + repr(dir)
162 text = text + ", version=" + repr(version)
163 text = text + ", sample_conditions=" + repr(sample_conditions) + ")"
164 print(text)
165
166
167 arg_check.is_str(file, 'file name')
168 arg_check.is_str(dir, 'directory name', can_be_none=True)
169 arg_check.is_str(version, 'NMR-STAR dictionary version', can_be_none=True)
170 arg_check.is_str(sample_conditions, 'sample conditions label', can_be_none=True)
171
172
173 bmrb.read(file=file, directory=dir, version=version, sample_conditions=sample_conditions)
174
175
176 read._doc_title = "Read BMRB files in the NMR-STAR format."
177 read._doc_title_short = "Reading of BMRB files."
178 read._doc_args = [
179 ["file", "The name of the BMRB STAR formatted file."],
180 ["dir", "The directory where the file is located."],
181 ["version", "For the reading to use the given NMR-STAR version."],
182 ["sample_conditions", "The sample conditions label in the NMR-STAR file to restrict loading to."]
183 ]
184 read._doc_desc = """
185 To search for the results file in the current working directory, set dir to None. Note that only one sample condition can be read per relax data pipe. Therefore if sample_conditions is not given and multiple conditions exist in the NMR-STAR file, a RelaxError will be raised.
186 """
187 _build_doc(read)
188
189
190 - def script(self, file='reduced', dir=None, analysis_type=None, model_selection=None, engine='relax', model_elim=False, universal_solution=False):
191
192 if self._exec_info.intro:
193 text = self._exec_info.ps3 + "bmrb.script("
194 text = text + "file=" + repr(file)
195 text = text + ", dir=" + repr(dir)
196 text = text + ", analysis_type=" + repr(analysis_type)
197 text = text + ", model_selection=" + repr(model_selection)
198 text = text + ", engine=" + repr(engine)
199 text = text + ", model_elim=" + repr(model_elim)
200 text = text + ", universal_solution=" + repr(universal_solution) + ")"
201 print(text)
202
203
204 arg_check.is_str(file, 'script file')
205 arg_check.is_str(dir, 'directory', can_be_none=True)
206 arg_check.is_str(analysis_type, 'analysis type')
207 arg_check.is_str(model_selection, 'model selection', can_be_none=True)
208 arg_check.is_str(engine, 'engine')
209 arg_check.is_bool(model_elim, 'model elimination flag')
210 arg_check.is_bool(universal_solution, 'universal solution flag')
211
212
213 exp_info.script(file=file, dir=dir, analysis_type=analysis_type, model_selection=model_selection, engine=engine, model_elim=model_elim, universal_solution=universal_solution)
214
215
216 script._doc_title = "Specify the scripts used in the analysis."
217 script._doc_title_short = "Analysis scripts used."
218 script._doc_args = [
219 ["file", "The script file name."],
220 ["dir", "The directory name."],
221 ["analysis_type", "The type of analysis performed."],
222 ["model_selection", "The model selection technique used, if relevant."],
223 ["engine", "The software engine used in the analysis."],
224 ["model_elim", "A model-free specific flag specifying if model elimination was performed."],
225 ["universal_solution", "A model-free specific flag specifying if the universal solution was sought after."]
226 ]
227 script._doc_desc = """
228 This user function allows scripts used in the analysis to be included in the BMRB deposition. The following addition information may need to be specified with the script.
229
230 The analysis_type must be set. Allowable values include all the data pipe types used in relax, ie:
231
232 'frame order': The Frame Order theories,
233 'jw': Reduced spectral density mapping,
234 'mf': Model-free analysis,
235 'N-state': N-state model of domain motions,
236 'noe': Steady state NOE calculation,
237 'relax_fit': Relaxation curve fitting,
238
239 The model_selection argument only needs to be set if the script selects between different mathematical models. This can be anything, but the following are recommended:
240
241 'AIC': Akaike's Information Criteria.
242 'AICc': Small sample size corrected AIC.
243 'BIC': Bayesian or Schwarz Information Criteria.
244 'Bootstrap': Bootstrap model selection.
245 'CV': Single-item-out cross-validation.
246 'Expect': The expected overall discrepancy (the true values of the parameters are required).
247 'Farrow': Old model-free method by Farrow et al., 1994.
248 'Palmer': Old model-free method by Mandel et al., 1995.
249 'Overall': The realised overall discrepancy (the true values of the parameters are required).
250
251 The engine is the software used in the calculation, optimisation, etc. This can be anything, but those recognised by relax (automatic program info, citations, etc. added) include:
252
253 'relax': hence relax was used for the full analysis.
254 'modelfree4': Art Palmer's Modelfree4 program was used for optimising the model-free parameter values.
255 'dasha': The Dasha program was used for optimising the model-free parameter values.
256 'curvefit': Art Palmer's curvefit program was used to determine the R1 or R2 values.
257
258 The model_elim flag is model-free specific and should be set if the methods from "d'Auvergne, E. J. and Gooley, P. R. (2006). Model-free model elimination: A new step in the model-free dynamic analysis of NMR relaxation data. J. Biomol. NMR, 35(2), 117-135." were used. This should be set to True for the full_analysis.py script.
259
260 The universal_solution flag is model-free specific and should be set if the methods from "d'Auvergne E. J., Gooley P. R. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494." were used. This should be set to True for the full_analysis.py script.
261 """
262 script._doc_examples = """
263 For BMRB deposition, to specify that the full_analysis.py script was used, type one of:
264
265 relax> bmrb.script('full_analysis.py', 'model-free', 'AIC', 'relax', True, True)
266 relax> bmrb.script(file='full_analysis.py', dir=None, analysis_type='model-free',
267 model_selection='AIC', engine='relax', model_elim=True,
268 universal_solution=True)
269 """
270 _build_doc(script)
271
272
273 - def software(self, name=None, version=None, url=None, vendor_name=None, cite_ids=None, tasks=None):
274
275 if self._exec_info.intro:
276 text = self._exec_info.ps3 + "bmrb.software("
277 text = text + "name=" + repr(name)
278 text = text + ", version=" + repr(version)
279 text = text + ", url=" + repr(url)
280 text = text + ", vendor_name=" + repr(vendor_name)
281 text = text + ", cite_ids=" + repr(cite_ids)
282 text = text + ", tasks=" + repr(tasks) + ")"
283 print(text)
284
285
286 arg_check.is_str(name, 'program name')
287 arg_check.is_str(version, 'version', can_be_none=True)
288 arg_check.is_str(url, 'url', can_be_none=True)
289 arg_check.is_str(vendor_name, 'vendor_name', can_be_none=True)
290 arg_check.is_str_list(cite_ids, 'citation ID numbers', can_be_none=True)
291 arg_check.is_str_list(tasks, 'tasks', can_be_none=True)
292
293
294 exp_info.software(name=name, version=version, url=url, vendor_name=vendor_name, cite_ids=cite_ids, tasks=tasks)
295
296
297 software._doc_title = "Specify the software used in the analysis."
298 software._doc_title_short = "Analysis software used."
299 software._doc_args = [
300 ["name", "The name of the software program utilised."],
301 ["version", "The version of the software, if applicable."],
302 ["url", "The web address of the software."],
303 ["vendor_name", "The name of the company or person behind the program."],
304 ["cite_ids", "A list of the citation ID numbers."],
305 ["tasks", "A list of all the tasks performed by the software."]
306 ]
307 software._doc_desc = """
308 This user function allows the software used in the analysis to be specified in full detail.
309
310 For the tasks list, this should be a python list of strings (eg. ['spectral processing']). Although not restricted to these, the values suggested by the BMRB are:
311
312 'chemical shift assignment',
313 'chemical shift calculation',
314 'collection',
315 'data analysis',
316 'geometry optimization',
317 'peak picking',
318 'processing',
319 'refinement',
320 'structure solution'
321 """
322 software._doc_examples = """
323 For BMRB deposition, to say that Sparky was used in the analysis, type:
324
325 relax> cite_id = bmrb.citation(authors=[['Tom', 'Goddard', 'T.', 'D.'], ['D', 'Kneller',
326 'D.', 'G.']], title=""Goddard, T. D. and Kneller, D. G., SPARKY 3, University of
327 California, San Francisco."
328 relax> bmrb.software('Sparky', version='3.110', url="http://www.cgl.ucsf.edu/home/sparky/",
329 vendor_name="Goddard, T. D.", cite_ids=[cite_id], tasks=["spectral analysis"])
330 """
331 _build_doc(software)
332
333
348
349
350 software_select._doc_title = "Select the software used in the analysis."
351 software_select._doc_title_short = "Utilised software selection."
352 software_select._doc_args = [
353 ["name", "The name of the software program utilised."],
354 ["version", "The version of the software, if applicable."]
355 ]
356 software_select._doc_desc = """
357 Rather than specifying all the information directly, this user function allows the software packaged used in the analysis to be selected by name. The programs currently supported are:
358
359 'NMRPipe' - http://spin.niddk.nih.gov/NMRPipe/
360 'Sparky' - http://www.cgl.ucsf.edu/home/sparky/
361
362 More can be added if all relevant information (program name, description, website, original citation, purpose, etc.) is emailed to relax-users@gna.org.
363
364 Note that relax is automatically added to the BMRB file.
365 """
366 software_select._doc_examples = """
367 For BMRB deposition, to say that both NMRPipe and Sparky were used prior to relax, type:
368
369 relax> bmrb.software_select('NMRPipe')
370 relax> bmrb.software_select('Sparky', version='3.113')
371 """
372 _build_doc(software_select)
373
374
387
388
389 thiol_state._doc_title = "Select the thiol state of the system."
390 thiol_state._doc_title_short = "Thiol state selection."
391 thiol_state._doc_args = [
392 ["state", "The thiol state."]
393 ]
394 thiol_state._doc_desc = """
395 The thiol state can be any text, thought the BMRB suggests the following:
396
397 'all disulfide bound',
398 'all free',
399 'all other bound',
400 'disulfide and other bound',
401 'free and disulfide bound',
402 'free and other bound',
403 'free disulfide and other bound',
404 'not available',
405 'not present',
406 'not reported',
407 'unknown'.
408
409 Alternatively the pure states 'reduced' or 'oxidised' could be specified.
410 """
411 thiol_state._doc_examples = """
412 For BMRB deposition, to say that the protein studied is in the oxidised state, tyype one of:
413
414 relax> bmrb.thiol_state('oxidised')
415 relax> bmrb.thiol_state(state='oxidised')
416 """
417 _build_doc(thiol_state)
418
419
420 - def write(self, file=None, dir='pipe_name', version=None, force=False):
421
422 if self._exec_info.intro:
423 text = self._exec_info.ps3 + "bmrb.write("
424 text = text + "file=" + repr(file)
425 text = text + ", dir=" + repr(dir)
426 text = text + ", version=" + repr(version)
427 text = text + ", force=" + repr(force) + ")"
428 print(text)
429
430
431 arg_check.is_str(file, 'file name')
432 arg_check.is_str(dir, 'directory name', can_be_none=True)
433 arg_check.is_str(version, 'NMR-STAR dictionary version', can_be_none=True)
434 arg_check.is_bool(force, 'force flag')
435
436
437 bmrb.write(file=file, directory=dir, version=version, force=force)
438
439
440 write._doc_title = "Write the results to a BMRB NMR-STAR formatted file."
441 write._doc_title = "BMRB file writing."
442 write._doc_args = [
443 ["file", "The name of the BMRB file to output results to. Optionally this can be a file object, or any object with a write() method."],
444 ["dir", "The directory name."],
445 ["version", "The NMR-STAR dictionary format version to use."],
446 ["force", "A flag which if True will cause the any pre-existing file to be overwritten."]
447 ]
448 write._doc_desc = """
449 To place the BMRB file in the current working directory, set dir to None. If dir is set to the special name 'pipe_name', then the results file will be placed into a directory with the same name as the current data pipe.
450 """
451 _build_doc(write)
452