source: trunk/sphinxdocs/source/imports.rst @ 1172

Last change on this file since 1172 was 1172, checked in by toby, 8 years ago

ask to link phases to histograms after an import of either; rethink import initialization

File size: 8.5 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
6or :class:`GSASIIIO.ImportPowderData` (which are in turn
7derived from :class:`GSASIIIO.ImportBaseclass`)
8to implement import of
9a phase, a single crystal or a powder dataset, respectively.
10Module file names (`G2phase_`, `G2pwd_` and `G2sfact_`) are used to
11determine which menu an import routine should be placed into. (N.B. this
12was an unnecessary choice; this could be done from the class used.)
13
14Writing an Import Routine
15--------------------------
16
17.. _Import_routines:
18
19
20When writing a import routine, one should create a new class derived
21from :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
22or :class:`GSASIIIO.ImportPowderData`. As described below,
23all these classes will implement
24an ``__init__()`` and a ``Reader()`` method, and most will supply a
25``ContentsValidator()`` method, too.
26See the :class:`~GSASIIIO.ImportPhase`, :class:`~GSASIIIO.ImportStructFactor`
27or :class:`~GSASIIIO.ImportPowderData` class documentation
28for details on what values each type of ``Reader()`` should set.
29
30__init__()
31~~~~~~~~~~~~~~
32 
33The class should supply a
34``__init__`` method which calls the parent ``__init__`` method and
35specifies the following parameters:
36
37  * `extensionlist`: a list of extensions that may be used for this type of file.
38  * `strictExtension`: Should be True if only files with extensions in
39    `extensionlist` are allows; False if all file types should be offered
40    in the file browser. Also if False, the import class will be
41    used on all files when "guess from format" is tried, though
42    readers with matching extensions will be tried first.
43  * `formatName`: a string to be used in the menu. Should be short.
44  * `longFormatName`: a longer string to be used to describe the format in help.
45
46Reader()
47~~~~~~~~~~~~~~
48
49The class must supply a ``Reader`` method that actually performs the
50reading. All readers must have at a minimum these arguments::
51
52    def Reader(self, filename, filepointer, ParentFrame, **unused):
53
54where the arguments have the following uses:
55
56 * `filename`: a string with the name of the file being read
57 * `filepointer`: a file object (created by :func:`open`) that accesses
58   the file and is points to the beginning of the file when Reader is
59   called.
60 * `ParentFrame`: a reference to the main GSAS-II (tree) windows, for
61   the unusual ``Reader`` routines that will create GUI windows to ask
62   questions.
63
64In addition, the following keyword parameters are defined that ``Reader``
65routines may optionally use:
66
67 * `buffer`: a dict that can be used to retain information between repeated calls of the routine
68 * `blocknum`: counts the number of times that a reader is called
69 * `usedRanIdList`: a list of previously used random Id values that can be checked to determine that a value is unique.
70
71As an example, the `buffer` dict is used for CIF reading to hold the parsed CIF file
72so that it can be reused without having to reread the file from
73scratch.
74
75Reader return values
76______________________
77
78The ``Reader`` routine should return the value of True if the file has been
79read successfully. Optionally, use `self.warnings` to indicate any
80problems.
81
82If the file cannot be read,  the ``Reader`` routine should
83return False or raise an :class:`GSASIIIO.ImportBaseclass.ImportException`
84exception. (Why either? Sometimes an exception is the easiest way to
85bail out of a called routine.) Place text in `self.errors` and/or use::
86
87     ImportException('Error message')
88
89to give the user information on what went wrong during the reading.
90
91self.warnings
92_____________________
93
94Use `self.warnings` to indicate any information
95that should be displayed to the user if the file is read successfully,
96but perhaps not completely or additional settings will need to be
97made.
98
99self.errors
100_____________________
101
102Use `self.errors` to give the user information on where and why a read
103error occurs in the file. Note that text supplied with the ``raise``
104statement will be appended to ``self.errors``.
105
106self.repeat
107_____________________
108
109Set `self.repeat` to True (the default is False) if a Reader should be
110called again to read a second block from a file. Most commonly
111(only?) used for reading multiple powder histograms from a single
112file. Variable `self.repeatcount` is used to keep track of the block
113numbers.
114
115*support routines*
116_________________________
117
118Note that the base class (:class:`GSASIIIO.ImportBaseclass`) supplies two routines,
119:meth:`~GSASIIIO.ImportBaseclass.BlockSelector` and
120:meth:`~GSASIIIO.ImportBaseclass.MultipleBlockSelector` that are useful for
121selecting amongst one or more datasets (and perhaps phases) for
122``Reader()`` routines that may encounter more than one set of information
123in a file.
124Likewise, when an operation will take some time to complete,
125use :meth:`~GSASIIIO.ImportBaseclass.ShowBusy` and
126:meth:`~GSASIIIO.ImportBaseclass.DoneBusy` to show the user
127that something is happening.
128
129
130ContentsValidator()
131~~~~~~~~~~~~~~~~~~~~
132
133Defining a ``ContentsValidator`` method is optional, but is usually a
134good idea, particularly if the file extension is not a reliable
135identifier for the file type. The intent of this routine is to take a
136superficial look at the file to see if it has the expected
137characteristics of the expected file type. For example, are there
138numbers in the expected places?
139
140This routine is passed a single argument:
141
142* `filepointer`: a file object (created by :func:`open`) that accesses
143  the file and is points to the beginning of the file when ContentsValidator is
144  called.
145
146Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
147for validating CIF files.
148
149
150ReInitialize()
151~~~~~~~~~~~~~~~~~~~~
152
153Import classes are substantiated only once and are used as needed.
154This means that if something needs to be initialized before the
155``Reader()`` will be called to read a new file, it must be coded. The
156``ReInitialize()`` method is provided for this and it is always called
157before the ``ContentsValidator`` method is called. Use care to call
158the parent class ``ReInitialize()`` method, if this is overridden.
159
160
161ContentsValidator return values
162________________________________
163
164The ``ContentsValidator`` routine should return the value of True if
165the file appears to match the type expected for the class.
166
167If the file cannot be read by this class,  the routine should
168return False. Preferably one will also place text in `self.errors` 
169to give the user information on what went wrong during the reading.
170
171Currently Defined Phase Import Routines
172----------------------------------------
173Phase import routines are classes derived from
174:class:`GSASIIIO.ImportPhase`
175They must be found in files named `G2phase*.py` that are in the Python path
176and the class must override the ``__init__`` method and add a ``Reader`` method.
177The distributed routines are:
178
179.. automodule:: G2phase
180    :members: 
181    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
182
183.. automodule:: G2phase_GPX
184    :members: 
185    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
186      a text file.
187
188.. automodule:: G2phase_CIF
189    :members: 
190    :synopsis: Reads phase information from a CIF
191
192Currently Defined Powder Data Import Routines
193---------------------------------------------
194Powder data import routines are classes derived from
195:class:`GSASIIIO.ImportPowderData`.
196They must be found in files named `G2pwd*.py` that are in the Python path
197and the class must override the ``__init__`` method and add a ``Reader`` method.
198The distributed routines are:
199
200.. automodule:: G2pwd_GPX
201    :members: 
202    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
203
204.. automodule:: G2pwd_fxye
205    :members: 
206    :synopsis: Reads powder data in all of the GSAS formats
207
208.. automodule:: G2pwd_xye
209    :members: 
210    :synopsis: Reads powder data from a Topas format file
211
212.. automodule:: G2pwd_CIF
213    :members: 
214    :synopsis: Reads powder data from a CIF
215
216Currently Defined Single Crystal Data Import Routines
217-----------------------------------------------------
218Single crystal data import routines are classes derived from
219, :class:`GSASIIIO.ImportStructFactor`.
220They must be found in files named `G2sfact*.py` that are in the Python path
221and the class must override the ``__init__`` method and add a ``Reader`` method.
222The distributed routines are:
223
224.. automodule:: G2sfact
225    :members: 
226    :synopsis: Reads single crystal data from simple hkl files
227
228.. automodule:: G2sfact_CIF
229    :members: 
230    :synopsis: Reads single crystal data from CIF files
Note: See TracBrowser for help on using the repository browser.