Array¶

class igwn_ligolw.ligolw.Array(*args)¶

Bases: EmptyElement

Array element. During parsing, the character data contained within the Stream element is parsed into a numpy array object. The array has the dimensions and type described by the Array and Dim element metadata. When the document is written, the Stream element serializes the numpy array back into character data. The array is stored as an attribute of the Array element.

Examples:

>>> import numpy
>>> x = numpy.mgrid[0:5,0:3][0]
>>> x
array([[0, 0, 0],
       [1, 1, 1],
       [2, 2, 2],
       [3, 3, 3],
       [4, 4, 4]])
>>> x.shape
(5, 3)
>>> elem = Array.build("test", x, ["dim0", "dim1"])
>>> elem.shape
(5, 3)
>>> import sys
>>> elem.write(sys.stdout)
<Array Type="int_8s" Name="test:array">
        <Dim Name="dim1">3</Dim>
        <Dim Name="dim0">5</Dim>
        <Stream Type="Local" Delimiter=" ">
                0 1 2 3 4
                0 1 2 3 4
                0 1 2 3 4
        </Stream>
</Array>
>>> # change the Array shape.  the internal array is changed, too
>>> elem.shape = 15
>>> elem.write(sys.stdout)
<Array Type="int_8s" Name="test:array">
        <Dim Name="dim0">15</Dim>
        <Stream Type="Local" Delimiter=" ">
                0 0 0 1 1 1 2 2 2 3 3 3 4 4 4
        </Stream>
</Array>
>>> # replace the internal array with one with a different number
>>> # of dimensions.  assign to .array first, then fix .shape
>>> elem.array = numpy.mgrid[0:4,0:3,0:2][0]
>>> elem.shape = elem.array.shape
>>> elem.write(sys.stdout)
<Array Type="int_8s" Name="test:array">
        <Dim>2</Dim>
        <Dim>3</Dim>
        <Dim Name="dim0">4</Dim>
        <Stream Type="Local" Delimiter=" ">
                0 1 2 3
                0 1 2 3
                0 1 2 3
                0 1 2 3
                0 1 2 3
                0 1 2 3
        </Stream>
</Array>

Attributes Summary

`Name`	The "Name" attribute.
`Type`	The "Type" attribute.
`Unit`	The "Unit" attribute.
`shape`	The Array's dimensions.
`tagName`
`validchildren`

Methods Summary

`build`(name, array[, dim_names, encoding])	Construct a LIGO Light Weight XML Array document subtree from a numpy array object.
`getArraysByName`(elem, name)	Return a list of arrays with name name under elem.
`get_array`(xmldoc[, name])	Scan xmldoc for an array named name.
`unlink`()	Break internal references within the document tree rooted on this element to promote garbage collection.

Attributes Documentation

Name¶: The “Name” attribute.

Type¶: The “Type” attribute.

Unit¶: The “Unit” attribute.

shape¶

The Array’s dimensions. If the shape described by the Dim child elements is not consistent with the shape of the internal array object then ValueError is raised.

When assigning to this property, the internal array object is adjusted as well, and an error will be raised if the re-shape is not allowed (see numpy documentation for the rules). If the number of dimensions is being changed, and the Array object requires additional Dim child elements to be added, they are created with higher ranks than the existing dimensions, with no Name attributes assigned; likewise if Dim elements need to be removed, the highest rank dimensions are removed first. NOTE: Dim elements are stored in reverse order, so the highest rank dimension corresponds to the first Dim element in the XML tree.

NOTE: the shape of the internal numpy array and the shape described by the Dim child elements are only weakly related to one another. There are some sanity checks watching out for inconsistencies, for example when retrieving the value of this property, or when writing the XML tree to a file, but in general there is no mechanism preventing sufficiently quirky code from getting the .array attribute out of sync with the Dim child elements. Calling code should ensure it contains its own safety checks where needed.

tagName = 'Array'¶

validchildren = frozenset({'Dim', 'Stream'})¶

Methods Documentation

classmethod build(name, array, dim_names=None, encoding='Text')¶

Construct a LIGO Light Weight XML Array document subtree from a numpy array object.

Example:

>>> import numpy, sys
>>> a = numpy.arange(12, dtype = "double")
>>> a.shape = (4, 3)
>>> Array.build("test", a).write(sys.stdout)
<Array Type="real_8" Name="test:array">
        <Dim>3</Dim>
        <Dim>4</Dim>
        <Stream Type="Local" Delimiter=" ">
                0 3 6 9
                1 4 7 10
                2 5 8 11
        </Stream>
</Array>

classmethod getArraysByName(elem, name)¶

Return a list of arrays with name name under elem.