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

20. GSAS-II Importer Modules

Imports are implemented by deriving a class from GSASIIobj.ImportPhase, GSASIIobj.ImportStructFactor, GSASIIobj.ImportPowderData , GSASIIobj.ImportSmallAngleData, GSASIIobj.ImportReflectometryData, GSASIIobj.ImportPDFData, or GSASIIobj.ImportImage. These classes are in turn derived from GSASIIobj.ImportBaseclass.

Module file names (G2phase_, G2pwd_ and G2sfact_, etc.) are used to determine which menu an importer routine should be placed into. (N.B. in retrospect this naming was an unnecessary choice; importer types could have been determined from the base class.) To implement the import of a phase, a single crystal or a powder dataset, etc., create a file named with the appropriate file name prefix and place the file anywhere in the path defined in sys.path. The next time GSAS-II is started, the file should be read by Python and the new format will appear in the appropriate importer menu. Importers are documented below, separated by type. Importers tend to be fairly simple files, where many are in the range of 50-100 lines, and where more than half of those lines are directly copied from other importers without any changes. Details on this are given in the Writing a Importer Routine section, immediately below.

20.1. Writing an Importer Routine

When writing a importer routine, one should create a new class derived from GSASIIobj.ImportPhase, GSASIIobj.ImportStructFactor, GSASIIobj.ImportPowderData , GSASIIobj.ImportSmallAngleData, GSASIIobj.ImportReflectometryData, GSASIIobj.ImportPDFData, or GSASIIobj.ImportImage. As described below, all these classes will implement an __init__() and a Reader() method, and most will supply a ContentsValidator() method, too. See the appropriate class documentation for details on what values each type of Reader() should set. General principles on how an importer works are described below.

20.1.1. __init__()

The __init__ method will follow standard boilerplate:

def __init__(self):
    super(self.__class__,self).__init__( # fancy way to self-reference
        extensionlist=('.ext1','ext2'),
        strictExtension=True,
        formatName = 'example image',
        longFormatName = 'A longer description that this is an example image format'
        )

The first line in the __init__ method calls the parent class __init__ method with the following parameters:

• extensionlist: a list of extensions that may be used for this type of file.

• strictExtension: Should be True if only files with extensions in extensionlist are allows; False if all file types should be offered in the file browser. Also if False, the importer class will be used on all files when “guess from format” is tried, though readers with matching extensions will be tried first. It is a very good idea to supply a ContentsValidator method when strictExtension is False.

• formatName: a string to be used in the menu. Should be short.

• longFormatName: a longer string to be used to describe the format in help.

Note that if an importer detects a condition which prevents its use, for example because a required Python package is not present, it can set the value of self.UseReader to False. Another possible use for this would be an importer that requires a network connection to a remote site. Setting self.UseReader to False must be done in the __init__ method and will prevent the importer from being used or included in the expected menu.

20.1.2. Reader()

The class must supply a Reader method that actually performs the reading. All readers must have at a minimum these arguments:

def Reader(self, filename, filepointer, ParentFrame, **unused):

where the arguments have the following uses:

• filename: a string with the name of the file being read

• filepointer: a file object (created by open()) that accesses the file and is points to the beginning of the file when Reader is called.

• ParentFrame: a reference to the main GSAS-II (tree) windows, for the unusual Reader routines that will create GUI windows to ask questions. The Reader should do something reasonable such as take a reasonable default if ParentFrame is None, which indicates that GUI should not be accessed.

In addition, the following keyword parameters are defined that Reader routines may optionally use:

• buffer: a dict that can be used to retain information between repeated calls of the routine

• blocknum: counts the number of times that a reader is called, to be used with files that contain more than one set of data (e.g. GSAS .gsa/.fxye files with multiple banks or image files with multiple images.)

• usedRanIdList: a list of previously used random Id values that can be checked to determine that a value is unique.

Note that a Reader is used to read only a single phase, image, dataset, etc. and will be called repeatedly when used to read files that contain multiple datasets, etc. The buffer dict can be used to hold information that will speed repeated calls. As an example, the buffer dict is used in CIF reading to hold the parsed CIF file, so that when reading multiple datasets or phases from a multi-block CIF, the parsed information can be reused without having to reread and reparse the file for subsequent calls.

Some additional information specific to on what a Reader() method should do for images and single-crystal datasets can be found in the documentation for ImportImage (images) and ImportStructFactor, respectively.

20.1.2.1. Reader return values

The Reader routine should return the value of True if the file has been read successfully. Optionally, use self.warnings to indicate any problems.

If the file cannot be read, the Reader routine should return False or raise an GSASIIobj.ImportBaseclass.ImportException exception. (Why either? Sometimes an exception is the easiest way to bail out of a called routine.) Place text in self.errors and/or use:

ImportException('Error message')

to give the user information on what went wrong during the reading. The following variables are used to indicate results from the reader:

self.warnings

Use self.warnings to indicate any information that should be displayed to the user if the file is read successfully, but perhaps not completely or additional settings will need to be made.

self.errors

Use self.errors to give the user information on where and why a read error occurs in the file. Note that text supplied with the raise statement will be appended to self.errors.

self.repeat

Set self.repeat to True (the default is False) if a Reader should be called again to after reading to indicate that more data may exist in the file to be read. This is used for reading multiple powder histograms or multiple images from a single file. Variable self.repeatcount is used to keep track of the block numbers.

20.1.2.2. Reader support routines

Note that GSASIIctrlGUI supplies three GUI routines, BlockSelector() MultipleBlockSelector() and MultipleChoiceSelector() that are useful for selecting amongst one or more datasets (and perhaps phases) or data items for Reader() routines that may encounter more than one set of information in a file.

20.1.3. ContentsValidator()

Defining a ContentsValidator method is optional, but is usually a good idea, particularly if the file extension is not a reliable identifier for the file type. The intent of this routine is to take a superficial look at the file to see if it has the expected characteristics of the expected file type. For example, are there numbers in the expected places?

This routine is passed a single argument:

• filepointer: a file object (created by open()) that accesses the file and is points to the beginning of the file when ContentsValidator is called.

Note that GSASIIobj.ImportBaseclass.CIFValidator() is a ContentsValidator for validating CIF files.

20.1.3.1. ContentsValidator return values

The ContentsValidator routine should return the value of True if the file appears to match the type expected for the class.

If the file cannot be read by this class, the routine should return False. Preferably one will also place text in self.errors to give the user information on what went wrong during the reading.

20.1.4. ReInitialize()

Importer classes are substantiated only once and are used as needed. This means that if something needs to be initialized before the Reader() will be called to read a new file, the initialization step must be coded. The ReInitialize() method is provided for this and it is always called before the ContentsValidator method is called. Use care to call the parent class ReInitialize() method, if this is overridden.

20.2. Phase Importer Routines

Phase importer routines are classes derived from GSASIIobj.ImportPhase. They must be found in files named G2phase*.py that are in the Python path and the class must override the __init__ method and add a Reader method. The distributed routines are:

20.2.1. Module G2phase: PDB, .EXP & JANA m40,m50

A set of short routines to read in phases using routines that were previously implemented in GSAS-II: PDB, GSAS .EXP and JANA m40-m50 file formats

class G2phase.EXP_ReaderClass

Routine to import Phase information from GSAS .EXP files

ContentsValidator(filename)

Look for a VERSION tag in 1st line

ReadEXPPhase(G2frame, filepointer)

Read a phase from a GSAS .EXP file.

Reader(filename, ParentFrame=None, usedRanIdList=[], **unused)

Read a phase from a GSAS .EXP file using ReadEXPPhase()

class G2phase.JANA_ReaderClass

Routine to import Phase information from a JANA2006 file

ContentsValidator(filename)

Taking a stab a validating a .m50 file (look for cell & at least one atom)

ReadJANAPhase(filename, parent=None)

Read a phase from a JANA2006 m50 & m40 files.

Reader(filename, ParentFrame=None, **unused)

Read a m50 file using ReadJANAPhase()

class G2phase.PDB_ReaderClass

Routine to import Phase information from a PDB file

ContentsValidator(filename)

Taking a stab a validating a PDB file (look for cell & at least one atom)

ReadPDBPhase(filename, parent=None)

Read a phase from a PDB file.

Reader(filename, ParentFrame=None, **unused)

Read a PDF file using ReadPDBPhase()

class G2phase.PDF_ReaderClass

Routine to import Phase information from ICDD PDF Card files

ContentsValidator(filename)

Look for a str tag in 1st line

ReadPDFPhase(G2frame, fp)

Read a phase from a ICDD .str file.

Reader(filename, ParentFrame=None, **unused)

Read phase from a ICDD .str file using ReadPDFPhase()

20.2.2. Module G2phase_GPX: Import phase from GSAS-II project

Copies a phase from another GSAS-II project file into the current project.

Class to read a phase from an existing GSAS-II project file

class G2phase_GPX.PhaseReaderClass

Opens a .GPX file and pulls out a selected phase

ContentsValidator(filename)

Test if the 1st section can be read as a pickle block, if not it can’t be .GPX!

Reader(filename, ParentFrame=None, **unused)

Read a phase from a .GPX file. Does not (yet?) support selecting and reading more than one phase at a time.

20.2.3. Module G2phase_CIF: Coordinates from CIF

Parses a CIF using PyCifRW from James Hester (https://github.com/jamesrhester/pycifrw) and pulls out the structural information.

If a CIF generated by ISODISTORT is encountered, extra information is added to the phase entry and constraints are generated.

class G2phase_CIF.CIFPhaseReader

Implements a phase importer from a possibly multi-block CIF file

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

ISODISTORT_proc(blk, atomlbllist, ranIdlookup, filename)

Process ISODISTORT items to create constraints etc. Constraints are generated from information extracted from loops beginning with _iso_ and are placed into self.Constraints, which contains a list of constraints tree items and one dict. The dict contains help text for each generated ISODISTORT variable

At present only _iso_displacivemode… and _iso_occupancymode… are processed. Not yet processed: _iso_magneticmode…, _iso_rotationalmode… & _iso_strainmode…

ISODISTORT_test(blk)

Test if there is any ISODISTORT information in CIF

At present only _iso_displacivemode… and _iso_occupancymode… are tested.

G2phase_CIF.ISODISTORT_shortLbl(lbl, shortmodelist)

Shorten model labels and remove special characters

20.2.4. Module G2phase_INS: Import phase from SHELX INS file

Copies a phase from SHELX ins file into the current project.

class G2phase_INS.PhaseReaderClass

Opens a .INS file and pulls out a selected phase

ContentsValidator(filename)

Test if the ins file has a CELL record

ReadINSPhase(filename, parent=None)

Read a phase from a INS file.

Reader(filename, filepointer, ParentFrame=None, **unused)

Read a ins file using ReadINSPhase()

20.2.5. Module G2phase_rmc6f: Import phase from RMCProfile

Copies a phase from a file written by RMCProfile into the current GSAS-II project.

Class to read a phase from a RMCprofile output file

class G2phase_rmc6f.PhaseReaderClass

Opens a .rmc6f file and pulls out the phase

ContentsValidator(filename)

Test if the rmc6f file has a CELL record

Reader(filename, filepointer, ParentFrame=None, **unused)

Read a rmc6f file using ReadINSPhase()

Readrmc6fPhase(filename, parent=None)

Read a phase from a rmc6f file.

20.2.6. Module G2phase_xyz: read coordinates from an xyz file

A short routine to read in a phase from an xyz Cartesian coordinate file

class G2phase_xyz.XYZ_ReaderClass

Routine to import Phase information from a XYZ file

ContentsValidator(filename)

Taking a stab a validating: 1st line should be a number

Reader(filename, ParentFrame=None, **unused)

Read a PDF file using ReadPDBPhase()

20.3. Powder Data Importer Routines

Powder data importer routines are classes derived from GSASIIobj.ImportPowderData. They must be found in files named G2pwd*.py that are in the Python path and the class must override the __init__ method and add a Reader method.

The distributed powder data importers are:

20.3.1. Module G2pwd_GPX: GSAS-II projects

Routine to importer powder data from GSAS-II .gpx files

class G2pwd_GPX.GSAS2_ReaderClass

Routines to import powder data from a GSAS-II file This should work to pull data out from a out of date .GPX file as long as the details of the histogram data itself don’t change

ContentsValidator(filename)

Test if the 1st section can be read as a cPickle block, if not it can’t be .GPX!

Reader(filename, ParentFrame=None, **kwarg)

Read a dataset from a .GPX file. If multiple datasets are requested, use self.repeat and buffer caching.

20.3.2. Module G2pwd_fxye: GSAS data files

Routine to read in powder data in a variety of formats that were defined in the original GSAS/EXPGUI software suite.

class G2pwd_fxye.GSAS_ReaderClass

Routines to import powder data from a GSAS files

ContentsValidator(filename)

Validate by checking to see if the file has BANK lines & count them

Reader(filename, ParentFrame=None, **kwarg)

Read a GSAS (old formats) file of type FXY, FXYE, ESD or STD types. If multiple datasets are requested, use self.repeat and buffer caching.

EDS data is only in the STD format (10 values per line separated by spaces); the 1st line contains at col 60 the word “Two-Theta “ followed by the appropriate value. The BANK record contains the 3 values (4th not used) after ‘EDS’ for converting MCA channel number (c) to keV via E = A + Bc + Cc^2; these coefficients are generally predetermined by calibration of the MCA. They & 2-theta are transferred to the Instrument parameters data.

G2pwd_fxye.sfloat(S)

convert a string to a float, treating an all-blank string as zero

G2pwd_fxye.sint(S)

convert a string to an integer, treating an all-blank string as zero

20.3.3. Module G2pwd_xye: Topas & Fit2D data

Routine to read in powder data from a number of related formats including ones used in Topas and Fit2D. Typical file extensions are .xye, .qye, .chi, and .qchi.

Importer for various two/three column formats with 2theta vs intensity or Q vs intensity with an optional 3rd column for s.u.(I)

class G2pwd_xye.xye_ReaderClass

Routines to import powder data from a .xye/.chi file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid Topas Fit2D or BNL/pyFAI file. Alas the latter two formats are somewhat in conflict.

Reader(filename, ParentFrame=None, **unused)

Read a Topas file

20.3.4. Module G2pwd_CIF: CIF powder data

Routine to read in powder data from a CIF. Parses a CIF using PyCifRW from James Hester (https://github.com/jamesrhester/pycifrw).

Class to read a phase from a CIF

class G2pwd_CIF.CIFpwdReader

Routines to import powder data from a CIF file

ContentsValidator(filename)

Use standard CIF validator

Reader(filename, ParentFrame=None, **kwarg)

Read powder data from a CIF. If multiple datasets are requested, use self.repeat and buffer caching.

20.3.5. Module G2pwd_BrukerRAW: Bruker .raw & .brml

Routine to read in powder data from a Bruker versions 1, 2, or 3 .raw or a .brml file. Alas, we have not been able to get documentation for the version 4 .raw file, so this is not yet supported.

class G2pwd_BrukerRAW.brml_ReaderClass

Routines to import powder data from a zip Bruker .brml file

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **kwarg)

Read a Bruker brml file

class G2pwd_BrukerRAW.raw_ReaderClass

Routines to import powder data from a binary Bruker .RAW file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid Bruker RAW file

Reader(filename, ParentFrame=None, **kwarg)

Read a Bruker RAW file

20.3.6. Module G2pwd_FP: FullProf .dat data

Routine to read in powder data from a FullProf .dat file

class G2pwd_FP.fp_ReaderClass

Routines to import powder data from a FullProf 1-10 column .dat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid FullProf file

Reader(filename, ParentFrame=None, **unused)

Read a FullProf file

20.3.7. Module G2pwd_Panalytical: Panalytical .xrdml data

Routines to importer powder data from a Pananalytical (XML) .xrdm file.

class G2pwd_Panalytical.Panalytical_ReaderClass

Routines to import powder data from a Pananalytical.xrdm (xml) file.

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **kwarg)

Read a Panalytical .xrdml (.xml) file; already in self.root

20.3.8. Module G2pwd_csv: Read Excel .csv data

Routine to read in powder data from Excel type comma separated variable column-oriented variable. The only allowed extensions for this are .csv, .xy, or .XY.

class G2pwd_csv.csv_ReaderClass

Routines to import powder data from a .xye file

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **unused)

Read a csv file

20.3.9. Module G2pwd_rigaku: powder data from a Rigaku .txt file

class G2pwd_rigaku.Rigaku_rasReaderClass

Routines to import powder data from a Rigaku .ras file with multiple scans. All scans will be imported as individual PWDR entries

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **kwarg)

Read a Rigaku .ras/.rasx file

class G2pwd_rigaku.Rigaku_txtReaderClass

Routines to import powder data from a Rigaku .txt file with an angle and then 1 or 11(!) intensity values on the line. The example file is proceeded with 10 of blank lines, but I have assumed they could be any sort of text. This code should work with an angle and any number of intensity values/line as long as the number is the same on each line. The step size may not change. The number of comment lines can also change, but should not appear to be intensity values (numbers only).

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **kwarg)

Read a Rigaku .txt file

20.4. Single Crystal Data Importer Routines

Single crystal data importer routines are classes derived from , GSASIIobj.ImportStructFactor. They must be found in files named G2sfact*.py that are in the Python path and the class must override the __init__ method and add a Reader method. The distributed routines are:

20.4.1. Module G2sfact: simple HKL import

Read structure factors from a number of hkl file types. Routines are provided to read from files containing F or F² values from a number of sources.

Classes to read single crystal reflection files in formats used by: Shelx, Jana, REMOS, TOPAS (SNS), HB-3A (HIFR)

G2sfact.ColumnValidator(parent, filepointer, nCol=5)

Validate a file to check that it contains columns of numbers

class G2sfact.HKLF_ReaderClass

Routines to import F, sig(F) reflections from a HKLF file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.HKLMF_ReaderClass

Routines to import F, reflections from a REMOS HKLMF file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.M90_ReaderClass

Routines to import F**2, sig(F**2) reflections from a JANA M90 file

ContentsValidator(filename)

Discover how many columns are in the m90 file - could be 9-12 depending on satellites

Reader(filename, filepointer, ParentFrame=None, **unused)

Read the file

class G2sfact.NT_HKLF2_ReaderClass

Routines to import neutron TOF F**2, sig(F**2) reflections from a HKLF file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers & count number of data blocks - “Banks”

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.NT_JANA2K_ReaderClass

Routines to import neutron TOF F**2, sig(F**2) reflections from a JANA2000 file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers & count number of data blocks - “Banks”

Reader(filename, filepointer, ParentFrame=None, **unused)

Read the file

class G2sfact.SHELX4_ReaderClass

Routines to import F**2, sig(F**2) reflections from a Shelx HKLF 4 file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.SHELX5_ReaderClass

Routines to import F**2, sig(F**2) twin/incommensurate reflections from a fixed format SHELX HKLF5 file

ContentsValidator(filename)

Discover how many columns before F^2 are in the SHELX HKL5 file - could be 3-6 depending on satellites

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.SHELX6_ReaderClass

Routines to import F**2, sig(F**2) twin/incommensurate reflections from a fixed format SHELX HKLF6 file

ContentsValidator(filename)

Discover how many columns before F^2 are in the SHELX HKL6 file - could be 3-6 depending on satellites

Reader(filename, ParentFrame=None, **unused)

Read the file

class G2sfact.hb3a_INT_ReaderClass

Routines to import neutron CW F**2, sig(F**2) reflections from a NIST hb3a int file

ContentsValidator(filename)

Make sure file contains the expected columns on numbers & count number of data blocks - “Banks”

Reader(filename, filepointer, ParentFrame=None, **unused)

Read the file

20.4.2. Module G2sfact_CIF: CIF import

Read structure factors from a CIF reflection table CIF using PyCifRW from James Hester (https://github.com/jamesrhester/pycifrw).

Class to read single-crystal data from a CIF

class G2sfact_CIF.CIFhklReader

Routines to import Phase information from a CIF file

ContentsValidator(filename)

Use standard CIF validator

Reader(filename, ParentFrame=None, **kwarg)

Read single crystal data from a CIF. If multiple datasets are requested, use self.repeat and buffer caching.

20.5. Small Angle Scattering Data Importer Routines

Small angle scattering data importer routines are classes derived from , GSASIIobj.ImportSmallAngle. They must be found in files named G2sad*.py that are in the Python path and the class must override the __init__ method and add a Reader method. The distributed routines are in:

20.5.1. Module G2sad_xye: read small angle data

Routines to read in small angle data from an .xye type file, with two-theta or Q steps. Expected extensions are .xsad, .xdat, .nsad, or .ndat.

class G2sad_xye.txt_NeutronReaderClass

Routines to import neutron q SAXD data from a .nsad or .ndat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

class G2sad_xye.txt_XRayReaderClass

Routines to import X-ray q SAXD data from a .xsad or .xdat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

class G2sad_xye.txt_nmNeutronReaderClass

Routines to import neutron q in nm-1 SAXD data from a .nsad or .ndat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

class G2sad_xye.txt_nmXRayReaderClass

Routines to import X-ray q SAXD data from a .xsad or .xdat file, q in nm-1

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

20.6. Image Importer Routines

Image importer routines are classes derived from GSASIIobj.ImportImage. See Writing a Importer Routine for general information on importers and the GSASIIobj.ImportImage for information on what class variables a reader should set. Image importers must be found in files named G2img*.py that are in the Python path and the class must override the __init__ method and add a Reader method.

The distributed routines are:

20.6.1. Module G2img_ADSC: .img image file

class G2img_ADSC.ADSC_ReaderClass

Reads an ADSC .img file

ContentsValidator(filename)

no test at this time

G2img_ADSC.GetImgData(filename, imageOnly=False)

Read an ADSC image file

20.6.2. Module G2img_EDF: .edf image file

class G2img_EDF.EDF_ReaderClass

Routine to read a Read European detector data .edf file. This is a particularly nice standard.

ContentsValidator(filename)

no test used at this time

G2img_EDF.GetEdfData(filename, imageOnly=False)

Read European detector data edf file

20.6.3. Module G2img_SumG2: Python pickled image

Routine to read an image from GSAS-II that has been pickled in Python. Images in this format are created by the “Sum image data” command. At least for now, only one image is permitted per file.

class G2img_SumG2.G2_ReaderClass

Routine to read an image that has been pickled in Python. Images in this format are created by the “Sum image data” command. At least for now, only one image is permitted per file.

ContentsValidator(filename)

test by trying to unpickle (should be quick)

Reader(filename, ParentFrame=None, **unused)

Read using cPickle

20.6.4. Module G2img_GE: summed GE image file

Read data from General Electric angiography x-ray detectors, primarily as used at APS 1-ID. This shows an example of an importer that will handle files with more than a single image.

class G2img_GE.GE_ReaderClass

Routine to read a GE image, typically from APS Sector 1.

The image files may be of form .geX (where X is ‘ ‘, 1, 2, 3, 4 or 5), which is a raw image from the detector. These files may contain more than one image and have a rudimentary header. Files with extension .sum or .cor are 4 byte integers/pixel, one image/file. Files with extension .avg are 2 byte integers/pixel, one image/file.

ContentsValidator(filename)

just a test on file size

Reader(filename, ParentFrame=None, **kwarg)

Read using GE file reader, GetGEsumData()

class G2img_GE.GEsum_ReaderClass

Routine to read multiple GE images & sum them, typically from APS Sector 1.

The image files may be of form .geX (where X is ‘ ‘, 1, 2, 3, 4 or 5), which is a raw image from the detector. These files may contain more than one image and have a rudimentary header. Files with extension .sum or .cor are 4 byte integers/pixel, one image/file. Files with extension .avg are 2 byte integers/pixel, one image/file.

ContentsValidator(filename)

just a test on file size

Reader(filename, ParentFrame=None, **kwarg)

Read using GE file reader, GetGEsumData()

G2img_GE.GetGEsumData(self, filename, imagenum=1, sum=False)

Read G.E. detector images from various files as produced at 1-ID and with Detector Pool detector. Also sums multiple image files if desired

20.6.5. Module G2img_MAR: MAR image files

G2img_MAR.GetMAR345Data(filename, imageOnly=False)

Read a MAR-345 image plate image

class G2img_MAR.MAR_ReaderClass

Routine to read several MAR formats, .mar3450,.mar2300,.mar2560

ContentsValidator(filename)

no test at this time

20.6.6. Module G2img_Rigaku: .stl image file

G2img_Rigaku.GetRigaku(filename, imageOnly=False)

Read Rigaku R-Axis IV image file

class G2img_Rigaku.Rigaku_ReaderClass

Routine to read a Rigaku R-Axis IV image file.

ContentsValidator(filename)

Test by checking if the file size makes sense.

20.6.7. Module G2img_1TIF: Tagged-image File images

Routine to read an image in Tagged-image file (TIF) format as well as a variety of slightly incorrect pseudo-TIF formats used at instruments around the world. This uses a custom reader that attempts to determine the instrument and detector parameters from various aspects of the file, not always successfully alas.

Note that the name G2img_1TIF is used so that this file will sort to the top of the image formats and thus show up first in the menu. (It is the most common, alas).

G2img_1TIF.GetTifData(filename)

Read an image in a pseudo-tif format, as produced by a wide variety of software, almost always incorrectly in some way.

G2img_1TIF.TIFValidator(filename)

Does the header match the required TIF header?

class G2img_1TIF.TIF_ReaderClass

Reads TIF files using a routine (GetTifData()) that looks for files that can be identified from known instruments and will correct for slightly incorrect TIF usage.

ContentsValidator(filename)

Does the header match the required TIF header?

Reader(filename, ParentFrame=None, **unused)

Read the TIF file using GetTifData() which attempts to recognize the detector type and set various parameters

20.6.8. Module G2img_PILTIF: Std Tagged-image File images

Routine to read an image in Tagged-image file (TIF) format using a standard image library function in Pillow or the now obsolete PIL package. This means that parameters such as the pixel size (which is in the TIFF header but is almost never correct) and distance to sample, etc. are not correct unless specified in a separate metadata file. See below for more information on metadata files.

Read TIF files using the PIL/Pillow module.

The metadata can be specified in a file with the same name and path as the TIFF file except that the the extension is .metadata.

The contents of that file are a series of lines of form:

keyword = value

Note that capitalization of keywords is ignored. Defined keywords are in table below. Any line without one of these keywords will be ignored.

keyword	explanation
wavelength	Wavelength in \(\AA\)
distance	Distance to sample in mm
polarization	Percentage polarized in horizontal plane
sampleChangerCoordinate	Used for sample changers to track sample
pixelSizeX	Pixel size in X direction (microns)
pixelSizeY	Pixel size in Y direction (microns)
CenterPixelX	Location of beam center as a pixel number (in X)
CenterPixelY	Location of beam center as a pixel number (in X)

class G2img_PILTIF.TIF_LibraryReader

Reads TIF files using a standard library routine. Metadata (such as pixel size) must be specified by user, either in GUI or via a metadata file. The library TIF reader can handle compression and other things that are not commonly used at beamlines.

ContentsValidator(filename)

Does the header match the required TIF header?

Reader(filename, ParentFrame=None, **unused)

Read the TIF file using the PIL/Pillow reader and give the user a chance to edit the likely wrong default image parameters.

20.6.9. Module G2img_png: png image file

Routine to read an image in .png (Portable Network Graphics) format. For now, the only known use of this is with converted Mars Rover (CheMin) tif files, so default parameters are for that.

class G2img_CheMin.png_ReaderClass

Reads standard PNG images; parameters are set to those of the Mars Rover (CheMin) diffractometer.

ContentsValidator(filename)

no test at this time

Reader(filename, ParentFrame=None, **unused)

Reads using standard scipy PNG reader

20.6.10. Module G2img_CBF: .cbf cif image file

class G2img_CBF.CBF_ReaderClass

Routine to read a Read cif image data .cbf file. This is used by Pilatus.

ContentsValidator(filename)

no test used at this time

Reader(filename, ParentFrame=None, **unused)

Read using Bob’s routine GetCbfData()

G2img_CBF.GetCbfData(self, filename)

Read cif binarydetector data cbf file

20.6.11. Module G2img_HDF5: summed HDF5 image file

Reads images found in a HDF5 file. If the file contains multiple images, all are read.

A reader for HDF-5 files. This should be as generic as possible, but at present this is pretty much customized for XSD-MPE (APS) uses.

class G2img_HDF5.HDF5_Reader

Routine to read a HDF-5 image, typically from APS Sector 6. initial version from B. Frosik/SDM. Updated to also handle Varex images from APS 1-ID-C.

ContentsValidator(filename)

Test if valid by seeing if the HDF5 library recognizes the file.

Reader(filename, ParentFrame=None, **kwarg)

Scan file structure using visit() and map out locations of image(s) then read one image using readDataset(). Save map of file structure in buffer arg, if used.

readDataset(fp, imagenum=1)

Read a specified image number from a file

visit(fp)

Recursively visit each node in an HDF5 file. For nodes ending in ‘data’ look at dimensions of contents. If the shape is length 2, 3, or 4 assume an image and index in self.buffer[‘imagemap’]

20.6.12. Module G2img_SFRM: Brucker .sfrm image file

G2img_SFRM.GetGFRMData(self, filename)

Read Bruker compressed binary detector data gfrm file

G2img_SFRM.GetSFRMData(self, filename)

Read cbf compressed binarydetector data sfrm file

class G2img_SFRM.SFRM_ReaderClass

Routine to read a Read Bruker Advance image data .sfrm/.grfm file.

ContentsValidator(filename)

GFRM files always begin with FORMAT, should also contain VERSION (also HDRBLKS, but not checked) No check for SRFM files

Reader(filename, ParentFrame=None, **unused)

Read using Bob’s routine GetSFRMData()

20.7. PDF Importer Routines

PDF importer routines are classes derived from GSASIIobj.ImportPDFData. See Writing a Importer Routine for general information on importers.

The distributed routines are in:

20.7.1. Module G2pdf_gr: read PDF G(R) data

Routines to read in G(R) data from a pdfGet/GSAS-II .gr or gudrun .dat file (with \(\AA\) steps) or S(Q) data from a .fq file.

class G2pdf_gr.txt_FSQReaderClass

Routines to import S(Q) data from a .fq file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid r-step file

class G2pdf_gr.txt_PDFReaderClass

Routines to import PDF G(R) data from a .gr file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid r-step file

class G2pdf_gr.txt_PDFReaderClassG

Routines to import PDF G(R) data from a .dat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid r-step file

20.8. Reflectometry Importer Routines

Reflectometry importer routines are classes derived from GSASIIobj.ImportReflectometryData. See Writing a Importer Routine for general information on importers.

The distributed routines are:

20.8.1. Module G2rfd_xye: read reflectometry data

Routines to read in reflectometry data from an .xrfd, .xdat, .xtrfd, .xtdat, .nrfd or .ndat type file, with two-theta or Q steps.

class G2rfd_xye.txt_NeutronReaderClass

Routines to import neutron q REFD data from a .nrfd or .ndat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

class G2rfd_xye.txt_XRayReaderClass

Routines to import X-ray q REFD data from a .xrfd or .xdat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

class G2rfd_xye.txt_XRayThetaReaderClass

Routines to import X-ray theta REFD data from a .xtrfd or .xtdat file

ContentsValidator(filename)

Look through the file for expected types of lines in a valid q-step file

20.8.2. Module G2rfd_Panalytical: read Panalytical reflectometry data

Routine to importer reflectivity data from a Panalytical .xrdm (xml) file.

class G2rfd_Panalytical.Panalytical_ReaderClass

Routines to import reflectivity data from a Panalytical.xrdm (xml) file.

ContentsValidator(filename)

This routine will attempt to determine if the file can be read with the current format. This will typically be overridden with a method that takes a quick scan of [some of] the file contents to do a “sanity” check if the file appears to match the selected format. the file must be opened here with the correct format (binary/text)

Reader(filename, ParentFrame=None, **kwarg)

Read a Panalytical .xrdml (.xml) file; already in self.root