\(\renewcommand\AA{\text{Å}}\)

20. GSAS-II Export Modules

Exports are implemented by deriving a class from GSASIIIO.ExportBaseclass. Initialization of self.exporttype determines the type of export that will be performed (‘project’, ‘phase’, ‘single’, ‘powder’, ‘image’, ‘map’ or (someday) ‘pdf’) and of self.multiple determines if only a single phase, data set, etc. can be exported at a time (when False) or more than one can be selected.

Powder export routines may optionally define a Writer() method that accepts the histogram tree name as well as a file name to be written. This allows GSASIIIO.ExportPowder() to use the exporter independent of the GUI, for example from GSASIIscriptable.

20.1. Module G2export_examples: Examples

Code to demonstrate how GSAS-II data export routines are created. The classes defined here, ExportPhaseText, ExportSingleText, ExportPowderReflText, and ExportPowderText each demonstrate a different type of export. Also see G2export_map.ExportMapASCII for an example of a map export.

20.1.1. G2export_examples Classes and Routines

Classes in G2export_examples follow:

class G2export_examples.ExportPhaseText(G2frame)

Used to create a text file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a phase as a text file

class G2export_examples.ExportPowderReflText(G2frame)

Used to create a text file of reflections from a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder reflections as a text file

class G2export_examples.ExportPowderText(G2frame)

Used to create a text file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder data as a text file

class G2export_examples.ExportSingleText(G2frame)

Used to create a text file with single crystal reflection data skips user rejected & space group extinct reflections

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of single crystal data as a text file

20.2. Module G2export_csv: Spreadsheet export

Code to create .csv (comma-separated variable) files for GSAS-II data export to a spreadsheet program, etc. Defines a number of .csv exports:

• ExportPhaseCSV: phases

• ExportPowderCSV: powder data, includes instrument parameters as well as obs & calc patterns, etc.

• ExportMultiPowderCSV: multiple powder datasets in a single spreadsheet

• ExportPowderReflCSV: reflections from a powder fit

• ExportSASDCSV: small angle data set

• ExportREFDCSV: reflectometry data set

• ExportSingleCSV: single crystal reflection data

• ExportStrainCSV: reflectometry datasets

20.2.1. G2export_csv Classes and Routines

Classes in G2export_csv follow:

class G2export_csv.ExportMultiPowderCSV(G2frame)

Used to create a csv file for a stack of powder data sets suitable for display purposes only; no y-calc or weights are exported only x & y-obs :param wx.Frame G2frame: reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder data as a single csv file

class G2export_csv.ExportPhaseCSV(G2frame)

Used to create a csv file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a phase as a csv file

class G2export_csv.ExportPowderCSV(G2frame)

Used to create a csv file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder data as a csv file

class G2export_csv.ExportPowderReflCSV(G2frame)

Used to create a csv file of reflections from a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder reflections as a csv file

class G2export_csv.ExportREFDCSV(G2frame)

Used to create a csv file for a reflectometry data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of reflectometry data as a csv file

class G2export_csv.ExportSASDCSV(G2frame)

Used to create a csv file for a small angle data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of small angle data as a csv file

class G2export_csv.ExportSingleCSV(G2frame)

Used to create a csv file with single crystal reflection data

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of single crystal data as a csv file

class G2export_csv.ExportStrainCSV(G2frame)

Used to create a csv file with single crystal reflection data

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of single crystal data as a csv file

G2export_csv.WriteList(obj, headerItems)

Write a CSV header

Parameters:

• obj (object) – Exporter object

• headerItems (list) – items to write as a header

20.3. Module G2export_PDB: Macromolecular export

Code to export a phase into the venerated/obsolete (pick one) ASCII PDB format. Also defines exporter ExportPhaseCartXYZ which writes atom positions in orthogonal coordinates for a phase.

20.3.1. G2export_PDB Classes and Routines

Classes in G2export_PDB follow:

class G2export_PDB.ExportPhaseCartXYZ(G2frame)

Used to create a Cartesian XYZ file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export as a XYZ file

class G2export_PDB.ExportPhasePDB(G2frame)

Used to create a PDB file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export as a PDB file

20.4. Module G2export_image: 2D Image data export

Demonstrates how an image is retrieved and written. Uses a SciPy routine to write a PNG format file.

20.4.1. G2export_image Classes and Routines

Classes in G2export_image follow:

class G2export_image.ExportImagePNG(G2frame)

Used to create a PNG file for a GSAS-II image

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export an image

20.5. Module G2export_map: Map export

Code to write Fourier/Charge-Flip atomic density maps out in formats that can be read by external programs. At present a GSAS format that is supported by FOX and DrawXTL (ExportMapASCII) and the CCP4 format that is used by COOT (ExportMapCCP4) are implemented.

20.5.1. G2export_map Classes and Routines

Classes in G2export_map follow:

class G2export_map.ExportMapASCII(G2frame)

Used to create a text file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a map as a text file

class G2export_map.ExportMapCCP4(G2frame)

Used to create a text file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a map as a text file

Write(data, dtype)

write a line of output, attaching a line-end character

Parameters:

line (str) – the text to be written.

20.6. Module G2export_shelx: Examples

Code to export coordinates in the SHELX .ins format (as best as I can makes sense of it).

20.6.1. G2export_shelx Classes and Routines

Classes in G2export_shelx follow:

class G2export_shelx.ExportPhaseShelx(G2frame)

Used to create a SHELX .ins file for a phase

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export as a SHELX .ins file

20.7. Module G2export_CIF: CIF Exports

This implements a complex set of CIF (Crystallographic Information Framework) exporters. The base class, ExportCIF, implement a variety of export capabilities, where extra parameters for ExportCIF:MasterExporter() determine if a project, single phase or data set are written. The subclasses of ExportCIF, as listed below, supply these different parameters when calling that method.

• ExportProjectCIF: writes an entire project in a complete CIF intended for submission as a publication,

• ExportPhaseCIF: writes a single phase in CIF

• ExportPwdrCIF: writes a one powder diffraction dataset CIF

• ExportHKLFCIF: writes a single crystal dataset

20.7.1. G2export_CIF Classes and Routines

Classes in G2export_CIF follow:

G2export_CIF.CIF2dict(cf)

copy the contents of a CIF out from a PyCifRW block object into a dict

Returns:

cifblk, loopstructure where cifblk is a dict with CIF items and loopstructure is a list of lists that defines which items are in which loops.

class G2export_CIF.CIFdefHelp(parent, msg, helpwin, helptxt)

Create a help button that displays help information on the current data item

Parameters:

• parent – the panel which will be the parent of the button

• msg (str) – the help text to be displayed

• helpwin (wx.Dialog) – Frame for CIF editing dialog

• helptxt (wx.TextCtrl) – TextCtrl where help text is placed

class G2export_CIF.CIFtemplateSelect(frame, panel, tmplate, G2dict, repaint, title, defaultname='', cifKey='CIF_template')

Create a set of buttons to show, select and edit a CIF template

Parameters:

• frame – wx.Frame object of parent

• panel – wx.Panel object where widgets should be placed

• tmplate (str) – one of ‘publ’, ‘phase’, or ‘instrument’ to determine the type of template

• G2dict (dict) – GSAS-II dict where CIF should be placed. The key specified in cifKey (defaults to “CIF_template”) will be used to store either a list or a string. If a list, it will contain a dict and a list defining loops. If an str, it will contain a file name.

• repaint (function) – reference to a routine to be called to repaint the frame after a change has been made

• title (str) – A line of text to show at the top of the window

• defaultname (str) – specifies the default file name to be used for saving the CIF.

• cifKey (str) – key to be used for saving the CIF information in G2dict. Defaults to “CIF_template”

class G2export_CIF.EditCIFpanel(parent, cifblk, loopstructure, cifdic={}, OKbuttons=[], **kw)

Creates a scrolled panel for editing CIF template items

Parameters:

• parent (wx.Frame) – parent frame where panel will be placed

• cifblk – dict or PyCifRW block containing values for each CIF item

• loopstructure (list) –

  a list of lists containing the contents of each loop, as an example:

  [ ["_a","_b"], ["_c"], ["_d_1","_d_2","_d_3"]]
  

  this describes a CIF with this type of structure:

  loop_ _a _b <a1> <b1> <a2> ...
  loop_ _c <c1> <c2>...
  loop _d_1 _d_2 _d_3 ...
  

  Note that the values for each looped CIF item, such as _a, are contained in a list, for example as cifblk[“_a”]

• cifdic (dict) – optional CIF dictionary definitions

• OKbuttons (list) – A list of wx.Button objects that should be disabled when information in the CIF is invalid

• (other) – optional keyword parameters for wx.ScrolledPanel

CIFEntryWidget(dct, item, dataname)

Create an entry widget for a CIF item. Use a validated entry for numb values where int is required when limits are integers and floats otherwise. At present this does not allow entry of the special CIF values of “.” and “?” for numerical values and highlights them as invalid. Use a selection widget when there are specific enumerated values for a string.

ControlOKButton(setvalue)

Enable or Disable the OK button(s) for the dialog. Note that this is passed into the ValidatedTxtCtrl for use by validators.

Parameters:

setvalue (bool) – if True, all entries in the dialog are checked for validity. The first invalid control triggers disabling of buttons. If False then the OK button(s) are disabled with no checking of the invalid flag for each control.

DoLayout()

Update the Layout and scroll bars for the Panel. Clears self.LayoutCalled so that next change to panel can request a new update

OnAddRow(event)

add a row to a loop

OnLayoutNeeded(event)

Called when an update of the panel layout is needed. Calls self.DoLayout after the current operations are complete using CallAfter. This is called only once, according to flag self.LayoutCalled, which is cleared in self.DoLayout.

class G2export_CIF.EditCIFtemplate(parent, cifblk, loopstructure, defaultname)

Create a dialog for editing a CIF template. The edited information is placed in cifblk. If the CIF is saved as a file, the name of that file is saved as self.newfile.

Parameters:

• parent (wx.Frame) – parent frame or None

• cifblk – dict or PyCifRW block containing values for each CIF item

• loopstructure (list) –

  a list of lists containing the contents of each loop, as an example:

  [ ["_a","_b"], ["_c"], ["_d_1","_d_2","_d_3"]]
  

  this describes a CIF with this type of structure:

  loop_ _a _b <a1> <b1> <a2> ...
  loop_ _c <c1> <c2>...
  loop _d_1 _d_2 _d_3 ...
  

  Note that the values for each looped CIF item, such as _a, are contained in a list, for example as cifblk[“_a”]

• defaultname (str) – specifies the default file name to be used for saving the CIF.

Post()

Display the dialog

Returns:

True unless Cancel has been pressed.

class G2export_CIF.ExportCIF(G2frame, formatName, extension, longFormatName=None)

Base class for CIF exports. Not used directly. Exporters are defined in subclasses that call MasterExporter().

MasterExporter(event=None, phaseOnly=None, histOnly=None)

Basic code to export a CIF. Export can be full or simple, as set by phaseOnly and histOnly which skips distances & angles, etc.

Parameters:

• phaseOnly (bool) – used to export only one phase

• histOnly (bool) – used to export only one histogram

ShowHstrainCells(phasenam, datablockidDict)

Displays the unit cell parameters for phases where Dij values create mutiple sets of lattice parameters. At present there is no way defined for this in CIF, so local data names are used.

ValidateAscii(checklist)

Validate items as ASCII

class G2export_CIF.ExportHKLCIF(G2frame)

Used to create a simple CIF containing diffraction data only. Uses exact same code as ExportCIF except that histOnly is set for the Exporter Shows up in menu as Quick CIF.

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

class G2export_CIF.ExportPhaseCIF(G2frame)

Used to create a simple CIF with one phase. Uses exact same code as ExportCIF except that phaseOnly is set for the Exporter Shows up in menu as Quick CIF.

also called directly in OnISOSearch in GSASIIphsGUI

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

class G2export_CIF.ExportProjectCIF(G2frame)

Used to create a CIF of an entire project

also called directly in GSASIIIO.ExportSequentialFullCIF()

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

class G2export_CIF.ExportPwdrCIF(G2frame)

Used to create a simple CIF containing diffraction data only. Uses exact same code as ExportCIF except that histOnly is set for the Exporter Shows up in menu as Quick CIF.

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Writer(hist, mode='w')

Used for histogram CIF export of a sequential fit.

G2export_CIF.FmtAtomType(sym)

Reformat a GSAS-II atom type symbol to match CIF rules

G2export_CIF.HillSortElements(elmlist)

Sort elements in “Hill” order: C, H, others, (where others are alphabetical).

Params list elmlist:

a list of element strings

Returns:

a sorted list of element strings

G2export_CIF.LoadCIFdic()

Create a composite core+powder CIF lookup dict containing information about all items in the CIF dictionaries, loading pickled files if possible. The routine looks for files named cif_core.cpickle and cif_pd.cpickle in every directory in the path and if they are not found, files cif_core.dic and/or cif_pd.dic are read.

Returns:

the dict with the definitions

G2export_CIF.PickleCIFdict(fil)

Loads a CIF dictionary, cherry picks out the items needed by local code and sticks them into a python dict and writes that dict out as a pickle file for later reuse. If the write fails a warning message is printed, but no exception occurs.

Parameters:

fil (str) – file name of CIF dictionary, will usually end in .dic

Returns:

the dict with the definitions

G2export_CIF.WriteAtomsMM(fp, phasedict, phasenam, parmDict, sigDict, RBparms={})

Write atom positions to CIF using mmCIF items

G2export_CIF.WriteAtomsMagnetic(fp, phasedict, phasenam, parmDict, sigDict, labellist)

Write atom positions to CIF

G2export_CIF.WriteAtomsNuclear(fp, phasedict, phasenam, parmDict, sigDict, labellist, RBparms={})

Write atom positions to CIF

G2export_CIF.WriteCIFitem(fp, name, value='')

Helper function for writing CIF output. This gets used in different ways. The simplest use will be:

>>> WriteCIFitem(fp, '_some_cif_name', valstr)

For loops it will be used like this:

>>> WriteCIFitem(fp, 'loop_   _cif_name1  _cif_name2')
>>> for v1,v2 in values:
>>>     WriteCIFitem(fp, value=v1)
>>>     WriteCIFitem(fp, value=v2)

or if items will be aligned in a table (no spaces or new lines in the items)

>>> WriteCIFitem(fp, 'loop_   _cif_name1  _cif_name2')
>>> for v1,v2 in values:
>>>     s = PutInCol("{:.4f}".format(v1),10)
>>>     s += PutInCol(str(v2),8) 
>>>     WriteCIFitem(fp, value=s)

It is occasionally used where a CIF value is passed as the name parameter. This works if no quoting is needed, but is not a good practice.

Parameters:

• fp – file access object

• name (str) – a CIF data name

• value (str) – the value associated with the CIF data name. Written in different ways depending on what the contents contain, with respect to quoting.

G2export_CIF.WriteComposition(fp, phasedict, phasenam, parmDict, quickmode=True, keV=None)

determine the composition for the unit cell, crudely determine Z and then compute the composition in formula units.

If quickmode is False, then scattering factors are added to the element loop.

If keV is specified, then resonant scattering factors are also computed and included.

G2export_CIF.WriteCompositionMM(fp, phasedict, phasenam, parmDict, quickmode=True, keV=None)

determine the composition for the unit cell, crudely determine Z and then compute the composition in formula units.

If quickmode is False, then scattering factors are added to the element loop.

If keV is specified, then resonant scattering factors are also computed and included.

G2export_CIF.WriteSeqAtomsNuclear(fp, cell, phasedict, phasenam, hist, seqData, RBparms)

Write atom positions to CIF

G2export_CIF.dict2CIF(dblk, loopstructure, blockname='Template')

Create a PyCifRW CIF object containing a single CIF block object from a dict and loop structure list.

Parameters:

• dblk – a dict containing values for each CIF item

• loopstructure (list) –

  a list of lists containing the contents of each loop, as an example:

  [ ["_a","_b"], ["_c"], ["_d_1","_d_2","_d_3"]]
  

  this describes a CIF with this type of structure:

  loop_ _a _b <a1> <b1> <a2> ...
  loop_ _c <c1> <c2>...
  loop _d_1 _d_2 _d_3 ...
  

  Note that the values for each looped CIF item, such as _a, are contained in a list, for example as cifblk[“_a”]

• blockname (str) – an optional name for the CIF block. Defaults to ‘Template’

Returns:

the newly created PyCifRW CIF object

G2export_CIF.getCellwStrain(phasedict, seqData, pId, histname)

Get cell parameters and their errors for a sequential fit

G2export_CIF.mkSeqResTable(mode, seqHistList, seqData, Phases, Histograms, Controls)

Setup sequential results table (based on code from GSASIIseqGUI.UpdateSeqResults)

TODO: This should be merged with the table build code in GSASIIseqGUI.UpdateSeqResults and moved to somewhere non-GUI like GSASIIstrIO to create a single routine that can be used in both places, but this means returning some of the code that has been removed from there

G2export_CIF.striphist(var, insChar='')

strip a histogram number from a var name

20.8. Module G2export_pwdr: Export powder input files

Creates files used by GSAS (FXYE) & TOPAS (XYE) as input

20.8.1. G2export_pwdr Classes and Routines

Classes in G2export_pwdr follow:

class G2export_pwdr.ExportPowderFXYE(G2frame)

Used to create a FXYE file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export one or more sets of powder data as FXYE file(s)

WriteInstFile(hist, Inst)

Write an instrument parameter file

Writer(TreeName, filename=None, prmname='')

Write a single PWDR entry to a FXYE file

class G2export_pwdr.ExportPowderXYE(G2frame)

Used to create a Topas XYE file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export one or more sets of powder data as XYE file(s)

20.9. Module G2export_FIT2D: Fit2D “Chi” export

Code to create .chi (Fit2D like) files for GSAS-II powder data export

20.9.1. G2export_FIT2d Classes and Routines

Classes in G2export_FIT2D follow:

class G2export_FIT2D.ExportPowderCHI(G2frame)

Used to create a CHI file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder data as a Fit2D .qchi file

class G2export_FIT2D.ExportPowderQCHI(G2frame)

Used to create a q-binned CHI file for a powder data set

Parameters:

G2frame (wx.Frame) – reference to main GSAS-II frame

Exporter(event=None)

Export a set of powder data as a q-bin Fit2D .qchi file

20.10. Module G2export_JSON: ASCII .gpx Export

This implements a fairly simple exporter, ExportJSON, that can export the contents of an entire project as a sort-of human readable (JSON) ASCII file. This provides a way to see the contents of a GSAS-II project file. This does not provide a mechanism to change the contents of a .gpx file, since there are no provisions to read this file back into GSAS-II, as the likelihood of breaking a data structure is too high. If you want to change the contents of a .gpx file, use GSASIIscriptable where you can access the native Python data structures and change things, with a good chance of getting things to work.

20.10.1. G2export_JSON Classes and Routines

Classes in G2export_JSON follow:

This code is to honor my friend Robert Papoular, who wants to see what is inside a .gpx file.

class G2export_JSON.ExportJSON(G2frame)

Implement JSON export of entire projects

class G2export_JSON.JsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

This provides the ability to turn np arrays and masked arrays into something that json can handle.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

20.11. Module G2export_Bracket: ASCII .gpx Export

This provides to methods for tabulating GSAS-II parameters from a project for use in manuscript preparation into an ASCII .csv (spreadsheet) file. The first, Exportbracket, provides standard uncertainties for values in crystallographic (e.g. “bracket”) notation: i.e.: 1.234(5), which indicates a value of 1.234 with a standard uncertainty of 0.005. The second method, Export3col, provides the standard uncertainties as a separate column.

This module initially written by Conrad Gillard. For any enquiries please contact conrad.gillard@gmail.com.

20.11.1. G2export_Bracket Classes and Routines

class G2export_Bracket.Export3col(G2frame)

Enables export of parameters that are commonly needed for publications, with esds in a separate column

ValEsd2col(param, param_sig)

Return two values with the formated value as the first number and the standard uncertainty (if provided) as the second value.

class G2export_Bracket.Exportbracket(G2frame)

Enables export of parameters that are commonly needed for publications, in bracket notation