source: trunk/docs/source/imports.rst @ 2027

Last change on this file since 2027 was 2027, checked in by toby, 7 years ago

duplicate sphinx files for ReadTheDocs? trial

File size: 9.7 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
6or :class:`GSASIIIO.ImportPowderData` (which are in turn
7derived from :class:`GSASIIIO.ImportBaseclass`)
8to implement import of
9a phase, a single crystal or a powder dataset, respectively.
10Module file names (`G2phase_`, `G2pwd_` and `G2sfact_`, etc.) are used to
11determine which menu an import routine should be placed into. (N.B. this
12was an unnecessary choice; this could be done from the class used.)
13
14This list may not include all currently defined formats, since modules
15may be loaded from anywhere in the path.
16
17Writing an Import Routine
18--------------------------
19
20.. _Import_routines:
21
22
23When writing a import routine, one should create a new class derived
24from :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
25or :class:`GSASIIIO.ImportPowderData`. As described below,
26all these classes will implement
27an ``__init__()`` and a ``Reader()`` method, and most will supply a
28``ContentsValidator()`` method, too.
29See the :class:`~GSASIIIO.ImportPhase`, :class:`~GSASIIIO.ImportStructFactor`
30or :class:`~GSASIIIO.ImportPowderData` class documentation
31for details on what values each type of ``Reader()`` should set.
32
33__init__()
34~~~~~~~~~~~~~~
35 
36The class should supply a
37``__init__`` method which calls the parent ``__init__`` method and
38specifies the following parameters:
39
40  * `extensionlist`: a list of extensions that may be used for this type of file.
41  * `strictExtension`: Should be True if only files with extensions in
42    `extensionlist` are allows; False if all file types should be offered
43    in the file browser. Also if False, the import class will be
44    used on all files when "guess from format" is tried, though
45    readers with matching extensions will be tried first.
46  * `formatName`: a string to be used in the menu. Should be short.
47  * `longFormatName`: a longer string to be used to describe the format in help.
48
49Reader()
50~~~~~~~~~~~~~~
51
52The class must supply a ``Reader`` method that actually performs the
53reading. All readers must have at a minimum these arguments::
54
55    def Reader(self, filename, filepointer, ParentFrame, **unused):
56
57where the arguments have the following uses:
58
59 * `filename`: a string with the name of the file being read
60 * `filepointer`: a file object (created by :func:`open`) that accesses
61   the file and is points to the beginning of the file when Reader is
62   called.
63 * `ParentFrame`: a reference to the main GSAS-II (tree) windows, for
64   the unusual ``Reader`` routines that will create GUI windows to ask
65   questions.
66
67In addition, the following keyword parameters are defined that ``Reader``
68routines may optionally use:
69
70 * `buffer`: a dict that can be used to retain information between repeated calls of the routine
71 * `blocknum`: counts the number of times that a reader is called
72 * `usedRanIdList`: a list of previously used random Id values that can be checked to determine that a value is unique.
73
74As an example, the `buffer` dict is used for CIF reading to hold the parsed CIF file
75so that it can be reused without having to reread the file from
76scratch.
77
78Reader return values
79______________________
80
81The ``Reader`` routine should return the value of True if the file has been
82read successfully. Optionally, use `self.warnings` to indicate any
83problems.
84
85If the file cannot be read,  the ``Reader`` routine should
86return False or raise an :class:`GSASIIIO.ImportBaseclass.ImportException`
87exception. (Why either? Sometimes an exception is the easiest way to
88bail out of a called routine.) Place text in `self.errors` and/or use::
89
90     ImportException('Error message')
91
92to give the user information on what went wrong during the reading.
93
94self.warnings
95_____________________
96
97Use `self.warnings` to indicate any information
98that should be displayed to the user if the file is read successfully,
99but perhaps not completely or additional settings will need to be
100made.
101
102self.errors
103_____________________
104
105Use `self.errors` to give the user information on where and why a read
106error occurs in the file. Note that text supplied with the ``raise``
107statement will be appended to ``self.errors``.
108
109self.repeat
110_____________________
111
112Set `self.repeat` to True (the default is False) if a Reader should be
113called again to read a second block from a file. Most commonly
114(only?) used for reading multiple powder histograms from a single
115file. Variable `self.repeatcount` is used to keep track of the block
116numbers.
117
118*support routines*
119_________________________
120
121Note that the base class (:class:`GSASIIIO.ImportBaseclass`) supplies two routines,
122:meth:`~GSASIIIO.ImportBaseclass.BlockSelector` and
123:meth:`~GSASIIIO.ImportBaseclass.MultipleBlockSelector` that are useful for
124selecting amongst one or more datasets (and perhaps phases) for
125``Reader()`` routines that may encounter more than one set of information
126in a file.
127Likewise, when an operation will take some time to complete,
128use :meth:`~GSASIIIO.ImportBaseclass.ShowBusy` and
129:meth:`~GSASIIIO.ImportBaseclass.DoneBusy` to show the user
130that something is happening.
131
132
133ContentsValidator()
134~~~~~~~~~~~~~~~~~~~~
135
136Defining a ``ContentsValidator`` method is optional, but is usually a
137good idea, particularly if the file extension is not a reliable
138identifier for the file type. The intent of this routine is to take a
139superficial look at the file to see if it has the expected
140characteristics of the expected file type. For example, are there
141numbers in the expected places?
142
143This routine is passed a single argument:
144
145* `filepointer`: a file object (created by :func:`open`) that accesses
146  the file and is points to the beginning of the file when ContentsValidator is
147  called.
148
149Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
150for validating CIF files.
151
152
153ReInitialize()
154~~~~~~~~~~~~~~~~~~~~
155
156Import classes are substantiated only once and are used as needed.
157This means that if something needs to be initialized before the
158``Reader()`` will be called to read a new file, it must be coded. The
159``ReInitialize()`` method is provided for this and it is always called
160before the ``ContentsValidator`` method is called. Use care to call
161the parent class ``ReInitialize()`` method, if this is overridden.
162
163
164ContentsValidator return values
165________________________________
166
167The ``ContentsValidator`` routine should return the value of True if
168the file appears to match the type expected for the class.
169
170If the file cannot be read by this class,  the routine should
171return False. Preferably one will also place text in `self.errors` 
172to give the user information on what went wrong during the reading.
173
174Phase Import Routines
175----------------------------------------
176Phase import routines are classes derived from
177:class:`GSASIIIO.ImportPhase`
178They must be found in files named `G2phase*.py` that are in the Python path
179and the class must override the ``__init__`` method and add a ``Reader`` method.
180The distributed routines are:
181
182.. automodule:: G2phase
183    :members: 
184    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
185
186.. automodule:: G2phase_GPX
187    :members: 
188    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
189      a text file.
190
191.. automodule:: G2phase_CIF
192    :members: 
193    :synopsis: Reads phase information from a CIF
194
195Powder Data Import Routines
196---------------------------------------------
197Powder data import routines are classes derived from
198:class:`GSASIIIO.ImportPowderData`.
199They must be found in files named `G2pwd*.py` that are in the Python path
200and the class must override the ``__init__`` method and add a
201``Reader`` method.
202
203The distributed routines are:
204
205.. automodule:: G2pwd_GPX
206    :members: 
207    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
208
209.. automodule:: G2pwd_fxye
210    :members: 
211    :synopsis: Reads powder data in all of the GSAS formats
212
213.. automodule:: G2pwd_xye
214    :members: 
215    :synopsis: Reads powder data from a Topas format file
216
217.. automodule:: G2pwd_CIF
218    :members: 
219    :synopsis: Reads powder data from a CIF
220
221Single Crystal Data Import Routines
222-----------------------------------------------------
223Single crystal data import routines are classes derived from
224, :class:`GSASIIIO.ImportStructFactor`.
225They must be found in files named `G2sfact*.py` that are in the Python path
226and the class must override the ``__init__`` method and add a ``Reader`` method.
227The distributed routines are:
228
229.. automodule:: G2sfact
230    :members: 
231    :synopsis: Reads single crystal data from simple hkl files
232
233.. automodule:: G2sfact_CIF
234    :members: 
235    :synopsis: Reads single crystal data from CIF files
236
237
238Small Angle Scattering Data Import Routines
239-----------------------------------------------------
240Small angle scattering data import routines are classes derived from
241, :class:`GSASIIIO.ImportSmallAngle`.
242They must be found in files named `G2sad*.py` that are in the Python path
243and the class must override the ``__init__`` method and add a ``Reader`` method.
244The distributed routines are:
245
246.. automodule:: G2sad_xye
247    :members: 
248    :synopsis: Reads small angle scattering data from simple files
249
250Image Import Routines
251-----------------------------------------------------
252Image import routines are classes derived from
253, :class:`GSASIIIO.ImportImage`.
254They must be found in files named `G2img*.py` that are in the Python path
255and the class must override the ``__init__`` method and add a ``Reader`` method.
256The distributed routines are:
257
258.. automodule:: G2img_ADSC
259    :members: 
260
261.. automodule:: G2img_EDF
262    :members: 
263
264.. automodule:: G2img_SumG2
265    :members: 
266
267.. automodule:: G2img_GE
268    :members: 
269
270.. automodule:: G2img_MAR
271    :members: 
272
273.. automodule:: G2img_Rigaku
274    :members: 
275
276.. automodule:: G2img_1TIF
277    :members: 
278
279.. automodule:: G2img_CheMin
280    :members: 
Note: See TracBrowser for help on using the repository browser.