A Candis interface to python 3 programs.
import py3io
import numpy
Py3io is a python 3 module for reading and writing Candis files from python 3 programs. It won’t work with python 2 without modification. The module defines a class called candis, each instance of which contains a representation of the data and metadata in a Candis file. Methods are provided to read and write Candis files into and out of the instance, to create incrementally a representation that can be written, and to access information in the instance. Multiple instances can be created so that multiple Candis files can be accessed at the same time. Files can also be read into an instance, modified by adding elements, and written out.
Candis files with multiple variable slices are read into and written from an instance all at once. This limits the size of files to some fraction of the available memory.
Candis parameters are a problem in general when multiple, possibly conflicting copies of the same parameter end up in a Candis file. Also, parameters unrelated to dimensions or limiting values have generally been found to be useless, so all parameters are discarded on output and the parameters associated with Candis dimensions are regenerated. The bad and badlim parameters are an exception -- if they exist on input, they are retained on output. If they don’t exist, they are created on output with the default values bad = 1.e30 and badlim = 9.99e29. Candis parameter values are represented as strings rather than floats, in agreement with their original definition in Candis. Python provides trivial conversion between floats and their string representations, so this not a major inconvenience.
Extraneous static field variables are also a potential problem. Py3io handles these by accepting on input and writing on output only static fields that are index fields, i.e., they represent information on Candis dimensions. Other static fields are silently discarded. The order of dimensions on input is retained on output.
The Numpy package is used to handle binary data within the py3io package. Numpy arrays may be either flat i.e., exhibiting only one array dimension, or shaped, exhibiting possibly multiple dimensions. Candis represents all fields as flat numpy arrays and shaped arrays are flattened automatically on input. Candis fields are normally represented as flat arrays on output even though the field is formally multi-dimensional. However, a convenience method is provided to give the output field a shape congruent with the dimensions over which it is defined.
The normal sequence of operations is to create a candis instance, either read in a Candis file or create a new file incrementally. Information in the file can also be accessed incrementally. If desired, a new Candis file can be written from the information stored in the instance.
The general philosophy of the package is to die with an error message if inappropriate input is received, e.g., a float which should be a string or a field that doesn’t exist.
Creating a candis instance:
a = candis()
This function creates a candis instance representing a null Candis file. The variable "a" represents the candis instance. This instance may be filled by reading in a file or by adding comments, parameters, dimensions, and fields incrementally. There is no need to destroy instances no longer being used -- python garbage collection takes care of that. In what follows, "a" at the beginning of the method is the instance returned by "candis()".
Methods for reading and writing files:
a.get_candis(filename)
This method reads a complete Candis file into the instance. "filename" is a string representing the name of the file. If "filename" = ’-’, the standard input is read. "True" is returned if the method succeeds.
a.put_candis(filename)
This method writes a complete Candis file to the file "filename". If "filename" = ’-’, the file is sent to standard output. "True" is returned if the method succeeds.
a.get_next_slice()
Upon reading, access is set to the first variable slice. This method advances to the next variable slice, returning "True" if it succeeds. If there are no more variable slices, it returns "False".
Methods for accessing data and metadata:
a.get_comment_info()
This method returns all comment lines in the form of a list.
a.get_param_info()
This method returns a list of all parameter names and values. Each name-value pair is represented by a sublist and the value is represented as a string.
a.get_param(pname)
This method returns a string representing the parameter with name "pname".
a.get_dim_info()
This method prints out information about all defined dimensions.
a.get_vfield_info()
This method prints out information about all defined variable fields.
a.get_field(fname)
This method returns information about either a dimension (static field) or a variable field named "fname" in the form of a list with two elements. The first element is the actual flattened numpy array data in the current variable slice. The second element is a sub-list of the names of the dimensions over which the field is defined. The list is empty for a zero-dimensional field.
a.get_field_shaped(fname)
This method is like "get_field()" except that the returned array has been shaped to be congruent with the dimensions over which the field is defined.
Adding information incrementally to the instance:
a.add_comment(comment)
This method adds "comment".
a.add_param(pname,pval)
This method adds a parameter "pname" with value "pval". Both are represented as strings.
a.add.dim(dname,dsize,ddata)
This method adds a dimension of name "dname", size "dsize" as an integer, and the one-dimensional numpy array containing the values of the dimension field.
a.add_vfield4(fname,dname1,dname2,dname3,dname4,fdata)
This method adds a 4-dimensional field named "fname" with dimension names "dname1", "dname2", .... The last argument is a list with elements being numpy arrays of the field data, one element for each variable slice. The arrays will be flattened if necessary.
a.add_vfield3(fname,dname1,dname2,dname3,fdata)
As above, but for a 3-dimensional field.
a.add_vfield2(fname,dname1,dname2,fdata)
As above, but for a 2-dimensional field.
a.add_vfield1(fname,dname1,fdata)
As above, but for a 1-dimensional field.
a.add_vfield0(fname,fdata)
As above, but for a 0-dimensional field. Note that "fdata" is still a numpy array even though it represents a scalar value.
None known at this point.
David J. Raymond, raymond@kestrel.nmt.edu