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

Last change on this file since 2087 was 2087, checked in by toby, 6 years ago

change error handling if h5py not installed; add new condition variable to importers (self.UseReader?); changes to docs to reflect this and consolidate description of package requirements

File size: 11.3 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
225Powder Data Import Routines
226---------------------------------------------
227Powder data import routines are classes derived from
228:class:`GSASIIIO.ImportPowderData`.
229They must be found in files named `G2pwd*.py` that are in the Python path
230and the class must override the ``__init__`` method and add a
231``Reader`` method.
232
233The distributed routines are:
234
235.. automodule:: G2pwd_GPX
236    :members: 
237    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
238
239.. automodule:: G2pwd_fxye
240    :members: 
241    :synopsis: Reads powder data in all of the GSAS formats
242
243.. automodule:: G2pwd_xye
244    :members: 
245    :synopsis: Reads powder data from a Topas format file
246
247.. automodule:: G2pwd_CIF
248    :members: 
249    :synopsis: Reads powder data from a CIF
250
251Single Crystal Data Import Routines
252-----------------------------------------------------
253Single crystal data import routines are classes derived from
254, :class:`GSASIIIO.ImportStructFactor`.
255They must be found in files named `G2sfact*.py` that are in the Python path
256and the class must override the ``__init__`` method and add a ``Reader`` method.
257The distributed routines are:
258
259.. automodule:: G2sfact
260    :members: 
261    :synopsis: Reads single crystal data from simple hkl files
262
263.. automodule:: G2sfact_CIF
264    :members: 
265    :synopsis: Reads single crystal data from CIF files
266
267
268Small Angle Scattering Data Import Routines
269-----------------------------------------------------
270Small angle scattering data import routines are classes derived from
271, :class:`GSASIIIO.ImportSmallAngle`.
272They must be found in files named `G2sad*.py` that are in the Python path
273and the class must override the ``__init__`` method and add a ``Reader`` method.
274The distributed routines are:
275
276.. automodule:: G2sad_xye
277    :members: 
278    :synopsis: Reads small angle scattering data from simple files
279
280Image Import Routines
281-----------------------------------------------------
282Image import routines are classes derived from
283:class:`GSASIIIO.ImportImage`.
284See :ref:`Writing a Import Routine<Import_Routines>` for general
285information on importers and
286:ref:`the ImportImage docstring<Image_import_routines>`
287for what a reader should define.
288Image importers must be found in files named `G2img*.py` that are in the Python path
289and the class must override the ``__init__`` method and add a
290``Reader`` method.
291
292The distributed routines are:
293
294.. automodule:: G2img_ADSC
295    :members: 
296
297.. automodule:: G2img_EDF
298    :members: 
299
300.. automodule:: G2img_SumG2
301    :members: 
302
303.. automodule:: G2img_GE
304    :members: 
305
306.. automodule:: G2img_MAR
307    :members: 
308
309.. automodule:: G2img_Rigaku
310    :members: 
311
312.. automodule:: G2img_1TIF
313    :members: 
314
315.. automodule:: G2img_CheMin
316    :members: 
Note: See TracBrowser for help on using the repository browser.