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

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

fix cif export w/unused histogram; switch 3.x imports to pickle w/warn if _pickle not available; doc fixes; scriptable enhancements

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