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

Last change on this file since 2817 was 2817, checked in by vondreele, 5 years ago

major revision - move all importers to GSASIIobj & make them independent of wx so they can be used in a scripting environment.
Still to move are PhaseSelector?, and 3 BlockSelector? dialogs

File size: 12.4 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIobj.ImportPhase`, :class:`GSASIIobj.ImportStructFactor`,
6:class:`GSASIIobj.ImportPowderData`
7or :class:`GSASIIIO.ImportPowderData` (which are in turn
8derived from :class:`GSASIIobj.ImportBaseclass`)
9to implement import of
10a phase, a single crystal or a powder dataset, respectively.
11Module file names (`G2phase_`, `G2pwd_` and `G2sfact_`, etc.) are used to
12determine which menu an import routine should be placed into. (N.B. this
13was an unnecessary choice; this could be done from the class used.)
14
15This list may not include all currently defined formats, since modules
16may be loaded from anywhere in the path.
17
18Writing an Import Routine
19--------------------------
20
21.. _Import_routines:
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`,
30:class:`~GSASIIIO.ImportStructFactor`,
31:class:`~GSASIIIO.ImportPowderData`
32or :class:`~GSASIIIO.ImportImage` class documentation
33for details on what values each type of ``Reader()`` should set.
34
35__init__()
36~~~~~~~~~~~~~~
37 
38The ``__init__`` method will follow standard boilerplate:
39
40.. code-block:: python
41
42    def __init__(self):
43        super(self.__class__,self).__init__( # fancy way to self-reference
44            extensionlist=('.ext1','ext2'),
45            strictExtension=True,
46            formatName = 'example image',
47            longFormatName = 'A longer description that this is an example image format'
48            )
49
50The first line in the ``__init__`` method calls the parent class
51``__init__`` method with the following parameters:
52
53  * ``extensionlist``: a list of extensions that may be used for this type of file.
54  * ``strictExtension``: Should be True if only files with extensions in
55    ``extensionlist`` are allows; False if all file types should be offered
56    in the file browser. Also if False, the import class will be
57    used on all files when "guess from format" is tried, though
58    readers with matching extensions will be tried first.
59    It is a very good idea to supply  a :ref:`ContentsValidator <ContentsValidator>`
60    method when ``strictExtension`` is False.
61  * ``formatName``: a string to be used in the menu. Should be short.
62  * ``longFormatName``: a longer string to be used to describe the
63    format in help.
64
65Note that if an importer detects a condition which prevents its use,
66for example because a required Python package is not present, it can
67set the value of ``self.UseReader`` to False. Another possible use for
68this would be an importer that requires a network connection to a
69remote site. Setting ``self.UseReader`` to False must be done in the
70``__init__`` method and will prevent the
71importer from being used or included in the expected menu.
72
73Reader()
74~~~~~~~~~~~~~~
75
76The class must supply a ``Reader`` method that actually performs the
77reading. All readers must have at a minimum these arguments::
78
79    def Reader(self, filename, filepointer, ParentFrame, **unused):
80
81where the arguments have the following uses:
82
83 * ``filename``: a string with the name of the file being read
84 * ``filepointer``: a file object (created by :func:`open`) that accesses
85   the file and is points to the beginning of the file when Reader is
86   called.
87 * ``ParentFrame``: a reference to the main GSAS-II (tree) windows, for
88   the unusual ``Reader`` routines that will create GUI windows to ask
89   questions. The Reader should do something reasonable such as take a
90   reasonable default if ``ParentFrame`` is None, which indicates that
91   GUI should not be accessed.
92
93In addition, the following keyword parameters are defined that ``Reader``
94routines may optionally use:
95
96 * ``buffer``: a dict that can be used to retain information between repeated calls of the routine
97 * ``blocknum``: counts the number of times that a reader is called, to
98   be used with files that contain more than one set of data (e.g. GSAS
99   .gsa/.fxye files with multiple banks or image files with multiple images.)
100 * ``usedRanIdList``: a list of previously used random Id values that can be checked to determine that a value is unique.
101
102As an example, the ``buffer`` dict is used in CIF reading to hold the parsed CIF file
103so that it can be reused without having to reread the file from
104scratch.
105
106Reader return values
107______________________
108
109The ``Reader`` routine should return the value of True if the file has been
110read successfully. Optionally, use `self.warnings` to indicate any
111problems.
112
113If the file cannot be read,  the ``Reader`` routine should
114return False or raise an :class:`GSASIIIO.ImportBaseclass.ImportException`
115exception. (Why either? Sometimes an exception is the easiest way to
116bail out of a called routine.) Place text in `self.errors` and/or use::
117
118     ImportException('Error message')
119
120to give the user information on what went wrong during the reading.
121
122self.warnings
123_____________________
124
125Use `self.warnings` to indicate any information
126that should be displayed to the user if the file is read successfully,
127but perhaps not completely or additional settings will need to be
128made.
129
130self.errors
131_____________________
132
133Use `self.errors` to give the user information on where and why a read
134error occurs in the file. Note that text supplied with the ``raise``
135statement will be appended to ``self.errors``.
136
137self.repeat
138_____________________
139
140Set `self.repeat` to True (the default is False) if a Reader should be
141called again to after reading to indicate that more data may exist in
142the file to be read. This is used for reading multiple powder
143histograms or multiple images from a single file. Variable
144`self.repeatcount` is used to keep track of the block numbers.
145
146*support routines*
147_________________________
148
149Note that GSASIIIO supplies three routines,
150:meth:`~GSASIIIO.BlockSelector` 
151:meth:`~GSASIIIO.MultipleBlockSelector` and
152:meth:`~GSASIIIO.MultipleChoiceSelector` that are useful for
153selecting amongst one or more datasets (and perhaps phases) or data items for
154``Reader()`` routines that may encounter more than one set of information
155in a file.
156Likewise, when an operation will take some time to complete,
157use :meth:`~GSASIIIO.ShowBusy` and
158:meth:`~GSASIIIO.DoneBusy` to show the user that something is happening.
159
160ContentsValidator()
161~~~~~~~~~~~~~~~~~~~~
162
163.. _ContentsValidator:
164
165Defining a ``ContentsValidator`` method is optional, but is usually a
166good idea, particularly if the file extension is not a reliable
167identifier for the file type. The intent of this routine is to take a
168superficial look at the file to see if it has the expected
169characteristics of the expected file type. For example, are there
170numbers in the expected places?
171
172This routine is passed a single argument:
173
174* `filepointer`: a file object (created by :func:`open`) that accesses
175  the file and is points to the beginning of the file when ContentsValidator is
176  called.
177
178Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
179for validating CIF files.
180
181
182ReInitialize()
183~~~~~~~~~~~~~~~~~~~~
184
185Import classes are substantiated only once and are used as needed.
186This means that if something needs to be initialized before the
187``Reader()`` will be called to read a new file, it must be coded. The
188``ReInitialize()`` method is provided for this and it is always called
189before the ``ContentsValidator`` method is called. Use care to call
190the parent class ``ReInitialize()`` method, if this is overridden.
191
192
193ContentsValidator return values
194________________________________
195
196The ``ContentsValidator`` routine should return the value of True if
197the file appears to match the type expected for the class.
198
199If the file cannot be read by this class,  the routine should
200return False. Preferably one will also place text in `self.errors` 
201to give the user information on what went wrong during the reading.
202
203Phase Import Routines
204----------------------------------------
205Phase import routines are classes derived from
206:class:`GSASIIobj.ImportPhase`
207They must be found in files named `G2phase*.py` that are in the Python path
208and the class must override the ``__init__`` method and add a ``Reader`` method.
209The distributed routines are:
210
211.. automodule:: G2phase
212    :members: 
213    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
214
215.. automodule:: G2phase_GPX
216    :members: 
217    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
218      a text file.
219
220.. automodule:: G2phase_CIF
221    :members: 
222    :synopsis: Reads phase information from a CIF
223
224.. automodule:: G2phase_INS
225    :members: 
226
227
228
229Powder Data Import Routines
230---------------------------------------------
231Powder data import routines are classes derived from
232:class:`GSASIIobj.ImportPowderData`.
233They must be found in files named `G2pwd*.py` that are in the Python path
234and the class must override the ``__init__`` method and add a
235``Reader`` method.
236
237The distributed routines are:
238
239.. automodule:: G2pwd_GPX
240    :members: 
241    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
242
243.. automodule:: G2pwd_fxye
244    :members: 
245    :synopsis: Reads powder data in all of the GSAS formats
246
247.. automodule:: G2pwd_xye
248    :members: 
249    :synopsis: Reads powder data from a Topas format file
250
251.. automodule:: G2pwd_CIF
252    :members: 
253    :synopsis: Reads powder data from a CIF
254
255.. automodule:: G2pwd_BrukerRAW
256    :members: 
257    :synopsis: Reads powder data from a Brucker .raw file
258
259.. automodule:: G2pwd_FP
260    :members: 
261
262.. automodule:: G2pwd_Panalytical
263    :members: 
264
265.. automodule:: G2pwd_csv
266    :members: 
267
268.. automodule:: G2pwd_rigaku
269    :members: 
270
271
272
273Single Crystal Data Import Routines
274-----------------------------------------------------
275Single crystal data import routines are classes derived from
276, :class:`GSASIIobj.ImportStructFactor`.
277They must be found in files named `G2sfact*.py` that are in the Python path
278and the class must override the ``__init__`` method and add a ``Reader`` method.
279The distributed routines are:
280
281.. automodule:: G2sfact
282    :members: 
283    :synopsis: Reads single crystal data from simple hkl files
284
285.. automodule:: G2sfact_CIF
286    :members: 
287    :synopsis: Reads single crystal data from CIF files
288
289
290Small Angle Scattering Data Import Routines
291-----------------------------------------------------
292Small angle scattering data import routines are classes derived from
293, :class:`GSASIIobj.ImportSmallAngle`.
294They must be found in files named `G2sad*.py` that are in the Python path
295and the class must override the ``__init__`` method and add a ``Reader`` method.
296The distributed routines are:
297
298.. automodule:: G2sad_xye
299    :members: 
300    :synopsis: Reads small angle scattering data from simple files
301
302Image Import Routines
303-----------------------------------------------------
304Image import routines are classes derived from
305:class:`GSASIIIO.ImportImage`.
306See :ref:`Writing a Import Routine<Import_Routines>` for general
307information on importers and
308:ref:`the ImportImage docstring<Image_import_routines>`
309for what a reader should define.
310Image importers must be found in files named `G2img*.py` that are in the Python path
311and the class must override the ``__init__`` method and add a
312``Reader`` method.
313
314The distributed routines are:
315
316.. automodule:: G2img_ADSC
317    :members: 
318
319.. automodule:: G2img_EDF
320    :members: 
321
322.. automodule:: G2img_SumG2
323    :members: 
324
325.. automodule:: G2img_GE
326    :members: 
327
328.. automodule:: G2img_MAR
329    :members: 
330
331.. automodule:: G2img_Rigaku
332    :members: 
333
334.. automodule:: G2img_1TIF
335    :members: 
336
337.. automodule:: G2img_CheMin
338    :members: 
339
340.. automodule:: G2img_CBF
341    :members: 
342
343.. automodule:: G2img_HDF5
344    :members: 
345
346PDF Import Routines
347-----------------------------------------------------
348PDF import routines are classes derived from
349:class:`GSASIIobj.ImportPDFData`.
350See :ref:`Writing a Import Routine<Import_Routines>` for general information on importers.
351
352The distributed routines are:
353
354.. automodule:: G2pdf_gr
355    :members: 
356
357Reflectometry Import Routines
358-----------------------------------------------------
359Reflectometry import routines are classes derived from
360:class:`GSASIIobj.ImportReflectometryData`.
361See :ref:`Writing a Import Routine<Import_Routines>` for general information on importers.
362
363The distributed routines are:
364
365.. automodule:: G2rfd_xye
366    :members: 
367
368
Note: See TracBrowser for help on using the repository browser.