# pyxfbp

- Xfbp
- Graphs
- Graph
- Groups
- Group
- Sets
- Set
- SetVector
- Vector
- ZComponents
- Weights
- Weight
- NewGroup
- LineStyle
- FillStyle
- FontStyle
- SymbolStyle
- Frame
- Paper
- World
- View
- Axis
- Legend
- Title
- SubTitle
- XAxisLabel
- YAxisLabel
- OppositeXAxisLabel
- OppositeYAxisLabel
- TextBoxes
- TextBox
- TicMarks
- TicMajor
- TicMinor
- TicLabels
- UserTics
- Tic
- Lines
- Line
- Ellipses
- Ellipse

This is the one and only module to manipulate the data of xfbp.

## Xfbp

class `Xfbp`

  This is the main class of `pyxfbp`. It provides access to a few basic functions and to all `Graphs` via the property `G`. An instance of this class called xfbp and all members of xfbp are loaded into the namespace when the editor is activated (see Sec General). Note, that `G` should not be overwritten by doing something like:

      G="Helloworld" # now G is no longer a Graphs object but xfbp.G still is

  `killall`()

    remove everything and reset to initial state (a single empty graph)

  `printto`(filename, dpi=300, quality=0.85)

    print to file called filename with dot-per-inch set to dpi and with quality. Two file types are available: `eps` and `png`. dpi and quality only apply to `png`-files.

    Parameters: | filename (str) – a filename including extension: `png` or `eps` dpi (int) – dots per inch quality (float) – compression quality in [0,1]
    Returns: | self to allow call chaining as in `Xfbp.printto(...).setSomethingElse(...)`
    Return type: | `Xfbp`

  `arrange`(paperwidth=800.0, Nx=1, leftgap=0.1, rightgap=0.1, hgap=0.1, Ny=1, topgap=0.1, bottomgap=0.1, vgap=0.1, aspectratio=1.5, commonxaxis=True, commonyaxis=True, commontitle=True)

    Arrange the first Nx * Ny graphs in a grid. The graphs can already exist. Otherwise they are created. The graph ids run row by row. leftgap/rightgap are the spaces left/right of the first/last viewbox (`View`) in percent*100 of the paperwidth. topgap/bottomgap work similar. hgap/vgap are the in-between gaps in percent*100 of the individual viewbox width/height. aspectratio determines the individual viewbox’s aspect ratio. The paperheight depends on all these settings.

    Note, that the point scale of the graphs depends on the paperwidth. You need to experiment with the gap values a bit to get the labels/ticmarks/titles properly displayed in the page. If commonxaxis is `True` the in-between-viewboxes tic labels and xaxis labels are switched off and in each column the world x axis is made equivalent. Similarily, for commonyaxis. For this to work the arrange command must be issued after setting up the graphs. If commontitle is `True` the titles in between rows are switched off. Example:

        killall()
        arrange(800,2,0.12,0.05,0.1,   2,0.1,0.12,0.1,   1, 1,1,1)

    Parameters: | paperwidth (float) – in pt (A4 is 595 x 842) Nx (int) – number of columns leftgap (float) – in percent*100 of paperwidth rightgap (float) – in percent*100 of paperwidth hgap (float) – in percent*100 of viewbox width Ny (int) – number of rows topgap (float) – in percent*100 of paperheight bottomgap (float) – in percent*100 of paperheight vgap (float) – in percent*100 of viewbox height aspectratio (float) – commonxaxis (int) – 0 or 1 (`False` or `True`) commonyaxis (int) – 0 or 1 (`False` or `True`) commontitle (int) – 0 or 1 (`False` or `True`)
    Returns: | self to allow call chaining as in `Xfbp.arrange(...).setSomethingElse(...)`
    Return type: | `Xfbp`

  `setMouseHook`(button, script)

    setup a miniscript to be executed at mouse click of button Currently button is always ‘left’. script should contain valid python code and it must be valid in the context it is exceuted in (objects refered to must exist) (see `Xfbp.cursor`)

    Parameters: | button (str) – on which mouse button click to install the hook currently only ‘left’ works script (str) – a valid python mini script
    Returns: | self to allow call chaining as in `Xfbp.setMouseHook(...).setSomethingElse(...)`
    Return type: | `Xfbp`

  `G`

    return a Graphs object, which provides access to all graphs. The following two are nearly equivalent: `G[1]` and `Graph(1)` The former allows deletion, E.g. `del G[1]` will delete the graph with id 1. Use it as in:

        G[1].world.x=(-2,3)

    Type: | `Graphs`

  `paper`

    return a Paper object to set its dimensions.

    Type: | `Paper`

  `cursor`

    return current cursor position as a tuple (x,y). This is usefull inside a mouse click hook. Note, that the graph must be the current graph to get expected results:

        setMouseHook('left','''
        G[1].title.toggle()
        c=cursor
        gr=G[1].Gr[1].on()
        s=gr.S[4].on()
        s.x=[c[0],c[0]]
        s.y=[G[1].world.ymin,G[1].world.ymax]
        print s.x
        print s.y
        ''')

    Type: | 2-tuple

## Graphs

class `Graphs`

  `Graphs` represents all `Graph` s. `Xfbp` returns an instance of `Graphs` via the property `G`. `G` is also loaded into the namespace such that we can just use it without the `Xfbp` object. It behaves a bit like a python `dict` with `int` keys and a bit like a `list`.

  `G[id]` represents a reference to graph with id, it does not mean that this graph exists. On usage of `G[i]` errors are raised when the graph was not yet created. A graph can be created by using a `read` command (`G[1].read(...)`) or by switching its visibility as in `G[i].active=1` or `G[i].on()`. Generally, `on`, `off`, `toggle` and the property `active` will physically create a graph.

  `len(G)` is the number of graphs not the highest id. Graphs can be created in any order of ids. The order of graphs determines the plotting order.

  You can do the following:

      # this iterates over all EXISTING graphs
      for g in G:
         g.title.off()

      G[4].active=1 # switch on graph number 4

      g=G[6] # g represents a reference to graph 6

      # if it does not exist yet errors will be raise when you use it
      # but you can write
      g.active=True # now it exists and is visible

      # iterate via index
      for i in range(len(G)):
          print G.at(i).id

      #iterate over certain graph ids
      for id in [1,4,6]:
          G[id].title.off()

      # delete graph with id 4
      del G[4]

  `__delitem__`(id)

    you can delete a graph with a certain id:

        del G[2]

  `__len__`()

    `len(G)` returns the number of graphs not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G)):
            G.at(i)...

    Parameters: | i (int) – graph index (not id)
    Returns: | graph at index i
    Return type: | `Graph`

  `__getitem__`()

    `G[id]` returns the graph with a certain id:

        killall() # only graph 1 will exist after killall
        G[4].on() # switch on graph with id 4
        G[2].on() # switch on graph with id 2
        for g in G:
           print g   #now we have graphs 1,4 and 2

    `G[i] <==> G.__getitem__(i)`

  `__iter__`()

    you can iterate over all graphs:

        for g in G:
            print g.id

  `next`()

    for the iterator interface, see `__iter__`

  `lastid`

    the highest id among all existing graphs (not the number of graphs):

        G[G.lastid+1].on()# definitely a new graph

    Type: | int

## Graph

class `Graph`(graphid)

  This class represents a single graph. This class can be used by itself to address a particular graph with id graphid:

      Graph(1) # represents graph 1

  Another way would be:

      G[1]

  To delete a graph there is only one way:

      del G[1]

  Parameters: | graphid (int) – the graphid as shown in the GUI

  `read`(type, filename, groupid=0)

    read file called filename of intended type type into the graph (and optionally into a specific group in this graph) and return a `list` of `NewGroup` object, which provide easy access to all newly created groups and sets. The return value can be ignored. If a groupid was given the group will be created if it does not exist.

    The type can be:

    > ‘xny’
    >   Data sets are read, assuming that an empty line starts a new data block. In each multi column block with N columns the first column is and the other columns are , resulting in sets for each data block in the file. All sets end up in a new group.
    > ‘xynw’
    >   The first column of each block is . The second is and the following columns are weights.
    > ‘xynz’
    >   First comes a block of -values, each line one value, followed by a blank line. Then comes a similar block of -values followed by a blank line. Finally a block of -values, one value per line. The resulting plot will be a density plot where the -values define the color.
    > ‘band’
    >   An FPLO band structure file.
    > ‘bandweight’ or ‘bandweights’
    >   An FPLO band weights file.
    > ‘akbl’
    >   An FPLO Bloch-Spectral-Density file. (CPA FPLO5, pyfplo.Slabify)

    Examples for return value:

        gr=G[1].read('xny','grid.dat')[0].group
        # new gr is a Group object

        ret=G[1].read('xny','grid.dat')
        for r in ret:
            for s in r.sets:
                print 'new group',r.group.id,'new set',s.id

    Parameters: | type (str) – file type marker: ‘xny’, ‘band’, ‘bandweight’, ‘xynw’ ,’xynz’ ‘akbl’ filename (str) – the filename groupid (int) – optionally, read into a specific group
    Returns: | a list of all newly created groups and sets
    Return type: | list of `NewGroup`

  `on`()

    switch graph on

    Returns: | self to allow call chaining as in `Graph.on(...).setSomethingElse(...)`
    Return type: | `Graph`

  `off`()

    switch graph off

    Returns: | self to allow call chaining as in `Graph.off(...).setSomethingElse(...)`
    Return type: | `Graph`

  `toggle`()

    toggle graph visibility

    Returns: | self to allow call chaining as in `Graph.toggle(...).setSomethingElse(...)`
    Return type: | `Graph`

  `autoscale`(what='all')

    autoscale graph using the currently set `World.offset`

    Parameters: | what (str) – ‘all’ ,’x’ or ‘y’
    Returns: | self to allow call chaining as in `Graph.autoscale(...).setSomethingElse(...)`
    Return type: | `Graph`

  `id`

    the graph id as shown in the GUI

    Type: | int

  `active`

    get/set if the graph is visible. A nonzero value is True zero is False.

    Type: | bool

  `Gr`

    return a Groups object, which provides access to all groupsof this graph.

    Type: | `Groups`

  `linewidthscale`

    get/set an overall line width scale for the graph. This affects all line widths.

    Type: | float

  `pointsizescale`

    get/set an overall point size scale for the graph. This affects font and symbol sizes and line widths.

    Type: | float

  `title`

    return a Title object

    Type: | `Title`

  `subtitle`

    return a SubTitle object

    Type: | `SubTitle`

  `xaxislabel`

    return a XAxisLabel object

    Type: | `XAxisLabel`

  `yaxislabel`

    return a YAxisLabel object

    Type: | `YAxisLabel`

  `oppositexaxislabel`

    return a OppositeXAxisLabel object

    Type: | `OppositeXAxisLabel`

  `oppositeyaxislabel`

    return a OppositeYAxisLabel object

    Type: | `OppositeYAxisLabel`

  `textboxes`

    return a TextBoxes object, which provides access to all textboxes of this graph.

    Type: | `TextBoxes`

  `legend`

    get/set a Legend object which represents the legendbox.

    Type: | `Legend`

  `world`

    get/set the World object of this graph.

    Type: | `World`

  `view`

    get/set the View object of this graph.

    Type: | `View`

  `xaxis`

    get/set the x-axis object of this graph.

    Type: | `Axis`

  `yaxis`

    get/set the y-axis object of this graph.

    Type: | `Axis`

  `xtics`

    return the x-ticmarks of this graph

    Type: | `TicMarks`

  `ytics`

    return the y-ticmarks of this graph

    Type: | `TicMarks`

  `usertics`

    return the irregular user defined tickmarks of this graph

    Type: | `UserTics`

  `lines`

    return a Lines object, which provides access to all Line shapes of this graph.

    Type: | `Lines`

  `ellipses`

    return an Ellipses object, which provides access to all ellipses shapes of this graph.

    Type: | `Ellipses`

## Groups

class `Groups`(graphid)

  The Groups object represents all `Group` s. It is organized id-based like `Graphs`. The groups need not be ordered with monotonous ids. The group order determines the plotting order. IDs are just the names of the groups in the GUI. Names should not change, thats why they cannot behave like linear indices. A groups object can be used standalone or probably better be obtained via the class hierarchy:

      G[1].Gr   # this is the Groups object of graph(id 1)
      Groups(1) # and this too

      G[1].Gr[2] # and this is the Group with id 2 in graph(id 1)
      Group(1,2) # and this too

      # lets do useful things, assuming we loaded some data
      gr=G[1].Gr[1]
      gr.useattributes=True
      gr.line.color=0xff # all sets in group(id 1) will be blue

      # We cannot straight forwardly copy groups, since there is an issue with
      # the way weightlabels are handled internally.
      # But we can do this:
      gr=G[1].Gr[1]
      G[1].Gr[2].on()
      for s in gr.S:
         G[1].Gr[2].S.append(s)
      # A note on weightlabels.
      # weightlabels are shared among the set of a bandweights/xynw plot
      # after our copy above we need to set weightlabels to a consistent state
      G[1].Gr[2].unifyWeightLabels()
      # this will make sure that the original group and the new group
      # have different weightlabel-data and that all sets in the group
      # have the same.

  Parameters: | graphid (int) – the graph id

  `__delitem__`(id)

    you can delete a group with a certain id:

        del G[1].Gr[2]

  `__len__`()

    `len(G[1].G)` returns the number of groups not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G[1].Gr)):
            G[1].Gr.at(i)...

    Parameters: | i (int) – group index (not id)
    Returns: | group at index i
    Return type: | `Group`

  `__getitem__`()

    `G[1].Gr[id]` returns the group with a certain id

    `G[1].Gr[i] <==> G[1].Gr.__getitem__(i)`

  `__iter__`()

    you can iterate over all groups:

        for gr in G[1].Gr:
            print gr.id

  `next`()

    for the iterator interface, see `__iter__`

  `new`()

    create and return a new Group

    Returns: | a new Group
    Return type: | `Group`

  `len`

    return the number of groups not the highest id

    Type: | int

  `lastid`

    the highest id among all existing groups of this graph (not the number of groups)

    Type: | int

## Group

class `Group`(graphid, groupid)

  A group is a collection of `Sets`. They allow easy application of collective properties on many sets as it occurs in band structure plots. The `Graph.read` method will create `Group` s for the new `Set` s in a reasonable fashion. If needed all sets can be displayed with identical properties via the `useattributes` flag. Similarily, `Weight` properties can also be accessed From groups. You can access a group through the `Groups` property of a `Graph`:

      G[1].Gr[2] # this is group(id 2) in graph(id 1)
      Group(1,2) # is the same

  Parameters: | graphid (int) – the graph id groupid (int) – the group id

  `on`()

    switch group on

    Returns: | self to allow call chaining as in `Group.on(...).setSomethingElse(...)`
    Return type: | `Group`

  `off`()

    switch group off

    Returns: | self to allow call chaining as in `Group.off(...).setSomethingElse(...)`
    Return type: | `Group`

  `toggle`()

    toggle the group’s visibility

    Returns: | self to allow call chaining as in `Group.toggle(...).setSomethingElse(...)`
    Return type: | `Group`

  `setWeightsStyle`(style='dots', factor=1, min=0.2, max=6, showinlegend=True)

    this is another interface to the weight… properties. A prototype of this method can be inserted from the editor insert menu.

    Parameters: | style – ‘dots’, ‘connected’ or ‘individual’ see(`weightstyle`) factor (float) – see `weightfactor` min (float) – see `weightmin` max (float) – see `weightmax` showinlegend (int) – see `showinlegend`
    Returns: | self to allow call chaining as in `Group.setWeightsStyle(...).setSomethingElse(...)`
    Return type: | `Group`

  `unifyWeightLabels`()

    This function will only be needed in rare cases, since all `Graph.read` commands already call this internally. One case, in which it is needed is when a `xynw` sets are created by script.

    If all sets in this group have the same number of weights we can unify the group such that the groups and all it’s sets refer to the same weight labels.

    Returns: | self to allow call chaining as in `Group.unifyWeightLabels(...).setSomethingElse(...)`
    Return type: | `Group`

  `id`

    the group’s id

    Type: | int

  `graph`

    return the graph, the group is in

    Type: | `Graph`

  `active`

    get/set if the group is visible. A nonzero value is True, zero is False.

    Type: | bool

  `S`

    this gives access to all sets of the group

        G[1].Gr[1].S[2].line.color=0xff0000
        G[1].Gr[1].S[2].line.width=2
        #
        G[1].Gr[1].S[2].line=LineStyle(color=0xff0000,width=2,style='Dot')

    Type: | `Sets`

  `W`

    this gives acces to all weights. This is usefull in conjunction with `useattributes`. See also `Sets.W`.

        G[1].Gr[1].W[1].off()
        G[1].Gr[1].W[5].on().setStyle(...)
        G[1].Gr[1].W[5].color=0xff

    Type: | `Weights`

  `useattributes`

    if nonzero/`True`, the group’s attributes will be used for each set of the group. When switched off, each set’s individual properties will be used. This flag is used e.g. when band structures are loaded.

    Type: | bool

  `line`

    get/set the linestyle.

    Type: | `LineStyle`

  `legend`

    a group can be displayed as a single legend entry. This is usefull in conjunction with `useattributes`.

    Type: | str

  `comment`

    get/set the ‘set-comment’ of the group. Set-comments denote, where the data came from. This is mostly set by file-loading routines.

    Type: | str

  `showinlegend`

    get/set if this group is shown in the legend box.

    Type: | bool

  `symbol`

    get/set the symbolstyle. Not used for `Weight` s, which have their own limited settings.

    Type: | `SymbolStyle`

  `weightstyle`

    get/set the style of the weights

    ‘dots’ | one filled circles for each data point
    ‘connected’ | connect the circles by linear intepolation
    ‘individual’ | each weight can have its own symbol

    Type: | str

  `weightfactor`

    get/set the weight factor. All weights are scaled by this factor, before applying `weightmax` and `weightmin`. (This is somehow superfluous, but usefull anyway).

    Type: | float

  `weightmin`

    get/set the weight symbol size, under which no symbols will be plotted. This depends on `weightmax` since it scales everything up. It actually also depends on other scales, so just do trial & error for the desired result.

    Type: | float

  `weightmax`

    get/set the symbol size, which represents a weight value of 1. weightmax is in a scale like font sizes.

    Type: | float

  `showweightsinlegend`

    get/set if weight legend entries are shown.

    Type: | bool

  `usertics`

    irregular user defined tickmarks

    Type: | `UserTics`

## Sets

class `Sets`(graphid, groupid)

  The Sets object gives access to all sets of a `Group`. It is ID bases as `Graphs`. The Sets class allows access to the sets, deletion and copying of sets:

      # access to set 1
      G[1].Gr[1].S[1].line.color=0xff

      # copy set 1 to set 3
      G[1].Gr[1].S[3]=G[1].Gr[1].S[1]

      # delete set 1
      del G[1].Gr[1].S[1]

  Parameters: | graphid (int) – the graph id groupid (int) – the group id

  `__delitem__`(id)

    you can delete a set with a certain id:

        del G[1].Gr[1].S[1]

  `__len__`()

    `len(G[1].Gr[1].S)` returns the number of sets not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G[1].Gr[1].S)):
            G[1].Gr[1].S.at(i)...

    Parameters: | i (int) – set index (not id)
    Returns: | set at index i
    Return type: | `Set`

  `__getitem__`()

    use as in in: print x[i]

  `__iter__`()

    you can iterate over all sets:

        for s in G[1].Gr[1].S:
            s.line.color=0xff

  `next`()

    for the iterator interface, see `__iter__`

  `new`(s=None)

    create and return a new set. If argument s is a `Set`, copy it:

        killall()
        gr=G[1].Gr[1]
        s=gr.S[1].on()
        s.x=[-2,-1,0,1,2,3,4]
        s.y=s.x**2
        s.line.color=0xff
        # new set - copy
        s=gr.S.new(s)
        s.x-=1
        s.line.color=0xcc00
        G[1].autoscale()

    Parameters: | s (`Set`) – an optional set to copy into the new set
    Returns: | a new set
    Return type: | `Set`

  `append`(s)

    Parameters: | s (`Set`) – an existing set
    Returns: | self to allow call chaining as in `Sets.append(...).setSomethingElse(...)`
    Return type: | `Sets`

    append set s to the sets, the set is hard copied, such that the original and the new set are physically distinct with the exception of weightlabel-data. The copied set shares the same weightlabels-data with the source set. This means that changing the name of a weight in the newly copied set will change the name in the source set as well. See `Group.unifyWeightLabels`.

  `len`

    return the number of sets not the highest id

    Type: | int

  `lastid`

    the highest id among all existing sets of this group (not the number of sets)

    Type: | int

## Set

class `Set`(graphid, groupid, setid)

  The Set class represents an actual data set. It can be accessed from the `S` property of a `Group` or directly:

      G[1].Gr[2].S[3].color=0xff
      # or
      Set(1,2,3).color=0xff

  Parameters: | graphid (int) – the graph id groupid (int) – the group id setid (int) – set set id

  `on`()

    switch set on

    Returns: | self to allow call chaining as in `Set.on(...).setSomethingElse(...)`
    Return type: | `Set`

  `off`()

    switch set off

    Returns: | self to allow call chaining as in `Set.off(...).setSomethingElse(...)`
    Return type: | `Set`

  `toggle`()

    toggle the set’s visibility

    Returns: | self to allow call chaining as in `Set.toggle(...).setSomethingElse(...)`
    Return type: | `Set`

  `setWeightsStyle`(style='dots', factor=1, min=0.2, max=6, showinlegend=True)

    this is another interface to the weight… properties. A prototype of this method can be inserted from the editor insert menu.

    Usually you will use `Group.useattributes` and set weight properties from the group.

    Parameters: | style – ‘dots’, ‘connected’ or ‘individual’ see(`weightstyle`) factor (float) – see `weightfactor` min (float) – see `weightmin` max (float) – see `weightmax` showinlegend (int) – see `showinlegend`
    Returns: | self to allow call chaining as in `Set.setWeightsStyle(...).setSomethingElse(...)`
    Return type: | `Set`

  `convolute`(width)

    replace current set data by a convolution with Gaussians of a given width.

    Parameters: | width (float) – the Gaussin width
    Returns: | self to allow call chaining as in `Set.convolute(...).setSomethingElse(...)`
    Return type: | `Set`

  `integrate`()

    replace the current set by a running integral of the data. The last value of the y-data is the total integral (if needed):

        s=G[1].Gr[1].S[1].integrate() # returns the set itself
        print 'integral',s.y[-1]

    Returns: | self to allow call chaining as in `Set.integrate(...).setSomethingElse(...)`
    Return type: | `Set`

  `moment`(order, interval=None, normalized=True)

    calculate the order-th moment of the y-data over the whole x-data interval (if interval is `None` or missing) or over a given interval.

    If normalized is `True` these are normalized moments , hence . The second moment corrected for the center of gravity is defined as .

    Otherwise, they are unnormalized ,

    The unnormalized moment of order 0 is the same as the integral:

        gr=G[1].Gr[1]
        s=gr.S[1] # assume it exists
        s2=gr.S.new(s)
        s.integrate()
        m=s2.moment(0,normalized=False)
        print s.y[-1],m

    Example:

        import numpy as np

        killall()
        g=G[1]
        gr=g.Gr[1].on()
        N=1000
        a=0.5
        x0=-0.6
        x1=1.6
        w=0.2
        s=gr.S[1].on()
        # s1 length N
        s.x=Vector(N,x0,x1)
        s.y=np.exp(-((s.x-a)/w)**2/2)*3
        m1=s.moment(1,[x0,x1])
        m2=s.moment(2,[x0,x1])
        # calculate the normalized width
        wi=np.sqrt(m2-m1**2)
        t=g.textboxes.new()
        t.text='calculated width={} input width={}'.format(wi,w)

        gr.usertics.on()
        gr.usertics.append(Tic(type='xmajor',position=m1,label='m1',
                labelside='Opposite',length=1,line=LineStyle(style='Solid')))\
            .append(Tic(type='xmajor',position=m1+wi,label='wi',
                labelside='Opposite',length=1,line=LineStyle(style='Dash')))\
            .append(Tic(type='xmajor',position=m1-wi,label='wi',
                labelside='Opposite',length=1,line=LineStyle(style='Dash')))

        g.title.text='Moment example'
        g.title.restriction=('y',0.02)
        g.autoscale()

    Parameters: | order (int) – the requested order interval (2-tuple or 2-sequence) – x-interval on which to calculate normalized (int) – normalized or not
    Returns: | the moment of requested order
    Return type: | float

  `bspline`(order, derivorder, xvector=None)

    Replace this set’s y-data with the derivorder-th derivative of the bspline of order order, evaluated at the set’s x-data if xvector is missing (or `None`), or on the provided xvector, in which case the set’s x-data is set to xvector

    Parameters: | order (int) – the requested spline order derivorder (int) – the requested derivative order xvector (None, seqence(list, `Vector`, tuple, numpy.ndarray) of float) – a possible alternative x-mesh
    Returns: | self to allow call chaining as in `Set.bspline(...).setSomethingElse(...)`
    Return type: | `Set`

  `adjustDensPlot`()

    adjust data range settings according to a guess for the current `zcomponent`. Affected are `scalemax` and `z0`. See Set Dialog.

    Returns: | self to allow call chaining as in `Set.adjustDensPlot(...).setSomethingElse(...)`
    Return type: | `Set`

  `id`

    the set’s id

    Type: | int

  `group`

    return the group, the set is in

    Type: | `Group`

  `graph`

    return the graph, the set is in

    Type: | `Graph`

  `active`

    get/set if the set is visible. A nonzero value is `True`, zero is `False`.

    Type: | bool

  `line`

    get/set the linestyle.

    Type: | `LineStyle`

  `legend`

    get/set what is displayed in the legend.

    Type: | str

  `comment`

    get/set the “set-comment” of the set. Set-comments denote, where the data came from. This is mostly set by file-loading routines.

    Type: | str

  `showinlegend`

    get/set if this set is shown in the legend box.

    Type: | bool

  `symbol`

    get/set the symbolstyle. Not used for `Weight` s, which have their own limited settings.

    Type: | `SymbolStyle`

  `interpolationdepth`

    get/set the interpolation depth for density plots (xynz plots). A density plot can have a limited number of data points (pixels) due to resource restrictions. These data can be interpolated to give a smoother picture. interpolationdepth determines on how many sub pixels the data re-interpolated. See Set Dialog.

    Type: | int

  `scalemin`

    set the lower cutoff for density plots. (see Set Dialog)

    Type: | float

  `scalemax`

    set the upper cutoff for density plots. (see Set Dialog)

    Type: | float

  `z0`

    data below this z-value will be considered background in grid/density plots (see Set Dialog)

    Type: | float

  `databackgroundcolor`

    the data background color in grid/density plots. (see Set Dialog)

    Type: | int

  `zpower`

    set the power law for mapping of z-values onto colormaps for grid/density plots (see Set Dialog)

    Type: | int

  `colormap`

    get/set the colormap for density plots. (see Set Dialog)

    A colormap can be a

    > a name (str)

    >   of a predefined map

    >   > ‘Terrain’ | ‘RainBow’ | ‘Magma’ | ‘Inferno’ | ‘Hot’ | ‘Heat’
    >   > ‘Spring’ | ‘Summer’ | ‘Autumn’ | ‘Winter’ | ‘Gnuplot’ | ‘Seismic’
    >   > ‘Rainbow2 | ‘Rainbow3’ |  |  |  |

    > a tuple
    >   of two colors which are RGB-interpolated between e.g. `(0xff00,0xff0000)`
    > a colormap which has the shape
    >   `[ [z0,color0], [z1,color1] ,...,interpolrgb]` where zi should be in [0,1] and monotonous and colori are hex numbers representing rgb colors. interpolrgb must evaluate to `bool` and determines the interpolation space.

    The getter returns a full colormap. Example:

        s.colormap=[
          [ 0.0 , 0x0ff ] ,
          [ 0.333333333333 , 0xff00dd ] ,
          [ 0.666666666667 , 0xff0000 ] ,
          [ 1.0 , 0xffff00 ] ,
          True
         ]

    Type: | str or sequence

  `weightstyle`

    get/set the style of the weights

    Usually you will use `Group.useattributes` and set weight properties from the group.

    > ‘dots’ | individual filled circles for each data point
    > ‘connected’ | connect the circles by linear intepolation
    > ‘individual’ | each weight can have its own symbol

  `weightfactor`

    get/set the weight factor. Usually you will use `Group.useattributes` and set weight properties from the group.

    All weights are scaled by this factor, before applying `weightmax` and `weightmin`. (This is somehow superfluous, but usefull anyway).

    Type: | float

  `weightmin`

    get/set the weight symbol size, under which no symbols will be plotted. Usually you will use `Group.useattributes` and set weight properties from the group.

    This depends on `weightmax` since it scales everything up. It actually also depends on other scales, so just do trial & error for the desired result.

    Type: | float

  `weightmax`

    get/set the symbol size, which represents a weight value of 1. weightmax is in a scale like font sizes. Usually you will use `Group.useattributes` and set weight properties from the group.

    Type: | float

  `showweightsinlegend`

    get/set if weight legend entries are shown. Usually you will use `Group.useattributes` and set weight properties from the group.

    Type: | bool

  `W`

    this gives acces to all weights. Usually you will use `Group.useattributes` and set weight properties from the group.

        G[1].Gr[1].S[1].W[1].off()
        G[1].Gr[1].S[1].W[5].on().setStyle(...)
        G[1].Gr[1].S[1].W[5].color=0xff

    Type: | `Weights`

  `type`

    get/set data type. Possible values:

    > ‘xy’
    >   y=function(x), x can be non monotonous
    > ‘xynw’
    >   y=function(x), additional n weights w=weightfunc(x) are defined
    > ‘xynz’.
    >   z=function(x,y), there can be several components i.e. several z(x,y)

    Warning: usually one does not need to set this. It can leave a confusing state.

    Type: | str

  `zcomponent`

    get/set which zcomponent (densplot, xynz type) is plotted. This is a zero-based index. The first component is `zcomponent==0`. See Set Dialog.

    Type: | int

  `x`

    get/set the vector of the abscissa or x-values. You can use `Vector`, which is used to allow standard arithmetic. It is mostly a class for intermediate results:

        s=G[1].Gr[1].S[1]
        s.x=Vector(100,-2.,10.) # !!! note, that N is first argument not last
                                # as for numpy.linspace !!!

        s.x*=0.529177
        s.y=((s.x+2)*3)**2  # intermediate results are Vector instances

        #or
        import math as m
        s.y=map(m.sin,s.x) # awkward but working if numpy is not available

        # or do this
        for i,x in enumerate(s.x):
           s.y[i]=m.sin(x)

    You can freely convert to and from numpy.ndarray:

        import numpy as np
        arr=np.array(G[1].Gr[1].S[1].x)

    set from numpy array like this:

        import numpy as np
        G[1].Gr[1].S[1].x=arr

    For example

        import numpy as np
        s=G[1].Gr[1].S[1]
        s.x=np.linspace(-2.,10.,100)
        s.y=s.x**2  # intermediate Vector instance

        #or simply

        s.x*=0.529177

        s.y=np.sin(s.x)

        #or
        for i,x in enumerate(s.x):
           s.y[i]=np.sin(x)

    Type: | `SetVector`

  `y`

    return the vector of the ordinate or y-values. See `x`.

    Type: | `SetVector`

  `z`

    get/set the z-components (densplot (xynz type) or band weights (xynw type)). You can set z-components in a block or access its individual data via `S[i].z[iw]`. ZComponents behaves differently for xynw and xynz data types.

    For xynw, each zcomponent represents one weight. So in general you have Nband sets and each set has Norbital weights. This is reflected by Norbital z-components for each set. `S[3].z[iw]` is the vector of weigths for set 3 and weight iw. `S[3].z[iw,ik]` is the weigth for set 3 and weight iw at k-point ik.

    You can set the z-components in bulk `S[3].z=arr`, where `arr` must be a sequence of Norbital sequences of length `len(S[i].x)` (Nk). All sets should have the same length. A 2d numpy array can be used for `arr`. In general the outer (first) dimension is Norbital and the second (inner) Nk: `S[3].z=[ [weight1],[weight2],...]`, where `weight1` … are sequences of Nk weights.

    If you construct xynw sets by yourself you need to call `Group.unifyWeightLabels` after the act, if you want the result to behave like a bandweights plot.

    Example:

        import numpy as np

        killall()

        gr=G[1].Gr[1].on()

        N=100
        x0=0.
        x1=np.pi

        for id in [1,2,3]: # 3 sets
            s=gr.S[id].on()
            s.x=np.linspace(x0,x1,N)
            s.y=np.cos(s.x*id)
            # set weight plot type
            s.type='xynw'
            # three weights
            s.z.len=3 # this is important to set up internal weightlabels
            # set at once
            s.z=[3*s.x,2*s.x,1*s.x] # assign list of three weight vectors
            # or
            w=np.array([3*s.x,2*s.x,1*s.x]) # we got some numpy array
            s.z=w # and assign it

            # or via indices
            for i in range(N):
                s.z[0,i]=3*np.abs(s.x[i]) # weight 1
                s.z[1,i]=2*np.abs(s.x[i]) # weight 2
                s.z[2,i]=1*np.abs(s.x[i]) # weight 3

        gr.unifyWeightLabels()
        gr.useattributes=1
        gr.setWeightsStyle(style='connected',factor=1,min=0.2,max=6,
         showinlegend=True)

        for w in gr.W:  w.on()

        gr.W[1].color=0xaa00
        gr.W[2].color=0xff00ff
        gr.W[3].color=0xffff00

        G[1].autoscale()

    For the xynz data type the ZComponents represent Nc z(x,y) functions, where Nc is `z.len`. Only one can be plotted at once, which is given by `zcomponent`. Some FPLO programs produce multiple z-components (ugly, I know). Each z-component contains `s.x.len*s.y.len` values z(x,y). The data can be accessed in bulk: s.z returns a list of Nc flat sequences, where each sequence is one component. In these flat sequences the x-coordinate runs first. `s.z` can be set from such a list or from a numpy array with `shape=(Nc,len(s.x)*len(s.y))`.

    Another option is to obtain the ic-th zcomponent (still flat) via `s.z[ic]` this returns or assigns one whole z(x,y) from a flat sequence, where x runs first.

    The last option is to access each element separately via `s.z[ic,ix,iy]`. This option is the slowest. To illustrate we give an example, where all possibilities are shown:

        import numpy as np

        def f(x,y):
            return np.cos(x)+np.cos(x*(x**2+y**2))

        killall()

        g=G[1]
        gr=g.Gr[1].on()
        s=gr.S[1].on()
        s.type='xynz' # set the data type

        Nx=200
        Ny=100
        # set the x and y values from numpy arrays
        s.x=np.linspace(-np.pi*3,np.pi*3,Nx)
        s.y=np.linspace(-np.pi*3,np.pi*3,Ny)

        # the number of components
        s.z.len=1

        # construct a flat numpy array containing z(x,y)
        # x runs first
        w=np.array([f(x,y) for x in s.x for y in s.y ])

        # assign in bulk
        s.z=[w]

        # or assign single component
        s.z[0]=w

        # or assign each data point separately
        for i,xx in enumerate(s.x):
            for j,yy in enumerate(s.y):
                s.z[0,i,j]=f(xx,yy)

        # which component to plot
        s.zcomponent=0
        # setup some default scalemax, z0
        s.adjustDensPlot()
        # not good enough
        s.z0=-2
        # pick colormap
        s.colormap='heat'

        # make it smoother
        s.interpolationdepth=2

        #and
        g.autoscale()

        g.title.text='Illusion'

    Type: | `ZComponents`

## SetVector

class `SetVector`(graphid, groupid, setid, xyz, ic=-1)

  A SetVector object is returned by `Set.x`, `Set.y` and `z[]` for some versions of indexing. It represents the x-data, y-data or z-component data (depending on the data `type`). You can assign a list or 1d `numpy.ndarray` or change single values. You can get/set the size via `len`. In this case there are two cases. For `Set.type` ‘xy’ and ‘xynw’ the size of `Set.x` and `Set.y` are the same since it represents y=f(x). Chaning the `len` of either changes the length of the other. For ‘xynz’ data the `len` of x and y can be different, since both are independent variables.

  If the SetVector represent a z-component of a ‘xynw’ type, the length is the same as `x.len` and `y.len`. Setting the `x.len` is automatically setting the z-component length.

  If the SetVector represents a z-component of a ‘xynz’ type (density plot) the `s.z.len` is `s.x.len*s.y.len`.

  Instead of individual element access `x[12]=7` one can assign a sequence (see `Set.x`). In the latter case automatic resizing will take place.

  Parameters: | graphid (int) – the graph id groupid (int) – the group id setid (int) – the set id xyz (str) – axis id ‘x’ or ‘y’ or ‘z’ ic (int) – if used: which z-component

  `__len__`()

    `len(...S[1].x)` returns the size of the vector (see also `len`)

  `__iter__`()

    you can iterate over a vector:

        su=0
        for d in G[1].Gr[1].S.x:
            su+=d
        su/=G[1].Gr[1].S.x.len

    This is NOT usefull for assignment.

  `next`()

    for the iterator interface, see `__iter__`

  `__getitem__`()

    return the i-th element:

        ...S[1].x[2]=...S[1].x[2]+0.1

  `__setitem__`()

    assign the i-th element:

        ...S[1].x[2]=...S[1].x[2]+0.1

  `__add__`()

    enable adding as in:

        s=G[1].Gr[1].S[1]
        s.x+=0.1
        s.x=s.x+2

  `__sub__`()

    enable sutraction as in:

        s=G[1].Gr[1].S[1]
        s.x-=0.1
        s.x=s.x-2

  `__mul__`()

    enable multiplication as in:

        s=G[1].Gr[1].S[1]
        s.x*=0.529177
        s.y=(s.x+2)*3

  `__div__`()

    enable division as in:

        print s.x/5 # same as [x/5 for x in s.x]
        print 5/s.x # same as [5/x for x in s.x]

  `__pow__`()

    enable power as in:

        s=G[1].Gr[1].S[1]
        s.y=s.x**2

  `__neg__`()

    enable unary minus:

        s=G[1].Gr[1].S[1]
        s.y=-s.x

  `__pos__`()

    enable unary plus:

        s=G[1].Gr[1].S[1]
        s.y=+s.x

  `__abs__`()

    abs(objects)

  `len`

    get/set the length of the vector

    Type: | int

## Vector

class `Vector`(size=0, x0=0, x1=0)

  Create a new Vector with size linearly spaced elements reaching from x0 to x1. This is a minimal implementation of a float vector, to obtain simple element wise list math for `SetVector` without compiling with numpy. It should be more or less invisible to the user that this class appears here and there.

  The point is that expressions like `s.x+2` must return a list with element wise arithmetic capabilities in order to be able to write `(s.x+2)*7`. Here the `s.x` is a `SetVector`. SetVector itself is not suited since it is a reference to real data and not data itself. We can implement `__add__` for SetVector to return the expression in parentheses as a `list`, but it must return more than a python `list` since `(..)*7` should also work. Ideally, we would return a `numpy` array, but this requires more dependencies. Numpy can still be used on this object as in

      X=Vector(10,0,1) #instead of np.linspace, X is a Vector
      Y=np.cos(X*2+3)

  However, it also works without numpy:

      from math import *
      s.x=Vector(10,0,1)
      s.y=map(cos,s.x+2)

      s.y+=0.1
      s.y=-((s.x+2)*7)**2

  Manipulate vector elements in the following way:

      v=Vector() # zero length
      v.len=10 # lenght 10
      v[2]=42  # element wise assignment
      print v[2] # __getitem__

      v=Vector() # zero length
      v.append(1)
      v.append(2)
      v.append(4) # v contains [1,2,4]

  Parameters: | size (int) – number of elements x0 (float) – first value x1 (float) – last value

  `__add__`()

    enable adding as in:

        s=G[1].Gr[1].S[1]
        s.x+=0.1
        s.x=s.x+2

  `__sub__`()

    enable sutraction as in:

        s=G[1].Gr[1].S[1]
        s.x-=0.1
        s.x=s.x-2

  `__mul__`()

    enable multiplication as in:

        s=G[1].Gr[1].S[1]
        s.x*=0.529177
        s.y=(s.x+2)*3

  `__div__`()

    enable division as in:

        v=Vector(5,1,5) # v=[1,2,3,4,5]
        print v/5 # [0.2,0.4,0.6,0.8,1]
        print 5/v # [5,2.5,1.666..,1.25,1]

  `__pow__`()

    enable power as in:

        s=G[1].Gr[1].S[1]
        s.y=s.x**2

  `__neg__`()

    enable unary minus:

        s=G[1].Gr[1].S[1]
        s.y=-s.x

  `__pos__`()

    enable unary plus:

        s=G[1].Gr[1].S[1]
        s.y=+s.x

  `__abs__`()

    enable absolute value:

        s=G[1].Gr[1].S[1]
        s.y=abs(s.x)

  `__len__`()

    `len(v)` returns the size of the Vector.

  `__getitem__`()

    return i-th item (float)

  `__setitem__`()

    assign a float to the i-th item

  `__iter__`()

    you can iterate over a Vector:

        v=Vector(11,0.,10.)
        su=0
        for x in v:
            su+=x
        su/=v.len

  `next`()

    for the iterator interface, see `__iter__`

  `append`(d)

    append d to the end of the Vector.

    Parameters: | d (float) – a new value
    Returns: | self to allow call chaining as in `Vector.append(...).setSomethingElse(...)`
    Return type: | `Vector`

  `len`

    get/set the size of the vector. After setting a larger len some elements can be uninitialized.

    Type: | int

## ZComponents

class `ZComponents`(graphid, groupid, setid)

  This class is returned by `z`. It can be used to manipulate the weigths (xynw type) or densplot functions z(x,y) (xynz type). Please read the doc for `z`.

  Parameters: | graphid (int) – the graph id groupid (int) – the group id setid (int) – the setid

  `__len__`()

    `len(s.z)` returns the number of z-components.

    > xynw
    >   Number of weigths
    > xynz
    >   Number of independent z(x,y) functions stored in the data

  `__getitem__`()

    indexing works the following way:

    > xynw

    > > `z[iw]` : the `iw`-th weight vector (length `s.x.len==s.y.len`) Note, that here `iw` is zero based, while weight ids start with id 1 (Sorry).

    > > `z[iw,ix]` : the `iw`-th weight at `xvalue[ix]` (a number)

    > xynz

    > > `z[ic]` : the whole `z[: , :]` for the `ic`-th component as flat vector, where `ix` runs first”

    > > `z[ic,ix,iy]` : `z[ix,iy]` for the `ic`-th component (a number)

  `__setitem__`()

    see `__getitem__`. When a certain index structure for __getitem__ returns a sequqence, assignment has also to occur from a sequence. If it returns a number you must assign a number.

    As an exception from this rule you can always assign a single number, which sets the whole sequence to this number if the index structure result in a sequence:

        s.z=0

  `len`

    get/set the number of z-components.

    > xynw
    >   this is the number of weights
    > xynz
    >   this is the number of independent z(x,y) functions stored in the data.

    see examples in `Set.z`.

    Type: | int

## Weights

class `Weights`(graphid, groupid, setid=0)

  The Weights class gives access to all available `Weigth` objects, which in turn determine the properties of plotted weights. As usual there is standalone and hierarchical acces. Weigths can be accessed from `Group` s or `Set` s:

      G[1].Gr[2].W # Weigths class of grap(id 1), group(id 2)
      Weights(1,2) # the same

      G[1].Gr[2].S[3].W # Weigths class of grap(id 1), group(id 2), set(id3)
      Weights(1,2,3)    # same

  A single `Weight` can be obtained by indexing, either with an `int` index or a `str` index. `int` indices are the weight number (one-based counting). `str` indices are the name of a weight. The name has to match exactly:

      G[1].Gr[2].W[5] # weight number 5
      G[1].Gr[2].W['Al(001)3p+0'] # a specific weight

  Note, that you can change the weight `name` in which case the new name can be used as index (the old no longer).

  Parameters: | graphid (int) – the graph id groupid (int) – the group id setid (int) – missing (group weigth access) or set id

  `__delitem__`(id)

    you can delete a weight with a certain id:

        del G[1].Gr[2].W[11]

  `__len__`()

    `len(G[1].Gr[2].W)` returns the number weights

  `__getitem__`()

    A single `Weight` can be obtained from an `int` index or a `str` index. `int` indices are the weight number (one-based counting). `str` indices are the name of a weight. The name has to match exactly.

  `__iter__`()

    you can iterate over all weights:

        for w in G[1].Gr[1].W:
            w.skip=3

  `next`()

    for the iterator interface, see `__iter__`

## Weight

class `Weight`(graphid, groupid, setorweightid, weightid=1)

  A funtion or set of functions can have associated weigths, which can be used for a fat-band plot. The Weight class determines the appearance of the individual weights in such a plot. If all sets of a group share the same weightlabel set the weight properties can be set from the group for all sets at once if `Group.useattributes` is `True`. This sharing is setup by the `Graph.read` methods. If the user creates weights on the fly `Group.unifyWeightLabels` will setup this sharing (see `Set.z`). Normal usage is:

      gr=G[1].Gr[1]
      gr.W[1].off()
      for id in [5,6,7]:
         gr.W[id].on()
         gr.W[id].skip=4
      gr.W[5].color=0xff0000
      gr.W[6].color=0xaa00
      gr.W[7].color=0xff

  If the class is accessed directly (`Weight(1,2,...)`) and called with three arguments they are: graphid, groupid, weightid. If called with four: graphid, groupid, setid, weightsid.

  Parameters: | graphid (int) – the graph id groupid (int) – the group id setorweightid (int) – set/weight id weightid (int) – weightid

  `on`()

    switch the weight on

    Returns: | self to allow call chaining as in `Weight.on(...).setSomethingElse(...)`
    Return type: | `Weight`

  `off`()

    switch the weight off

    Returns: | self to allow call chaining as in `Weight.off(...).setSomethingElse(...)`
    Return type: | `Weight`

  `toggle`()

    toggle the weight’s visibility

    Returns: | self to allow call chaining as in `Weight.toggle(...).setSomethingElse(...)`
    Return type: | `Weight`

  `setStyle`(style='square', color=255, skip=0, linewidth=1, fill=1)

    convenience method to set the style at once. `name` and `plotorder` must be set separately.

    Parameters: | style – see `style` color (int) – see `color` skip (int) – see `skip` linewidth (int) – see `linewidth` fill (int) – see `fill`
    Returns: | self to allow call chaining as in `Weight.setStyle(...).setSomethingElse(...)`
    Return type: | `Weight`

  `id`

    the weight id

    Type: | int

  `active`

    get/set if the Weight is visible

    Type: | bool

  `name`

    get/set the name of the weight.

    Type: | str

  `plotorder`

    get/set the plot order. Weights with higher plot order are plotted later.

    Type: | int

  `color`

    get/set the color as int. To print in hex form use e.g. `hex(...W[1].color)`. To set, use `W[1].color=0xff00ff` (magenta) (see Colors)

    Type: | int

  `skip`

    get/set how many data points are skiped before the next weight symbol is plotted. If there are many data points in the sets, which carry weights it might be advantageous to only plot a diluted number of weight symbols.

    Type: | int

  `style`

    get/set the weight style either from `int` or from `str` (If ‘individual’ weight style is set via `Group.weightstyle`/`Set.weightstyle`) The `str` version has short forms.

    > str | short | int | str | short | int | str | short | int
    > ‘none’ | ‘’ | 0 | ‘triangleup’ | ‘^’ | 4 | ‘plus’ | ‘+’ | 8
    > ‘circle’ | ‘o’ | 1 | ‘triangleleft’ | ‘<’ | 5 | ‘cross’ | ‘x’ | 9
    > ‘square’ | ‘q’ | 2 | ‘triangledown’ | ‘v’ | 6 | ‘star’ | ‘*’ | 10
    > ‘diamond’ | ‘d’ | 3 | ‘triangleright’ | ‘>’ | 7 |  |  |

    Type: | str/int

  `linewidth`

    get/set the line width of a weight symbol (If ‘individual’ weight style is set via `Group.weightstyle`/`Set.weightstyle`)

    Type: | float

  `fill`

    get/set if the the weight symbols are filled (If ‘individual’ weight style is set via `Group.weightstyle`/`Set.weightstyle`)

    Type: | bool

## NewGroup

class `NewGroup`(graphid, groupid)

  The NewGroup object is an element of the list returned by `Graph.read` and provides access to newly read `Group` s and `Set` s. This way one does not need not know, which groups/sets where created:

      # a simple case: non-spinpolarized or relativistic bandstructure
      #  (only 1 group)
      gr=G[1].read('band','+band')[0].group
      gr.line.color=0xff00

      # same but spin polarized
      grps=G[1].read('band','+band')
      gr=grps[0].group
      gr.line.color=0xff
      gr=grps[1].group
      gr.line.color=0xff00

      # another example
      grps=G[1].read('xny','+band') # note the xny type
      for r in grps:
          for s in r.sets:
             s.line.width=2
             s.legend='group {grid} set {sid}'.format(grid=r.group.id,sid=s.id)

  Parameters: | graphid (int) – the graph id groupid (int) – the group id

  `group`

    the new `Group` object

    Type: | `Group`

  `sets`

    the list of new `Set` objects

    Type: | list of `Set`

## LineStyle

class `LineStyle`(width=1, color=0, style='solid', extracolor=1)

  A LineStyle object is returned from other object’s properties such that we can change it:

      G[1].Gr[1].S[1].line.color=0xff00 # here line returns LineStyle

  Or we can create it separately and use it:

      l=LineStyle(width=1.5,color=0xff,style='Dash')

      for s in G[1].Gr[1].S:
         s.line=l

  Parameters: | width (float) – the line width color (int) – the line color style – see `style` extracolor (int) – see `extracolor`

  `width`

    get/set the line width

    Type: | float

  `color`

    get/set the line color as int(hex.) To print in hex form use e.g. `hex(...line.color)`. To set the color use `rim.color=0xff00ff` (see Colors).

    Type: | int

  `style`

    get/set the line style as int or str. Invalid numbers are folded back into the allowed range (modulus). Valid styles are defined below.

    > ‘none’ | 0 | ‘solid’ | 1 | ‘dash’ | 2
    > ‘dot’ | 3 | ‘dashdot’ | 4 | ‘dashdotdot’ | 5
    > ‘dotdashdash’ | 6 | ‘longdash’ | 7 | ‘longdashdot’ | 8
    > ‘longdashdotdot’ | 9 |  |  |  |
    > ‘dotlongdashlongdash’ | 10 |  |  |  |

    Type: | str/int

  `extracolor`

    get/set if separate line color is used for symbols. (in `SymbolStyle`)

    Type: | bool

## FillStyle

class `FillStyle`(active=1, color=16777215, extracolor=1)

  A FillStyle object is returned from other object’s properties such that we can change it:

      G[1].legend.frame.fill.color=0xff00 # here fill returns FillStyle

  Or we can create it separately and use it:

      fs=FillStyle(active=True,color=0xffffff,extracolor=True)

      for s in G[1].Gr[1].S:
         s.symbol.style='d'
         s.symbol.fill=fs

  Parameters: | active (int) – fill or not color (int) – fill color extracolor (int) – see `extracolor`

  `on`()

    switch filling on

    Returns: | self to allow call chaining as in `FillStyle.on(...).setSomethingElse(...)`
    Return type: | `FillStyle`

  `off`()

    switch filling off

    Returns: | self to allow call chaining as in `FillStyle.off(...).setSomethingElse(...)`
    Return type: | `FillStyle`

  `active`

    get/set if filling is active.

    Type: | bool

  `extracolor`

    get/set if separate fill color is used. (not used by all objects) If this property is used `extracolor=False` will trigger the use of the line color for filling. Otherwise `color` will be used.

    Type: | bool

  `color`

    get/set the fill color. To print in hex form use e.g. `hex(...fill.color)` Set it via `fill.color=0xff00ff` (see Colors)

    Type: | int/hex

## FontStyle

class `FontStyle`(size=12, subscriptscale=0.75, color=0)

  A FontStyle object is returned from other object’s properties such that we can change it:

      G[1].title.font.size=18

  Or we can create it separately and use it:

      ft=FontStyle(size=18,subscriptscale=0.75,color=0xff)

      for t in G[1].textboxes:
         t.font=ft

  Parameters: | size (int) – font size subscriptscale (float) – relative subscript font size scale color (int) – font color

  `color`

    get/set the color as int. To print in hex form use e.g. `hex(...rim.color)` Set color form as `font.color=0xff00ff` (see Colors)

    Type: | int/hex

  `size`

    get/set the font size.

    Type: | float

  `subscriptscale`

    get/set the relative scale of the subscripts font size compared to normal font size.

    Type: | float

## SymbolStyle

class `SymbolStyle`(style='none', size=12, line=None, fill=None)

  A SymbolStyle object is returned from `Set`/`Group` object’s such that we can change it:

      G[1].Gr[1].S[2].symbol.style='circle'

  Or we can create it separately and use it:

      sy=SymbolStyle(style='',size=12,
        line=LineStyle(style='Solid',width=1,color=0x0,extracolor=False),
        fill=FillStyle(active=False,color=0xffffff,extracolor=False))

      for s in G[1].Gr[1].S:
         s.symbol=sy

  Parameters: | style (str) – see `style` size (float) – symbol size line (`LineStyle`) – symbol’s line style fill (`FillStyle`) – symbol’s fill style

  `style`

    get/set the symbol style either as `int` or as `str`

    str | short | int | str | short | int | str | short | int
    ‘none’ | ‘’ | 0 | ‘triangleup’ | ‘^’ | 4 | ‘plus’ | ‘+’ | 8
    ‘circle’ | ‘o’ | 1 | ‘triangleleft’ | ‘<’ | 5 | ‘cross’ | ‘x’ | 9
    ‘square’ | ‘q’ | 2 | ‘triangledown’ | ‘v’ | 6 | ‘star’ | ‘*’ | 10
    ‘diamond’ | ‘d’ | 3 | ‘triangleright’ | ‘>’ | 7 |  |  |

    Type: | str/int

  `size`

    get/set the symbol size.

    Type: | float

  `line`

    get/set the line style of the symbol. If `LineStyle.extracolor` is `False` the line color will be the same as the color of the `Set.line` style.

    Type: | `LineStyle`

  `fill`

    get/set the fill style of the symbol. If `FillStyle.extracolor` is `False` the fill color will be the same as the color of the `Set.line` style.

    Type: | `FillStyle`

## Frame

class `Frame`(active=1, borderspacing=0.2, rim=None, fill=None)

  A Frame object is returned e.g. by `Legend` or `TextBox`. It can be manipulated or use standalone for assignment:

      G[1].legend.frame.off()

      Legend(1).on()\
      .setFrame(Frame(active=1,borderspacing=0.4,
          rim=LineStyle(style='Solid',width=1,color=0x0,extracolor=True),
          fill=FillStyle(active=True,color=0xffffff,extracolor=True)))

  Parameters: | active (int) – is the frame visible? borderspacing (float) – see `borderspacing` rim (`LineStyle`) – rim line style fill (`FillStyle`) – frame fill style

  `on`()

    show the frame

    Returns: | self to allow call chaining as in `Frame.on(...).setSomethingElse(...)`
    Return type: | `Frame`

  `off`()

    don’t show the frame

    Returns: | self to allow call chaining as in `Frame.off(...).setSomethingElse(...)`
    Return type: | `Frame`

  `toggle`()

    toggle the frame’s visibility

    Returns: | self to allow call chaining as in `Frame.toggle(...).setSomethingElse(...)`
    Return type: | `Frame`

  `active`

    get/set if the frame is visible

    Type: | bool

  `borderspacing`

    get/set the space between the rim and the content.

    Type: | float

  `rim`

    get/set the rim line style. The getter returns a reference object such that changing it changes the object which owns rim. The setter makes a hard assignment of the rim data of the underlying object. The reference stays intact:

        fr=G[1].textboxes[1].frame # fr refers to the textbox frame

        ls=fr.rim # ls and fr are references ...

        ls.width=2 # changes width in ls, fr and textbox(id 1)

        fr.rim=LineStyle() #will hard set new rim data

        ls.width=3 # now ls,fr and textbox have width 3

    Type: | `LineStyle`

  `fill`

    get/set the fill style. See rim for reference logic.

    Type: | `FillStyle`

## Paper

class `Paper`

  This class represents the paper which is the white area in the GUI containing everything. It is returned by global namespace paper or `Xfbp.paper`. Examples:

      paper.size='a4'
      paper.orientation='portrait'
      # or
      paper.size=(500,800) # not the same size but close

  That’s all there is to it.

  `size`

    get/set the paper size. There are two options. First one can give the paper size as a sequence (tuple,list,…) of two int:

        paper.size=(500,800)

    or one can give a paper size str

    a0 | … | a10
    b0 | … | b10
    c1 | … | c7
    isob0 | … | isob10
    letter | legal | …

    Type: | str or 2-sequence of int

  `orientation`

    get/set the orientation to ‘landscape’ or ‘portrait’

    Type: | str

## World

class `World`(graphid)

  The World object determines the part of the data range, which is shown inside the `Graph`’s viewport (`View`). A free standing object can be created or the hierarchy can be used:

      World(1).x=[-1,11] # the world object of the graph with id 1

      G[1].world.x=[-1,11] # the same thing

      g=G[1]
      # do somthing with graph 1
      ....
      w=g.world
      w.x=[-1,11] # yet the same thing
      w.offset=(0,0.1) # leave some space in y-direction
      w.autoscale('y') # let it be done
      #or
      g.autoscale('y') # let it be done, its all the same

      print w.xmin,w.xmax # printing will be shown in the console (xterm)
      print w.ymin,w.ymax

  Parameters: | graphid (int) – the graph id

  `autoscale`(what='all')

    autoscale graph using the currently set `offset`

    Parameters: | what (str) – ‘all’ ,’x’ or ‘y’
    Returns: | self to allow call chaining as in `World.autoscale(...).setSomethingElse(...)`
    Return type: | `World`

  `setX`(x0=0, x1=0)

    convenience function to set the `x`-world extend

    Parameters: | x0 (float) – leftmost x-value x1 (float) – righttmost x-value
    Returns: | self to allow call chaining as in `World.setX(...).setSomethingElse(...)`
    Return type: | `World`

  `setY`(y0=0, y1=0)

    convenience function to set the `y`-world extend

    Parameters: | y0 (float) – lowest y-value y1 (float) – highest y-value
    Returns: | self to allow call chaining as in `World.setY(...).setSomethingElse(...)`
    Return type: | `World`

  `setOffset`(x=0, y=0)

    convenience function to set the autoscale `offset`

    Parameters: | x (float) – the relative offset in x y (float) – the relative offset in y
    Returns: | self to allow call chaining as in `World.setOffset(...).setSomethingElse(...)`
    Return type: | `World`

  `x`

    get/set the x-world extend

    Type: | 2-tuple of float

  `y`

    get/set the y-world extend

    Type: | 2-tuple of float

  `xmin`

    get/set the leftmost x-value

    Type: | float

  `ymin`

    get/set the lowest y-value

    Type: | float

  `xmax`

    get/set the rightmost x-value

    Type: | float

  `ymax`

    get/set the highest y-value

    Type: | float

  `offset`

    get/set autoscale offset in percent*100 of the autoscale interval. The setter argument is a sequence of 2 float: (offsetx,offsety).

    Type: | 2-tuple or 2-list of float

## View

class `View`(graphid)

  The View object describes the viewport of a `Graph`, the area which is usually inside a frame with ticmarks and such stuff. It is where the data are plotted in on the screen. A free standing object can be created or the hierarchy can be used:

      View(1).x0=0.18 # dont ask why we use x0,y0,width,height here
      View(1).width=0.77  # it's historical
      View(1).y0=0.166
      View(1).height=0.668

      # or the same
      G[1].view.setGeometry(0.18,0.166,0.77,0.668)
      # or more verbose
      G[1].view.setGeometry(x0=0.18,y0=0.166,width=0.77,height=0.668)

      G[1].view.setFrame(Frame(active=1,
        rim=LineStyle(style='Solid',width=1,color=0x0),
        fill=FillStyle(active=True,color=0xffffff)))

  Parameters: | graphid (int) – the graph id

  `setFrame`(frame)

    convenience function for setting the `frame`

    Parameters: | frame (`Frame`) – the frame
    Returns: | self to allow call chaining as in `View.setFrame(...).setSomethingElse(...)`
    Return type: | `View`

  `setGeometry`(x0=0.18, y0=0.166, width=0.7, height=0.668)

    convenience function for setting the `x0`, `y0`, `width` and `height`

    Parameters: | x0 (float) – relative left border y0 (float) – relative top border width (float) – relative width height (float) – relative height
    Returns: | self to allow call chaining as in `View.setGeometry(...).setSomethingElse(...)`
    Return type: | `View`

  `frame`

    get/set the frame. The getter returns a reference object such that changing the returned frame changes the object which owns frame. The setter makes a hard assignment of the frame data of the underlying object while not changeing the reference.

    Type: | `Frame`

  `x0`

    get/set the border left of the view frame in percent*100 of the paper width

    Type: | float

  `y0`

    get/set the border above of the view frame in percent*100 of the paper height

    Type: | float

  `width`

    get/set the width of the view frame in percent*100 of the paper width

    Type: | float

  `height`

    get/set the height of the view frame in percent*100 of the paper height

    Type: | float

## Axis

class `Axis`(graphid, xy)

  The Axis object controls the axis scaling of the `Graph`:

      G[1].xaxis.scaling='log'
      #or
      Axis(1,'x').scaling='log'

  Note, that we use a trick to allow for logarithmic axes with negative world values. In a case where e.g. `World.xmin<0` we adjust `xmin` to take the smallest representable positive number. This way no error message pops up but your graph looks weird.

  Parameters: | graphid (int) – graph id xy (str) – axis id ‘x’ or ‘y’

  `scaling`

    get/set the axis scaling ‘lin’ or ‘log’

    Type: | str

## Legend

class `Legend`(graphid)

  The Legend object represents the legend box of the `Graph`. The legend entries are not defined here. They are `Set`/`Group` properties:

      G[1].legend.on()
      G[1].legend.symbolwidth=2
      G[1].legend.frame.borderspacing=0.2

      #or
      Legend(1).symbolwidth=2
      ...

  Parameters: | graphid (int) – the graph id

  `on`()

    switch legend box on

    Returns: | self to allow call chaining as in `Legend.on(...).setSomethingElse(...)`
    Return type: | `Legend`

  `off`()

    switch legend box off

    Returns: | self to allow call chaining as in `Legend.off(...).setSomethingElse(...)`
    Return type: | `Legend`

  `toggle`()

    toggle legend box visibility

    Returns: | self to allow call chaining as in `Legend.toggle(...).setSomethingElse(...)`
    Return type: | `Legend`

  `setText`(font=None, linespacing=0.2)

    convenience function to compactly set the text related properties

    Parameters: | font (`FontStyle`) – the `font` style linespacing (float) – the spacing between `lines`
    Returns: | self to allow call chaining as in `Legend.setText(...).setSomethingElse(...)`
    Return type: | `Legend`

  `setGeometry`(position=(0.98, 0.02), origin=(0.98, 0.02))

    convenience function to compactly set the geometry of the box

    Parameters: | position (sequence (list,tuple,..)) – the `position` of the boxes origin origin (sequence (list,tuple,..)) – the boxes `origin`
    Returns: | self to allow call chaining as in `Legend.setGeometry(...).setSomethingElse(...)`
    Return type: | `Legend`

  `setFrame`(frame)

    convenience function to compactly set the `frame` properties

    Parameters: | frame (`Frame`) – the `frame` settings
    Returns: | self to allow call chaining as in `Legend.setFrame(...).setSomethingElse(...)`
    Return type: | `Legend`

  `setSymbol`(spacing=0.5, width=3.0)

    convenience function to compactly set the symbol properties

    Parameters: | spacing (float) – symbol-text `spacing` width (float) – symbol `width`
    Returns: | self to allow call chaining as in `Legend.setSymbol(...).setSomethingElse(...)`
    Return type: | `Legend`

  `active`

    get/set if the legend box’s visiblity. A nonzero value is True zero is False.

    Type: | bool

  `font`

    get/set the font. The getter returns a reference object such that changing the returned font changes the object which owns font. The setter makes a hard assignment of the font data of the underlying object while not changeing the reference.

    Type: | `FontStyle`

  `position`

    the legendbox has an `origin`, which is considered the point in the box which is pinned to a position in the viewport of the graph. Ths position is relative to the viewport. So, `position=(1,0)` puts the origin of the box at the upper right corner of the viewport.

    Type: | 2-tuple or 2-sequence of float

  `origin`

    the legendbox has an origin, which is considered the point in the box which is pinned to a `position` in the viewport of the graph. Ths origin is relative to the legendbox. So, `origin=(1,0)` puts the origin of the box at the upper right corner of the box.

    Type: | 2-tuple or 2-sequence of float

  `symbolspacing`

    the symbol spacing is the distance between the symbol marker and the legend entry text. It is in units of the font size.

    Type: | float

  `symbolwidth`

    the symbol width determines the width of the symbol marker in units of the font size.

    Type: | float

  `linespacing`

    the line spacing determines the distance between the individual lines of legend entries in units of the font height. Note, that the font height is taller than the a capital letter. Hence linespacing=0 does not close the visible gap between the lines, negative values do.

    Type: | float

  `frame`

    get/set the frame. The getter returns a reference object such that changing the returned frame changes the object which owns frame. The setter makes a hard assignment of the frame data of the underlying object while not changeing the reference.

    Type: | `Frame`

## Title

class `Title`(graphid)

  Bases: `TextBox`

  Title is a `TextBox` and only here for convenience (editor code insert functionality). Access the title of a `Graph` in the following way:

      G[1].title.text="A title"
      #or
      Title(1).text="A title"

  Parameters: | graphid (int) – the graph id

## SubTitle

class `SubTitle`(graphid)

  Bases: `TextBox`

  SubTitle is a `TextBox` and only here for convenience (editor code insert functionality). Access the subtitle of a `Graph` in the following way:

      G[1].subtitle.on()
      G[1].subtitle.text="A subtitle"
      #or
      SubTitle(1).on().text="A subtitle"

  Parameters: | graphid (int) – the graph id

## XAxisLabel

class `XAxisLabel`(graphid)

  Bases: `TextBox`

  XAxisLabel is a `TextBox` and only here for convenience (editor code insert functionality). Access the xaxis label of a `Graph` in the following way:

      G[1].xaxislabel.text="moment [$~m$_B$.]"
      #or
      XAxisLabel(1).text="moment [$~m$_B$.]"

  Parameters: | graphid (int) – the graph id

## YAxisLabel

class `YAxisLabel`(graphid)

  Bases: `TextBox`

  YAxisLabel is a `TextBox` and only here for convenience (editor code insert functionality). Access the yaxis label of a `Graph` in the following way:

      G[1].yaxislabel.text="Energy [eV]"
      #or
      YAxisLabel(1).text="Energy [eV]"

  Parameters: | graphid (int) – the graph id

## OppositeXAxisLabel

class `OppositeXAxisLabel`(graphid)

  Bases: `TextBox`

  OppositeXAxisLabel is a `TextBox` and only here for convenience (editor code insert functionality). Access the opposite xaxis label of a `Graph` in the following way:

      G[1].oppositexaxislabel.on()
      G[1].oppositexaxislabel.text="occupation"
      #or
      OppositeXAxisLabel(1).on().text="occupation"

  Parameters: | graphid (int) – the graph id

## OppositeYAxisLabel

class `OppositeYAxisLabel`(graphid)

  Bases: `TextBox`

  OppositeYAxisLabel is a `TextBox` and only here for convenience (editor code insert functionality). Access the opposite yaxis label of a `Graph` in the following way:

      G[1].oppositeyaxislabel.active=True
      G[1].oppositeyaxislabel.text="Volume [a$_B$.$x{-0.6}$^$y{-0.4}3$.]"
      #or
      OppositeYAxisLabel(1).on().text="Volume [a$_B$.$x{-0.6}$^$y{-0.4}3$.]"

  Parameters: | graphid (int) – the graph id

## TextBoxes

class `TextBoxes`(graphid)

  The TextBoxes class represents all user defined `text boxes` of the `Graph`. This class can be indexed in a similar way as `Graphs` with IDs which are not necessarily contiguous indices. The standard way to access a textbox would be:

      G[1].textboxes[2].on().text="(A)"
      G[1].textboxes[2].on().frame.off()
      G[1].textboxes[2].on().position=(0.1,0.05)

  One can use the class on it’s own as with many others:

      TextBoxes(1)[2].on() # same thing as before

  On can delete a textbox:

      del G[1].textboxes[2]
      #or
      #del TextBoxes(1)[2]

  and one can copy one textbox onto another if ever needed:

      G[1].textboxes[1].on().text="(a)"
      G[2].on()
      G[2].view.frame.fill.off()
      G[2].textboxes[5]=G[1].textboxes[1];
      G[2].textboxes[5].position=(0.2,0.15)

  Parameters: | graphid (int) – the graph id

  `__delitem__`(id)

    you can delete a textbox with a certain id:

        del G[1].textboxes[2]

  `__len__`()

    `len(G[1].textboxes)` returns the number of textboxes not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G[1].textboxes)):
            G[1].textboxes.at(i).text='T{I}'.format(I=i+1)

    Parameters: | i (int) – textbox index (not id)
    Returns: | textbox at index i
    Return type: | `TextBox`

  `__getitem__`()

    `G[1].textboxes[id]` returns the textbox with a certain id:

        g=G[1]
        tbs=g.textboxes
        for i in range(1,6,2):
           t=tbs[i].on()
           t.text='Textbox id={0}'.format(t.id)
           t.position=[t.position[0]+i*0.03,t.position[1]+i*0.05]
           t.font.color=0xff

    `G[1].textboxes[i] <==> G[1].textboxes.__getitem__(i)`

  `__setitem__`()

    Assign one textbox to another:

        G[1].textboxes[2]=G[1].textboxes[1]
        G[]1.textboxes[2].position=(0.5,0.5)

    `G[1].textboxes[i]=x <==> G[1].textboxes.__setitem__(i,x)`

  `__iter__`()

    you can iterate over all textboxes:

        for t in G[1].textboxes:
            print t.id

  `next`()

    for the iterator interface, see `__iter__`

  `new`()

    create and return a new TextBox

    Returns: | a new `TextBox`

  `len`

    `G[1].textboxes.len` returns the number of textboxes not the highest id

    Type: | int

  `lastid`

    the highest id among all existing textboxes (not the number of textboxes)

    Type: | int

## TextBox

class `TextBox`(graphid, textboxid)

  TextBox represents a text box with textboxid in the graph with graphid. TextBox IDs are not necessarily ordered. You access a textbox from a `TextBoxes` object:

      t=G[1].textboxes[2] # textbox 2 in graph 1
      # or directly
      t=TextBox(1,2)

  The acces via `TextBoxes` allows deletion.

  Use the GUI to set up the line and then use the menu->insert->textboxes-> to get something like:

      TextBox(1,1).on()\
        .setText("$isymbols: $arrowup, $arrowdown, $arrowleft, "
                 "$arrowright, $angstroem, "
              "$infinity $imore italic, $nnormal",
          font=FontStyle(size=12,subscriptscale=0.75,color=0xff))\
        .setFrame(Frame(active=1,borderspacing=0.2,
          rim=LineStyle(style='Solid',width=1,color=0x0,extracolor=True),
          fill=FillStyle(active=True,color=0xffffff,extracolor=True)))\
        .setGeometry(system='View',position=(0.03,0.25),angle=0,
          origin=(0,0),  restriction=None,offsets=[])

  Parameters: | graphid (int) – the graph id textboxid (int) – the textbox id

  `on`()

    switch textbox on

    Returns: | self to allow call chaining as in `TextBox.on(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `off`()

    switch textbox off

    Returns: | self to allow call chaining as in `TextBox.off(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `toggle`()

    toggle textbox visibility

    Returns: | self to allow call chaining as in `TextBox.toggle(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `setText`(text='some text', font=None)

    convenience function to set text related properties.

    Parameters: | text (str) – the textbox’ `text` font (`FontStyle`) – the `font` style
    Returns: | self to allow call chaining as in `TextBox.setText(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `setFrame`(frame)

    convenience function to set the frame

    Parameters: | frame (`Frame`) – the `frame`
    Returns: | self to allow call chaining as in `TextBox.setFrame(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `setGeometry`(system='view', position=(0, 0), origin=(0, 0), angle=0.0, restriction=None, offsets=[])

    convenience function to set the geometry

    Parameters: | system (str) – `coordinate system`, ‘view’ or ‘world’ position (sequence (list,tuple,..)) – the `position`: (x,y) origin (sequence (list,tuple,..)) – the box `origin`: (x,y) angle (float) – the rotation `angle` restriction – `restrictions` offsets (list) – additional `offsets`
    Returns: | self to allow call chaining as in `TextBox.setGeometry(...).setSomethingElse(...)`
    Return type: | `TextBox`

  `active`

    get/set if the textbox is visible. A nonzero value is True, zero is False.

    Type: | bool

  `text`

    get/set the actual text of the box. Use text formating if needed.

    Type: | str

  `id`

    the textbox id

    Type: | int

  `font`

    get/set the font. The getter returns a reference object such that changing the returned font changes the object which owns font. The setter makes a hard assignment of the font data of the underlying object while not changeing the reference.

    Type: | `FontStyle`

  `position`

    the textbox has an `origin`, which is considered the point in the box which is pinned to a position in the viewport of the graph. Ths position is relative to the viewport. So, `position=(0,0)` puts the origin of the box at the upper left corner of the viewport.

    Type: | 2-tuple or 2-sequence of float

  `origin`

    the textbox has an origin, which is considered the point in the box which is pinned to a `position` in the viewport of the graph. Ths origin is relative to the textbox. So, `origin=(0,0)` puts the origin of the box at the upper left corner of the box.

    Type: | 2-tuple or 2-sequence of float

  `angle`

    the rotation angle of the whole box

    Type: | float

  `frame`

    get/set the frame. The getter returns a reference object such that changing the returned frame changes the object which owns frame. The setter makes a hard assignment of the frame data of the underlying object while not changeing the reference.

    Type: | `Frame`

  `coordinatesystem`

    the `position` of the box is either specified in `viewport` coordinates or in `world` coordinates. In the latter case the box moves when the world is moved. Possible values: ‘view’ or ‘world’.

    Type: | str

  `restriction`

    a textbox can have restrictions, which pin it in relation to other objects (e.g. used for the title and axis lables). A restriction is either `None` or a tuple `(str,float)` where the `str` can be ‘x’or ‘y’. A restriction moves the box from its position into the specified direction by a viewport-relative amount given by the `float` (which can be negative).

    Type: | tuple

  `offsets`

    additional offsets, which take into account the space occupied by other objects. If the `list` is empty no offsets are considered. Otherwise it can contain any of the following `int`:

    > 1 | opposite x tic label height
    > 2 | opposite x tic label offset
    > 3 | normal x tic label height
    > 4 | normal x tic label offset
    > 5 | opposite y tic label width
    > 6 | opposite y tic label offset
    > 7 | normal y tic label width
    > 8 | normal y tic label offset
    > 9 | subtitle offset
    > 10 | subtitle height
    > 11 | opposite x-axis label offset
    > 12 | opposite x-axis label height

    Type: | list of int

## TicMarks

class `TicMarks`(graphid, xy)

  TicMarks represents the default tic marks and tic labels of the `Graph` s `xaxis` and `yaxis`. For user defined `Tic` s look into `Graph.usertics` and `Group.usertics`. You can access individual properties via the object hierarchy:

      G[1].ytics.labels.decimals=2
      G[1].ytics.major.line.color=0xff0000
      G[1].ytics.minor.line.width=2

  To setup handmade tic spacings/subdivisions you need to switch off the auto-tic production:

      G[1].xtics.auto=False

  Note, that for logarithmic axis scaling `labels.decimals` and `major.spacing` will be ignored, since they only make sense for linear scales.

  It might probably be the easiest to use the editor insert menu to get and edit this (After insertion select the whole block and use the edit->indent functionality for proper python indentation.):

      G[1].xtics.auto=True
      G[1].xtics.side='Normal'
      G[1].xtics.setLabels(side='Normal',offset=0.03,decimals=-1,
       font=FontStyle(size=16,subscriptscale=0.75,color=0x0))\
       .setMajor(active=1,spacing=1,length=0.02,separatelength=0,
       line=LineStyle(style='Solid',width=1,color=0x0,extracolor=True))\
       .setMinor(active=1,subdiv=2,length=0.01,separatelength=0,
       line=LineStyle(style='Solid',width=1,color=0x0,extracolor=True))
      G[1].ytics.auto=True
      G[1].ytics.side='Normal'
      G[1].ytics.setLabels(side='Normal',offset=0.03,decimals=-1,
       font=FontStyle(size=16,subscriptscale=0.75,color=0x0))\
       .setMajor(active=1,spacing=1,length=0.02,separatelength=0,
       line=LineStyle(style='Solid',width=1,color=0x0,extracolor=True))\
       .setMinor(active=1,subdiv=2,length=0.01,separatelength=0,
       line=LineStyle(style='Solid',width=1,color=0x0,extracolor=True))

  Parameters: | graphid (int) – the graph id xy (str) – axis id ‘x’ or ‘y’

  `setLabels`(side='normal', offset=0.03, decimals=-1, font=None)

    convenience function to set the tic label properties. This is another way of doing the following:

        G[1].xtics.labels.side='both'
        G[1].xtics.labels.offset=0.02
        G[1].xtics.labels.decimals=2
        G[1].xtics.labels.font.color=0xff #...

    Parameters: | side (str) – ‘none’, ‘normal’, ‘opposite’ or ‘both’ (`TicLabels.side`) offset (float) – see `TicLabels.offset` decimals (int) – see `TicLabels.decimals` font (`FontStyle`) – see `TicLabels.font`
    Returns: | self to allow call chaining as in `TicMarks.setLabels(...).setSomethingElse(...)`
    Return type: | `TicMarks`

  `setMajor`(active=1, spacing=1.0, length=0.02, separatelength=False, line=None)

    convenience function to set the major tic mark properties. This is another way of doing the following:

        G[1].xtics.auto=False
        G[1].xtics.major.spacing=2
        G[1].xtics.major.length=0.05

    Parameters: | active (int) – see `TicMajor.active` spacing (float) – see `TicMajor.spacing` length (float) – see `TicMajor.length` separatelength (int) – see `TicMajor.separatelength` line (`LineStyle`) – see `TicMajor.line`
    Returns: | self to allow call chaining as in `TicMarks.setMajor(...).setSomethingElse(...)`
    Return type: | `TicMarks`

  `setMinor`(active=1, subdiv=2, length=0.01, separatelength=False, line=None)

    convenience function to set the minor tic mark properties. This is another way of doing the following:

        G[1].xtics.auto=False
        G[1].xtics.minor.subdiv=5
        G[1].xtics.minor.length=0.03

    Parameters: | active (int) – see `TicMinor.active` subdiv (int) – see `TicMinor.subdiv` length (float) – see `TicMinor.length` separatelength (int) – see `TicMinor.separatelength` line (`LineStyle`) – see `TicMinor.line`
    Returns: | self to allow call chaining as in `TicMarks.setMinor(...).setSomethingElse(...)`
    Return type: | `TicMarks`

  `auto`

    get/set if the tic mark positions shall be automatically determined.

    Type: | bool

  `side`

    get/set the side on which to plot the tics. Can be ‘none’, ‘normal’, ‘opposite’ and ‘both’

    Type: | str

  `labels`

    get/set a TicLabels object which gives access to the label properties.

    This is intended for hierarchical use to change a few properties only as in:

        G[1].ytics.labels.decimals=2

    Type: | `TicLabels`

  `major`

    get/set a TicMajor object which gives access to the major tic mark properties.

    This is intended for hierarchical use to change a few properties only as in:

        G[1].ytics.major.line.color=0xff0000

    Type: | `TicMajor`

  `minor`

    get/set a TicMinor object which gives access to the minor tic mark properties.

    This is intended for hierarchical use to change a few properties only as in:

        G[1].ytics.minor.line.width=2

    Type: | `TicMinor`

## TicMajor

class `TicMajor`(graphid, xy)

  TicMajor is returned by `G[1].xtics.major` or `G[1].ytics.major` and allows hierarchical access:

      G[1].xtics.major.line.color=0xff

  Parameters: | graphid (int) – the graph id xy (str) – axis id ‘x’ or ‘y’

  `on`()

    switch major tics/labels on

    Returns: | self to allow call chaining as in `TicMajor.on(...).setSomethingElse(...)`
    Return type: | `TicMajor`

  `off`()

    switch major tics/labels off

    Returns: | self to allow call chaining as in `TicMajor.off(...).setSomethingElse(...)`
    Return type: | `TicMajor`

  `toggle`()

    toggle major tics/labels visibility

    Returns: | self to allow call chaining as in `TicMajor.toggle(...).setSomethingElse(...)`
    Return type: | `TicMajor`

  `active`

    get/set if the major tics and tic labels are visible. A nonzero value is True, zero is False.

    Type: | bool

  `spacing`

    get/set the spacing between major tics in `world` units. This takes effect, if `TicMarks.auto` is switched off. Note, that for logarithmic axis scaling the spacing will be ignored.

    Type: | float

  `length`

    get/set the major tic’s length in relative viewport units. (1 means the whole viewport width/height). See `separatelength`.

    Type: | float

  `separatelength`

    (get/set) normally this is `False` such that the physical tic length of both axes is the same. In this case the xaxis determines the tic length. If separatelength is `True`, the tic length for both axes can be set separately. Note, that due to bad design both x- and y-tics have this property. So, if you have:

        G[1].xtics.major.separatelength=True
        G[1].ytics.major.separatelength=False

    in your script, the second line will win.

    Type: | bool

  `line`

    get/set the line (LineStyle). The getter returns a reference object such that changing it changes the `TicMajor`-object which owns line. The setter makes a hard assignment of the `TicMajor`-objects data. The reference of the assigned `LineStyle` stays intact.

    Type: | `LineStyle`

## TicMinor

class `TicMinor`(graphid, xy)

  TicMinor is returned by `G[1].xtics.minor` or `G[1].ytics.minor` and allows hierarchical access:

      G[1].xtics.minor.line.color=0xff

  Parameters: | graphid (int) – the graph id xy (str) – axis id ‘x’ or ‘y’

  `on`()

    switch minor tics/labels on

    Returns: | self to allow call chaining as in `TicMinor.on(...).setSomethingElse(...)`
    Return type: | `TicMinor`

  `off`()

    switch minor tics/labels off

    Returns: | self to allow call chaining as in `TicMinor.off(...).setSomethingElse(...)`
    Return type: | `TicMinor`

  `toggle`()

    toggle minor tics/labels visibility

    Returns: | self to allow call chaining as in `TicMinor.toggle(...).setSomethingElse(...)`
    Return type: | `TicMinor`

  `active`

    get/set if the minor tics and tic labels are visible. A nonzero value is True, zero is False.

    Type: | bool

  `subdiv`

    get/set the number of subdivions-intervals between major tics between which to plot a minor tic.

    Type: | int

  `length`

    get/set the major tic’s length in relative viewport units. (1 means the whole viewport width/height). See `separatelength`.

    Type: | float

  `separatelength`

    (get/set) normally this is `False` such that the physical tic length of both axes is the same. In this case the xaxis determines the tic length. If separatelength is `True`, the tic length for both axes can be set separately. Note, that due to bad design both x- and y-tics have this property. So, if you have:

        G[1].xtics.minor.separatelength=True
        G[1].ytics.minor.separatelength=False

    in your script, the second line will win.

    Type: | bool

  `line`

    get/set the line (LineStyle). The getter returns a reference object such that changing it changes the `TicMinor`-object which owns line. The setter makes a hard assignment of the `TicMinor`-objects data. The reference of the assigned `LineStyle` stays intact.

    Type: | `LineStyle`

## TicLabels

class `TicLabels`(graphid, xy)

  TicLabels is returned by `G[1].xtics.labels` or `G[1].ytics.labels` and allows hierarchical access:

      G[1].xtics.labels.decimals=2

  Parameters: | graphid (int) – the graph id xy (str) – axis id ‘x’ or ‘y’

  `side`

    get/set the side on which to plot tic labels. It can be ‘none’, ‘normal’, ‘opposite’ and ‘both’

    Type: | str

  `offset`

    get/set the offset between the tic labels and the axis in relative viewport units.

    Type: | int

  `decimals`

    get/set how many decimals will be plotted. -1 means automatic. Note, that for logarithmic axis scaling decimals will be ignored.

    Type: | int

  `font`

    get/set the font. The getter returns a reference object such that changing the returned font changes the object which owns font. The setter makes a hard assignment of the font data of the underlying object while not changeing the reference.

    Type: | `FontStyle`

## UserTics

class `UserTics`(graphid, groupid=0)

  UserTics allow to define irregular individual tic marks/labels. They can be `Graph` specific: `Graph.usertics` and `Group` specific: `Group.usertics`. The difference is that their visibility is coupled to the respective parent object’s visibility.

  Unfortunately, tics are indexed by zero based indices as normal lists in contrast to all other objects in `pyxfbp`. The easiest way to deal with them when creating is:

      G[1].usertics.clear().on()\
           .append(Tic(label="G",position=0.2,length=1,type='xmajor'))\
           .append(Tic(label="X",position=0.6,length=1,type='xmajor'))\
           .append(Tic(label="M",position=0.9,length=1,type='xmajor'))

  When changing existing tics do this (you will anyway have looked at the GUI to figure out which tics where created by a `read` command):

      G[1].usertics[1].label="P" # change label

      del G[1].usertics[5] # dont want this

  Some more explanantions: usertics[2] is the 2nd tic and not the tic with id 2 as for graphs… Deleting tics changes the index of all tics with higher index by -1. Furthermore, if we have reference objects they are now dangling:

      G[1].usertics.clear().on()\
           .append(Tic(label="G",position=0.2,length=1,type='xmajor'))\
           .append(Tic(label="X",position=0.6,length=1,type='xmajor'))\
           .append(Tic(label="M",position=0.9,length=1,type='xmajor'))

      t=G[1].usertics[0]
      t.label="GG"
      del G[1].usertics[0]

      t.line.color=0xff0000 # this is allowed

      for u in G[1].usertics:
          print u.label

      # now t is a dangling Tic. You can change it without any visible
      # changes in the GUI, well it's dangling.
      # But you can assign it to another tic.

      G[1].usertics.new()
      G[1].usertics[2]=t # assign to new 3rd tic

      # Now the tics are there in a different order

      for u in G[1].usertics:
          print u.label

  Parameters: | graphid (int) – the graph id groupid (int) – the group id

  `__delitem__`(i)

    you can delete a tic with index i:

        del G[1].usertics[2]

  `on`()

    switch usertics on

    Returns: | self to allow call chaining as in `UserTics.on(...).setSomethingElse(...)`
    Return type: | `UserTics`

  `off`()

    switch usertics off

    Returns: | self to allow call chaining as in `UserTics.off(...).setSomethingElse(...)`
    Return type: | `UserTics`

  `toggle`()

    toggle usertics visibility

    Returns: | self to allow call chaining as in `UserTics.toggle(...).setSomethingElse(...)`
    Return type: | `UserTics`

  `__len__`()

    `len(G[1].usertics)` returns the number of usertics

  `__getitem__`()

    `G[1].usertics[i]` returns the usertic with index i

    `G[1].usertics[i] <==> G[1].usertics.__getitem__(i)`

  `__setitem__`()

    Assign one usertic to another:

        G[1].usertics[2]=G[1].usertics[1]
        G[1].usertics[2].position=0.67
        G[1].usertics[2].label="M"

    `G[1].usertics[i]=x <==> G[1].usertics.__setitem__(i,x)`

  `__iter__`()

    you can iterate over all usertics:

        for t in G[1].usertics:
            t.line.color=0xff00

  `next`()

    for the iterator interface, see `__iter__`

  `clear`()

    delete all usertics

    Returns: | self to allow call chaining as in `UserTics.clear(...).setSomethingElse(...)`
    Return type: | `UserTics`

  `new`()

    create and return a new Tic

    Returns: | a new `Tic`

  `append`(tic)

    append `Tic` to the list of usertics.

    Parameters: | tic (`Tic`) – a tic object
    Returns: | self to allow call chaining as in `UserTics.append(...).setSomethingElse(...)`
    Return type: | `UserTics`

  `active`

    get/set if these usertics (Graph or Group owned) are visible. A nonzero value is True, zero is False.

    Type: | bool

## Tic

class `Tic`(type='xmajor', position=0, length=0.02, label='label', ticside='normal', labelside='normal', labeloffset=0.03, line=None)

  The Tic object is used to either append a new Tic to `UserTics` or to follow the object hierarchical:

      G[1].usertics.\
        append(Tic(type='xmajor',position=0.1,label='M',
               ticside='Normal',labelside='Normal',length=1,labeloffset=0.03,
               line=LineStyle(style='Solid',width=1,color=0x0,extracolor=True)))

      G[1].usertics[0].label='M' #  here usertics[1] returend a Tic object

  Parameters: | type (str) – ‘xmajor’, ‘xminor’, ‘ymajor’ or ‘yminor’ `type` position (float) – see `position` length (float) – see `length` label (str) – see `label` ticside (str) – ‘none’, ‘normal’, ‘opposite’ and ‘both’, see `ticside` labelside (str) – ‘none’, ‘normal’, ‘opposite’ and ‘both’, see `labelside` labeloffset (float) – see `labeloffset` line (`LineStyle`) – see `line`

  `type`

    get/set the type of the tic, ‘xminor’, ‘xmajor’, ‘yminor’ or ‘ymajor’

    Type: | str

  `position`

    get/set the tic position in world units.

    Type: | float

  `label`

    get/set the tic label.

    Type: | str

  `ticside`

    get/set the tic side, ‘none’, ‘normal’, ‘opposite’ and ‘both’

    Type: | str

  `labelside`

    get/set the label side, ‘none’, ‘normal’, ‘opposite’ and ‘both’

    Type: | str

  `length`

    get/set the tic length in relative viewport units

    Type: | float

  `labeloffset`

    get/set the label offset between the tic labels and the axis in relative viewport units.

    Type: | float

  `line`

    get/set the linestyle. The getter returns a reference object such that changing it changes the `Tic`-object which owns line. The setter makes a hard assignment of the `Tic`-objects data. The reference of the assigned `LineStyle` stays intact.

    Type: | `LineStyle`

## Lines

class `Lines`(graphid)

  Lines represent all `line` shapes in a `Graph`. Lines work ID-based, the same way as `Graphs`. You can delete line shapes and copy them onto each other:

      G[1].lines[1].on()
      # do some settings
      G[1].lines[5]=G[1].lines[1]
      del G[1].lines[1]

  You can directly access Lines via:

      lns=Lines(1)
      lns[1].on()

  Parameters: | graphid (int) – the graph id

  `__delitem__`(id)

    you can delete a line shape with a certain id:

        del G[1].lines[2]

  `__len__`()

    `len(G[1].lines)` returns the number of line shapes not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G[1].lines)):
            G[1].lines.at(i).line.color=0xff

    Parameters: | i (int) – line shape index (not id)
    Returns: | line shape at index i
    Return type: | `Line`

  `__getitem__`()

    `G[1].lines[id]` returns the line shape with a certain id:

        g=G[1]
        lns=g.lines
        for i in range(1,6,2):
           t=lns[i].on()
           t.line.color=0xff0000
           t.startat=(0.2,0.2)
           t.endat=[t.endat[0]+i*0.03,t.endat[1]+i*0.0]

    `G[1].lines[i] <==> G[1].lines.__getitem__(i)`

  `__setitem__`()

    Assign one line shape to another:

        G[1].lines[2]=G[1].lines[1]
        G[1].lines[2].startat=(0.9,0.5)

    `G[1].lines[i]=x <==> G[1].lines.__setitem__(i,x)`

  `__iter__`()

    you can iterate over all line shapes:

        for l in G[1].lines:
            l.line.color=0xff00

  `next`()

    for the iterator interface, see `__iter__`

  `new`()

    create and return a new Line

    Returns: | a new `Line`

  `len`

    `G[1].lines.len` returns the number of line shapes not the highest id

  `lastid`

    the highest id among all existing line shapes (not the number of line shapes)

    Type: | int

## Line

class `Line`(graphid, lineid)

  Line is a single line shape with optional arrows belonging to a particular `graph`. Access lines through the `lines` object or directly:

      l=G[1].lines[4].on() # graph1 line4 now exists and is visible and
                           # assigned to variable l
      Line(1,4).on()       # does the same thing

      G[1].lines[1]=G[1].lines[4] # now we have two lines

      del G[1].lines[4] # and delete the first

      l.line.color=0xff0000  # error: line4 does not exist, we deleted it

      # but

      l.on().line.color=0xff0000 # back alive

  Use the GUI to set up the line and then use the menu->insert->shapes to get something like:

      Line(1,1).on().setName('')\
       .setGeometry(startat=(0.2,0),endat=(0.8,1),system='View')\
       .setLine(capat='None',style=LineStyle(style='Solid',width=1,\
           color=0x0,extracolor=True))\
       .setArrow(at='End',style='Closed',size=16,sharpness=2,
           fill=FillStyle(active=False,color=0x0,extracolor=True))

  Parameters: | graphid (int) – graph owning the line lineid (int) – line shape id

  `on`()

    switch line shape on

    Returns: | self to allow call chaining as in `Line.on(...).setSomethingElse(...)`
    Return type: | `Line`

  `off`()

    switch line shape off

    Returns: | self to allow call chaining as in `Line.off(...).setSomethingElse(...)`
    Return type: | `Line`

  `toggle`()

    toggle line shape visibility

    Returns: | self to allow call chaining as in `Line.toggle(...).setSomethingElse(...)`
    Return type: | `Line`

  `setArrow`(at='end', style='closed', size=16, sharpness=2, fill=None)

    convenience function to set arrow related properties.

    Parameters: | at (str) – where does the arrow sit (`arrowat`). ‘none’, ‘end’, ‘start’ or ‘both’ style (str) – ‘open’ or ‘closed’ (`arrowstyle`) size (float) – the `arrowsize` sharpness (float) – the `arrowsharpness` fill (`FillStyle`) – the `arrowfill`
    Returns: | self to allow call chaining as in `Line.setArrow(...).setSomethingElse(...)`
    Return type: | `Line`

  `setName`(name)

    convenience function to set the line shape `name`

    Parameters: | name (str) – a name
    Returns: | self to allow call chaining as in `Line.setName(...).setSomethingElse(...)`
    Return type: | `Line`

  `setGeometry`(startat=(0.2, 0), endat=(0.8, 1), system='view')

    convenience function to set the line geometry

    Parameters: | startat (2-sequence (tuple,list,..)) – see `startat` endat (2-sequence (tuple,list,..)) – see `endat` system (str) – ‘view’ or ‘world’ (`coordinatesystem`)
    Returns: | self to allow call chaining as in `Line.setGeometry(...).setSomethingElse(...)`
    Return type: | `Line`

  `setLine`(capat='none', style=None)

    convenience function to set the line’s properties

    Parameters: | capat – ‘none’, ‘end’, ‘start’ or ‘both’ (`capat`) style (`LineStyle`) – see `line`
    Returns: | self to allow call chaining as in `Line.setLine(...).setSomethingElse(...)`
    Return type: | `Line`

  `id`

    the line shape’s id

    Type: | int

  `active`

    get/set if the line shape is visible. A nonzero value is True, zero is False.

    Type: | bool

  `name`

    get/set a name for the line shape for easier orientation

    Type: | str

  `line`

    get/set the linestyle. The getter returns a reference object such that changing it changes the `Line`-object which owns line. The setter makes a hard assignment of the `Line`-objects data. The reference of the assigned `LineStyle` stays intact.

    Type: | `LineStyle`

  `coordinatesystem`

    get/set/ the coordinate system. `startat` and `endat` of the line shape are either specified in `viewport` coordinates or in `world` coordinates. In the latter case the line moves when the world is moved. Possible values: ‘view’ or ‘world’.

    Type: | str

  `startat`

    get/set the line starting position:

        l=G[1].lines[1].on()
        l.coordinatesystem='world'
        l.startat=(0.1,0.2)
        l.endat=(0.8,0.6)
        G[1].world.setX(-1,1.5).setY(-0.5,1.3)
        # the line is still at the intended coordinates

    Type: | 2-tuple or 2-sequence of float

  `endat`

    get/set the line end position.

    Type: | 2-tuple or 2-sequence of float

  `capat`

    get/set the line cap. A line can have a cap at either end. A cap is a little round thing, which makes the line end look smoother. Possible options are:

    > ‘none’, ‘end’, ‘start’ or ‘both’

    Type: | str

  `arrowat`

    get/set the arrow. A line can have an arrow at either end. Possible options are:

    > ‘none’, ‘end’, ‘start’ or ‘both’

    Type: | str

  `arrowstyle`

    get/set the arrow style. There are two styles: ‘open’ and ‘closed’.

    Type: | str

  `arrowsize`

    get/set the arrow size in point units (as font size).

    Type: | float

  `arrowsharpness`

    get/set the arrow sharpness. This is accuteness of the opening.

    Type: | float

  `arrowfill`

    get/set the arrowfill (`FillStyle`). If `arrowfill.active` is `False/0` and the style is ‘closed’ a full arrow head with the `line` color is drawn, if `arrowfill.active` is `True/!=0` the arrow head has a separate fill color.

    The getter returns a reference object such that changing it changes the `Line`-object which owns arrowfill. The setter makes a hard assignment of the `Line`-objects data. The reference of the assigned `FillStyle` stays intact.

## Ellipses

class `Ellipses`(graphid)

  Ellipses represent all `ellipse` shapes in a `Graph`. Ellipses work ID-based, the same way as `Graphs`. You can delete ellipse shapes and copy them onto each other:

      G[1].ellipses[1].on()
      # do some settings
      G[1].ellipses[5]=G[1].ellipses[1]
      del G[1].ellipses[1]

  You can directly access Ellipses via:

      els=Ellipses(1) # all ellipses of graph with id 1
      els[1].on()

  Parameters: | graphid (int) – the graph id

  `__delitem__`(id)

    you can delete an ellipse shape with a certain id:

        del G[1].ellipses[2]

  `__len__`()

    `len(G[1].ellipses)` returns the number of ellipse shapes not the highest id

  `at`(i)

    For index (not id) based iteration, use as in:

        for i in range(len(G[1].ellipses)):
            G[1].ellipses.at(i).line.color=0xff

    Parameters: | i (int) – ellipse shape index (not id)
    Returns: | ellipse shape at index i
    Return type: | `Ellipse`

  `__getitem__`()

    `G[1].ellipses[id]` returns the ellipse shape with a certain id:

        g=G[1]
        els=g.ellipses
        for i in range(1,6,2):
           e=els[i].on()
           e.line.color=0xff0000
           e.radii=0.03*(i+1)
           e.center=(e.center[0],e.center[1]+i**2*0.01)

    `G[1].ellipses[i] <==> G[1].ellipses.__getitem__(i)`

  `__setitem__`()

    Assign one ellipse shape to another:

        G[1].ellipses[2]=G[1].ellipses[1]
        G[1].ellipses[2].center=(0.9,0.5)

    `G[1].ellipses[i]=x <==> G[1].ellipses.__setitem__(i,x)`

  `__iter__`()

    you can iterate over all ellipse shapes:

        for l in G[1].ellipses:
            l.line.color=0xff00

  `next`()

    for the iterator interface, see `__iter__`

  `new`()

    create and return a new ellipse

    Returns: | a new `Ellipse`

  `len`

    `G[1].ellipses.len` returns the number of ellipse shapes not the highest id

  `lastid`

    the highest id among all existing ellipse shapes (not the number of ellipse shapes)

    Type: | int

## Ellipse

class `Ellipse`(graphid, ellipseid)

  Ellipse is a single ellipse shape belonging to a particular `graph`. Access ellipses through the `ellipses` object or directly:

      e=G[1].ellipses[4].on() # graph1 ellipse4 now exists and is visible and
                           # assigned to variable e
      Ellipse(1,4).on()       # does the same thing

      G[1].ellipses[1]=G[1].ellipses[4] # now we have two ellipses

      del G[1].ellipses[4] # and delete the first

      e.line.color=0xff0000  # error: ellipse4 does not exist, we deleted it

      # but

      e.on().line.color=0xff0000 # back alive

  Use the GUI to set up the ellipse and then use the menu->insert->shapes to get something like:

      Ellipse(1,4).on().setName('')\
       .setGeometry(center=(4.47214,60),radii=(1.11474,18),angle=0,system='World')\
       .setLine(LineStyle(style='Dot',width=4,color=0xff0000,extracolor=True))\
       .setFill(FillStyle(active=True,color=0xaa00,extracolor=True))

  Parameters: | graphid (int) – graph owning the ellipse ellipseid (int) – ellipse shape id

  `on`()

    switch ellipse shape on

    Returns: | self to allow call chaining as in `Ellipse.on(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `off`()

    switch ellipse shape off

    Returns: | self to allow call chaining as in `Ellipse.off(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `toggle`()

    toggle ellipse shape visibility

    Returns: | self to allow call chaining as in `Ellipse.toggle(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `setName`(name)

    convenience function to set the ellipse shape `name`

    Parameters: | name (str) – a name
    Returns: | self to allow call chaining as in `Ellipse.setName(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `setGeometry`(center=(0, 0), radii=(0.1, 0.2), angle=0.0, system='view')

    convenience function to set the line geometry

    Parameters: | center (2-sequence (tuple,list,..)) – see `center` radii (float or 2-sequence (tuple,list,..)) – see `radii` angle (float) – see `angle` system (str) – ‘view’ or ‘world’ (`coordinatesystem`)
    Returns: | self to allow call chaining as in `Ellipse.setGeometry(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `setLine`(style)

    convenience function to set the ellipse’s linestyle

    Parameters: | style (`LineStyle`) – : see `line`
    Returns: | self to allow call chaining as in `Ellipse.setLine(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `setFill`(fill)

    convenience function to set the ellipse’s fillstyle

    Parameters: | fill (`FillStyle`) – : see `fill`
    Returns: | self to allow call chaining as in `Ellipse.setFill(...).setSomethingElse(...)`
    Return type: | `Ellipse`

  `id`

    the ellipse shape’s id

    Type: | int

  `active`

    get/set if the ellipse shape is visible. A nonzero value is True, zero is False.

    Type: | bool

  `name`

    get/set a name for the ellipse shape for easier orientation

    Type: | str

  `line`

    get/set the linestyle. The getter returns a reference object such that changing it changes the `Ellipse`-object which owns line. The setter makes a hard assignment of the `Ellipse`-objects data. The reference of the assigned `LineStyle` stays intact.

    Type: | `LineStyle`

  `fill`

    get/set the fillstyle. The getter returns a reference object such that changing it changes the `Ellipse`-object which owns fill. The setter makes a hard assignment of the `Ellipse`-objects data. The reference of the assigned `FillStyle` stays intact.

    Type: | `FillStyle`

  `center`

    get/set the ellipse starting position:

        e=G[1].ellipses[1].on()
        e.coordinatesystem='world'
        e.center=(0.1,0.2)
        e.radii=(0.2,0.1)
        G[1].world.setX(-1,1.5).setY(-0.5,1.3)
        # the ellipse is still at the intended coordinates

    Type: | 2-tuple or 2-sequence of float

  `radii`

    get/set radii/radius. The 2-sequence (tuple,list,…) denotes [x-radius,y-radius]. If a circle is needed just us a single float (no sequence):

        ellipse.radii=0.2 # a circle

    Type: | float or 2-tuple of float

  `angle`

    get/set rotation angle of the ellipse

    Type: | float

  `coordinatesystem`

    get/set/ the coordinate system. `center` and `radii` of the ellipse shape are either specified in `viewport` coordinates or in `world` coordinates. In the latter case the ellipse moves when the world is moved. Possible values: ‘view’ or ‘world’.

    Type: | str