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

Last change on this file since 3822 was 3822, checked in by toby, 3 years ago

fixing a broken doc reference?

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