== <sequence> ==

A sequence object represents a series of results that evolve with time or some other parameter.  In the simplest case, you can wrap a series of [wiki:rp_xml_ele_image <image>] elements in a sequence, and the user can play the sequence like a movie.  Right now, sequences are used only for output.

[[rpimage(zoo_sequence.gif)]]
{{{
  <sequence id="movie">
    <about>
      <label>Animated sequence</label>
    </about>
    <index>
      <label>Frame</label>
    </index>
    <element id="0">
      <index>1</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
        ...
        </current>
      </image>
    </element>
    <element id="1">
      <index>2</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
      </image>
    </element>
    ...
  </sequence>
  ...
}}}
Each sequence contains a series of elements, each with an index and a value.  The label of the index is set once, at the same level as the {{{<about>}}} section.  The label for each index is set just inside each {{{<element>}}}.  Note that the various elements will appear in the order associated with their {{{<index>}}} value.  The index does not have to be an integer; it can be a real number or any arbitrary string.  If one or more of the items is not recognized as a real or an integer, then all indices are treated as strings and ordered according to a dictionary sort.  See below for instructions on including units in index values.

The actual value within each element can be an [wiki:rp_xml_ele_image <image>], a [wiki:rp_xml_ele_curve <curve>], a [wiki:rp_xml_ele_field <field>], etc.  (Right now, only a few cases are supported.  In time, all output types will be handled properly within a sequence.)

=== <index> with Units ===

If you want to include units in your {{{<index>}}} values, then be sure to declare the units in the {{{<index>}}} section at the topmost level of the {{{<sequence>}}}.  For example, here is a sequence where the values are in picoseconds:
{{{
  <sequence id="movie">
    <about>
      <label>Animated sequence</label>
    </about>
    <index>
      <label>Time</label>
      <units>ps</units>
    </index>
    <element id="0">
      <index>0.05</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
        ...
        </current>
      </image>
    </element>
    <element id="1">
      <index>40fs</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
      </image>
    </element>
    ...
  </sequence>
  ...
}}}
In this example, the {{{<units>ps</units>}}} declares the default units for all index values.  Therefore, the index "0.05" for element 0 is interpreted as "0.05ps".  Note that element 1 has a value 40fs, which will put it before 0.05ps in the sequence order.

If you forget to declare the {{{<units>}}} for an index, then the individual {{{<index>}}} values won't pass the test of being real numbers, and the elements will be sorted in dictionary order as if they were ordinary string values.  This may put them in a rather strange order.

You can see working code in the [browser:trunk/examples/zoo zoo of examples] in the [browser:trunk/examples/zoo/sequence sequence example] or on the hub in the directory /apps/rappture/examples/zoo/sequence.