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

Last change on this file since 2802 was 2802, checked in by toby, 5 years ago

updates for doc build

File size: 12.4 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`,
6:class:`GSASIIIO.ImportPowderData`
7or :class:`GSASIIIO.ImportPowderData` (which are in turn
8derived from :class:`GSASIIIO.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 the base class (:class:`GSASIIIO.ImportBaseclass`) supplies two routines,
150:meth:`~GSASIIIO.ImportBaseclass.BlockSelector` and
151:meth:`~GSASIIIO.ImportBaseclass.MultipleBlockSelector` that are useful for
152selecting amongst one or more datasets (and perhaps phases) for
153``Reader()`` routines that may encounter more than one set of information
154in a file.
155Likewise, when an operation will take some time to complete,
156use :meth:`~GSASIIIO.ImportBaseclass.ShowBusy` and
157:meth:`~GSASIIIO.ImportBaseclass.DoneBusy` to show the user
158that something is happening.
159
160
161ContentsValidator()
162~~~~~~~~~~~~~~~~~~~~
163
164.. _ContentsValidator:
165
166Defining a ``ContentsValidator`` method is optional, but is usually a
167good idea, particularly if the file extension is not a reliable
168identifier for the file type. The intent of this routine is to take a
169superficial look at the file to see if it has the expected
170characteristics of the expected file type. For example, are there
171numbers in the expected places?
172
173This routine is passed a single argument:
174
175* `filepointer`: a file object (created by :func:`open`) that accesses
176  the file and is points to the beginning of the file when ContentsValidator is
177  called.
178
179Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
180for validating CIF files.
181
182
183ReInitialize()
184~~~~~~~~~~~~~~~~~~~~
185
186Import classes are substantiated only once and are used as needed.
187This means that if something needs to be initialized before the
188``Reader()`` will be called to read a new file, it must be coded. The
189``ReInitialize()`` method is provided for this and it is always called
190before the ``ContentsValidator`` method is called. Use care to call
191the parent class ``ReInitialize()`` method, if this is overridden.
192
193
194ContentsValidator return values
195________________________________
196
197The ``ContentsValidator`` routine should return the value of True if
198the file appears to match the type expected for the class.
199
200If the file cannot be read by this class,  the routine should
201return False. Preferably one will also place text in `self.errors` 
202to give the user information on what went wrong during the reading.
203
204Phase Import Routines
205----------------------------------------
206Phase import routines are classes derived from
207:class:`GSASIIIO.ImportPhase`
208They must be found in files named `G2phase*.py` that are in the Python path
209and the class must override the ``__init__`` method and add a ``Reader`` method.
210The distributed routines are:
211
212.. automodule:: G2phase
213    :members: 
214    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
215
216.. automodule:: G2phase_GPX
217    :members: 
218    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
219      a text file.
220
221.. automodule:: G2phase_CIF
222    :members: 
223    :synopsis: Reads phase information from a CIF
224
225.. automodule:: G2phase_INS
226    :members: 
227
228
229
230Powder Data Import Routines
231---------------------------------------------
232Powder data import routines are classes derived from
233:class:`GSASIIIO.ImportPowderData`.
234They must be found in files named `G2pwd*.py` that are in the Python path
235and the class must override the ``__init__`` method and add a
236``Reader`` method.
237
238The distributed routines are:
239
240.. automodule:: G2pwd_GPX
241    :members: 
242    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
243
244.. automodule:: G2pwd_fxye
245    :members: 
246    :synopsis: Reads powder data in all of the GSAS formats
247
248.. automodule:: G2pwd_xye
249    :members: 
250    :synopsis: Reads powder data from a Topas format file
251
252.. automodule:: G2pwd_CIF
253    :members: 
254    :synopsis: Reads powder data from a CIF
255
256.. automodule:: G2pwd_BrukerRAW
257    :members: 
258    :synopsis: Reads powder data from a Brucker .raw file
259
260.. automodule:: G2pwd_FP
261    :members: 
262
263.. automodule:: G2pwd_Panalytical
264    :members: 
265
266.. automodule:: G2pwd_csv
267    :members: 
268
269.. automodule:: G2pwd_rigaku
270    :members: 
271
272
273
274Single Crystal Data Import Routines
275-----------------------------------------------------
276Single crystal data import routines are classes derived from
277, :class:`GSASIIIO.ImportStructFactor`.
278They must be found in files named `G2sfact*.py` that are in the Python path
279and the class must override the ``__init__`` method and add a ``Reader`` method.
280The distributed routines are:
281
282.. automodule:: G2sfact
283    :members: 
284    :synopsis: Reads single crystal data from simple hkl files
285
286.. automodule:: G2sfact_CIF
287    :members: 
288    :synopsis: Reads single crystal data from CIF files
289
290
291Small Angle Scattering Data Import Routines
292-----------------------------------------------------
293Small angle scattering data import routines are classes derived from
294, :class:`GSASIIIO.ImportSmallAngle`.
295They must be found in files named `G2sad*.py` that are in the Python path
296and the class must override the ``__init__`` method and add a ``Reader`` method.
297The distributed routines are:
298
299.. automodule:: G2sad_xye
300    :members: 
301    :synopsis: Reads small angle scattering data from simple files
302
303Image Import Routines
304-----------------------------------------------------
305Image import routines are classes derived from
306:class:`GSASIIIO.ImportImage`.
307See :ref:`Writing a Import Routine<Import_Routines>` for general
308information on importers and
309:ref:`the ImportImage docstring<Image_import_routines>`
310for what a reader should define.
311Image importers must be found in files named `G2img*.py` that are in the Python path
312and the class must override the ``__init__`` method and add a
313``Reader`` method.
314
315The distributed routines are:
316
317.. automodule:: G2img_ADSC
318    :members: 
319
320.. automodule:: G2img_EDF
321    :members: 
322
323.. automodule:: G2img_SumG2
324    :members: 
325
326.. automodule:: G2img_GE
327    :members: 
328
329.. automodule:: G2img_MAR
330    :members: 
331
332.. automodule:: G2img_Rigaku
333    :members: 
334
335.. automodule:: G2img_1TIF
336    :members: 
337
338.. automodule:: G2img_CheMin
339    :members: 
340
341.. automodule:: G2img_CBF
342    :members: 
343
344.. automodule:: G2img_HDF5
345    :members: 
346
347PDF Import Routines
348-----------------------------------------------------
349PDF import routines are classes derived from
350:class:`GSASIIIO.ImportPDFData`.
351See :ref:`Writing a Import Routine<Import_Routines>` for general information on importers.
352
353The distributed routines are:
354
355.. automodule:: G2pdf_gr
356    :members: 
357
358Reflectometry Import Routines
359-----------------------------------------------------
360Reflectometry import routines are classes derived from
361:class:`GSASIIIO.ImportReflectometryData`.
362See :ref:`Writing a Import Routine<Import_Routines>` for general information on importers.
363
364The distributed routines are:
365
366.. automodule:: G2rfd_xye
367    :members: 
368
369
Note: See TracBrowser for help on using the repository browser.