Timestreams User Documentation

v. 2.0.0-Alpha-0.3

The Guide

  1. Introduction

    • Purpose

    The purpose of this document is to describe how to use the Timestreams WordPress Plugin and to provide the use cases we considered during its development.

    • Intended audience

    This document is intended for Timestreams users who want to create data, generate and modify Timestreams, and visualise them. There is a separate Admin guide, Plug guide and Sensor guide, for those wishing to administer the Timestreams plugin, run Timestreams on a Dreamplug, or get Timestreams working with some example sensors, respectively. In addition, click here to learn about the Timestream API, which is beyond the scope of this document.

    A note about terminology. The term “Timestream(s)” is used throughout this document referring to both the plugin name and the data manipulation model. It can sometimes be confusing but should be disambiguated. You have been warned icon_wink

    • Background and acknowledgements

    The Timestreams social data networking plugin leverages WordPress to allow artists to engage with live, modelled and captured data. It can be used to visualise, compare and perform data.

    The Relate Project is a collaboration between the Horizon Digital Economy Research Institute, artist company Active Ingredient, Dr Carlo Buontempo from the Met Office Hadley Centre, Brazilian curator Silvia Leal, staff in Computer Science, Psychology, Performance and New Media from Horizon (University of Nottingham and University of Exeter), and a number of communities in Brazil and the UK. The project is funded by RCUK.

    • License

      Timestreams is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

      Timestreams is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

    • Support, feedback and collaboration

      The Relate Project members are interested in your experience using the Timestreams plugin. Contact us if you require additional support or have feedback for us.

    • Document contents

      The remainder of this document describes the Timestreams plugin interface as well as advanced features including how to add new visualisations and use the API to access Timestreams outside of WordPress. It also presents various cases the Relate project team thought the plugin could be used for.

  2. Plugin interface

    To use Timestreams, log in to a WordPress site with the plugin enabled. See your WordPress administrator for your user account details if you do not already have these.

    Upon logging in, the Timestreams plugin adds various options to the WordPress administration dashboard. This section describes these options. Be sure to read the instructions on the particular pages as well for supplementary information.

    Timestreams Dashboard
    Timestreams Dashboard

    Rolling over the Timestreams left menu item reveals additional menus.

    Timestreams menu items
    Timestreams menu items

    The following subsections describes the various menus and their options.

      • Timestreams

        Selecting the Timestreams left-menu item reveals the Timestreams interface.

        Timestreams interface
        Timestreams interface

        The Timestreams interface allows users to create timestreams and use them to author data performances. These can then be used by visualisations and other outputs to perform the timestreams. Timestreams can be considered as views of measurement containers. Playheads move through timestreams to indicate a measurement that should be output. The following image shows the different parts of a timestream.

        Anatomy of a Timestream
        Anatomy of a Timestream

        Each Timestream has a name (A), measurement container selector (B), delete button (C), main measurement view (D), start position marker (E), current head position marker (F), mini measurement viewer (G), new head time feild (H), new start time field (I), new end time field (J), start/end time disable selector (K), rate field (L), and interface buttons (M).

        Name
        The name of the timestream, which is defined when a user creates a new timestream. Note that it is different from the measurement container name that the timestream is associated with.
        Measurement container selector
        A drop down menu that displays the measurement containers that can be used by this timestream.
        Delete button
        Deletes this timestream. The associated measurement container and its data is not affected by this deletion.
        Main measurement view
        This chart depicts a timeline with the measurements from the given measurement container. The green background indicates start and end times for the timestream.The height of the chart and its lowest value (0 in the case of the above image) are derived from the measurement container settings’ minimum and maximum values.At most, one thousand measurements may be displayed at a time. The “prev” and “next” buttons can be used to move the timeline forward and backward by one thousand measurements until the start or end of the data. The main measurement view may display a start position marker and a current head position marker.Three types of data may be displayed in the main view: standard data (such as numbers for temperature), images and media files. Rolling over a standard data point reveals its timestamp and data value. Rolling over an image reveals it in full. Rolling over a media file icon reveals its URL.
        Start position marker
        This indicates the starting point for data playback. To set this marker click the “head” button (M), click on the timeline, then click save. Repeat this to move the starting point elsewhere on the timeline.
        Current head position marker
        The current head position starts at the start position marker and moves forward by at the rate set in the rate field (L).
        Mini measurement viewer
        The mini measurement viewer allows you to zoom in and out of the data presented in the Main measurement view. To zoom in drag the left or right bar on the edges of the mini data viewer. Slide the reduced mini bar display to slide through the data.
        New head time field
        This field contains the precise time that the play head starts at. It is automatically completed when the play head is set to a new start location.
        New start time field
        This field contains the precise start time. It is automatically completed when the start time is set to a new start position.
        New end time field
        This field contains the precise end time. It is automatically completed when the end time is set to a new end position.
        Start/end time disable selector
        When this is toggled on the play head will continue to move forward as new data comes in. When this option is toggled off the play head will loop back to the start position and replay across the data.
        Rate field
        This field sets the rate that the play head moves forward at. This field can store real number values greater than 0. The value 1 means that it moves forward in real time (1 second per second). Other values are multiples of these, for instance 2 means it advances at double speed (2 seconds per second), while 0.5 means it advances at half speed (half a second per second).
        Interface buttons
        These buttons include start, end, head, prev, next, latest and save. The start and end buttons are used to set the playback start and end points. Head sets the play head start position. The prev, next buttons let you scroll through the data by 1000 data points at a time. The latest button displays the latest data in the main measurement view. The save button should be clicked after making changing the start, end or play head position.

        The following describes how to create a timestream and use it to author data.

        To create a Timestream:

        1. Type in a name for your timestream
        2. Choose the data source that you would like to include in your post, page or output application.
        3. Choose the range of data that you would like to appear in your post, blog or by used by the API.
        4. You can set up as many timestreams as you want to output to your post, webpage or API.

        Once you have set up your timestream the data will appear on a timeline below as a graph with an x and y axis. The way it is displayed depends on what type of data it is:

        • Numerical data will appear as a bar graph with the units of measurement on the x axis and the measurement of the data on the y axis.
        • Media and text files will appear as a timeline of the items that you can scroll through.

        Use the scroll bar below the timeline to zoom in and out and move along the timeline.

        You can change timestream being shown by selecting an alternate datasource from the dropdown box above the timestream, and then clicking the update button.

        Delete a timestream by clickign its delete button. Please note that this does not delete the datasource.

        To author data

        You can author your data using your timestream.

        1. Click start
        2. Click on the timeline where you want the data in your timestream to begin.
        3. Click end.
        4. Click on the timeline where you want the data in your timestream to end. A green overlay should appear over the data range that you have chosen.
        5. Click head and then click the area in the timestream to begin playing from.
        6. Set the speed that the data plays out using the rate field (1=realtime, 2=double time, 0.5= half time, etc..)
        7. Click save

        Note that if your toggle on the “start / end time disabled:” checkbox then the timesream will continue to play data as new values come in. If this is toggled off and there is an endtime set, the the data will loop to the start once the end is reached.

        After you have authored your timestreams you can put them in blog posts, blog pages, or special timestreams pages.

      • Measurements

        Timestreams display measurements from a sensor or model. Measurements contain values at given points in time. These are grouped into measurement containers for a single sensor from a particular device. For instance your mobile phone may have a camera and accelerometer. Each of these would need its own measurement container.

        Measurement Container interface
        Measurement Container interface

        When you create a new measurement container you describe the sensor/modelling device and a little bit about what is being sensed. The newly created measurement container gets added to a list of the ones that you can view and share. Data can be uploaded to the a measurement container using the API. Measurement containers and their measurements may not be altered or deleted. Access to them is shared only with all users of the blog that they are created within by default.

        Clicking the view button reveals a list of all of the measurements that have been uploaded to the measurement container. The data is paginated so use the buttons at the bottom right of the screen to scroll forwards and backwards through the data.

        Clicking the share button reveals a list of other blogs that you can share the measurement container with. When a measurement container is shared with another blog, others can access it and add readings to it.
      • Context

        Context records describe the context that the measurements were collected within. These help annotate the data and make it easier to understand. Context can be about the measurement collection location, activities, sessions, or anything else you would like to use.

        Context interface
        Context interface

        The context table lists existing context records. To add a new record complete the form and click add context record. The start and end times are optional. If they are left blank then the context is considered to apply to the earliest or latest readings.

      • Replication

        Sometimes its useful to share measurements between blogs. If the blogs are all using the same WordPress multisite instance, then the measurement container can be shared from one blog to the other. However, if the blogs are hosted on different servers (such as if two different schools or communities want to share data with each other) then replication can be used to copy the measurements from one site to another. Replication can also be useful for transferring measurements from a private site to a long-term data archive or public site.

        Replication interface
        Replication interface

        To use replication complete the form and click add replication record. You need to know the table name of the measurement container you are transferring which can be found in the measurements record. You will also need to set up a measurement container on the destination Timestreams server, to generate a set of API keys on it and know the blog’s which can be found under settings > Timestreams. The following describes some additional options.

        There are two types of replication in Timestreams — discrete and continuous. Discrete replication means manually transferring the data. Continuous means that your new data will be automatically transferred. For continuous replication, toggle-on the “Continuous” option when adding the replication record. If it’s toggled-off then the record will be discrete and you will have to click the “Replicate” button on the record to copy your data across.

        Timestreams supports three types of measurements: standard data (such as temperature readings), image files and other media files. When image and media files are uploaded to Timestreams as measurements the files are placed in a folder on the server and the file location (URL) is stored as the measurement value. When replicating image and media files, you have the choice of whether to transfer the files to the destination (which will also update the URLs in the measurements to these new locations), or simply replicate the original measurement URLs. To copy your files across toggle-on the “Copy Files” option when adding the replication record.

      • Visualisations

        One of the main purposes of the Timestreams plugin is to make it easy to insert visualisations into blogs about the measurements you take. In Timestreams, visualisations are javascript programs that read measurements from a Timestream and render the data in some way. Visualisations can be embedded into WordPress posts and pages (see Timestream Pages and Posts for information on how to do this). The visualisations interface lists the visualisations that are currently available to use in posts and pages.

        Visualisation interface
        Visualisation interface
      • Timestream Pages and Posts

        Timestream visualisations can be embedded into WordPress blog posts, pages, and Timestream Pages. The visualisations render measurements in accordance to the state of the corresponding timestream. Visualisations are automatically updated as the timestream play head moves through the data. Timestream pages are similar to regular WordPress pages, except they don’t have any of the theme styles or page menu items that a regular page does. They present a plain backdrop for visualisations. To add a visualisation into a regular page, timestream page or post click on the corresponding left menu add new menu item.

        Timestream pages
        Timestream pages

    Add a title for the new page or post displays then make sure it is displaying the visual editor.

    Add new Timestream Page
    Add new Timestream Page

    Click the “Insert Timestream button” (the yellow smiley face button), which brings up the “Insert a Timestream Visualisation” interface.

    Insert a Timestream Visualisation interface
    Insert a Timestream Visualisation interface

    Then select the timestream and visualisation from the drop down menus and click the “Insert Visualisation” button. This will embed a short code into the editor. You can add additional text and media around the code as you see fit. You may add as many visualisations into a page as you like. Adding multiple visualisations is useful for comparing data and showing multiple sensors at a time.

    Example visualisation
    Example visualisation
    • API Keys

      The Timestreams plugin provides a facility (the API) to upload and access measurements and timestreams from external applications.

      To access most parts of the API, your applications will need keys which are like passwords for the applications. These keys let the applications act on your behalf with the same access rights that your WordPress user account has.

      Like your user name and password, there’s a public key and a private key. You can generate as many pairs of keys that you would like and put them into each application you run. If you are concerned that a key pair may have become insecure, you can easily revoke that pair and replace it with a new one you generate. Since it’s so simple to generate them you never have to reuse key pairs (which you shouldn’t do because it’s insecure to use the same passwords for more than one application).

      To get your keys click the API keys menu item and click the “Create New API Keys” button. This will add a new pair of unique keys to your list.

      Api Key Interface
      Api Key Interface

      If you want to see a private key click the pertinent row’s “Reveal private key” button. Click “Revoke key” to disable the key pair.

    • Timestreams Settings

      There are a few settings to note accessed by going to the Settings > Timestreams left-menu.

      Settings Interface
      Settings Interface

      The settings that are displayed are the site id and blog id, as well as an area to add in proxy settings if your server accesses the Internet from behind a proxyy server (leave these fields blank if it doesn’t).

      Proxy settings
      Proxy settings
  3. Adding visualisations

    The Timestreams plugin comes with a set of default visualisations, however we hope that you will be inspired to create your own ways to artistically render your measurements. Adding visualisations requires a little bit of WordPress and Javascript knowledge, and a tiny bit of PHP knowledge. You will also need access to the plugin files on the server, or a helpful administrator who can help you access/upload the files. This section walks through adding a new visualisation to the plugin.

    Like all WordPress plugins, the Timestreams plugin is a folder containing other folders and files. To add visualisations, you add a new sub-folder to the Timestreams plugin “visualisations” sub-folder. You can call your plugin anything you want, but it’s your responsibility to make sure the name is unique compared with the other visualisation names. You need two files in your sub-folder, viz.php and a javascript file called whatever you like with a “.js” file suffix. It’s easiest to copy these files from an existing visualisation such as SimpleText. These instructions presume you have copied SimpleText files to a new visualisation folder called RedText.

    Very little of viz.php needs to be changed, so we’ll start with it. Open it up and globally replace the name “SimpleText” with the name of your visualisation (such as RedText). Next, change the echoed text in the describe function to describe what this visualisation does (for example “Text view of data rendered in red.”). Finally, globally replace “timestream-simple” with “timestream-” whereis some descriptor such as “redtext”. Save and close the file.

    Next you need to edit timestream-simple.js. Begin by changing its name to timestream-.js. Now open the file. Again, globally replace “SimpleText” with the name of your visualisation. Ignore the init function, the magic happens in onMeta and onData. The onMeta function gets called when your visualisation is first rendered on a page and sets up the visualisation based on the measurement container metadata. The onData function is calledas new data is made available from the play head of the Timestream. Modify these functions to generate your visualisation. Have a look at the GuageViz visualisation to see its modifications. The GuageViz plugin uses D3 to render its visualisation. For GuageViz whenever onData is called, it calls a drawPointer function which positions the visualisation pointer to its new position.

  4. User stories and cases

    Below are short explanations of how Timestreams might be used. These are the main use cases that the Relate project team considered when developing the plugin. Timestreams was designed to support artists to interacting with community and school groups, and for the general public to view visualisations. In addition, Timestreams was designed to support scientists and researchers to study bigger picture views into how artists and communities can engage with the data. Artists, community members, researchers and web audience are the main types of users in the stories below.

      • Performing existing data

        User Story

        As an artist, I want to create performances out of existing data. This data may have been previously collected by the audience I’m engaging, or come from other trusted sources such as the Met Office. Creating performances out of existing data will allow me to generate performative artworks (such as visual, aural, or machines) for public engagement in situations where liveness is not possible (such as in disconnected environments) or relevant (such as when performing historic data).

        Use Case

        Description

        Performing existing data is about setting up a timestream for a measurement container with data in it and then visualising (or otherwise outputting) the timestream.

        Precondition

        The artist has a timestream blog account. A measurement container exists and has some data in it. Also, the output method (such as a visualisation) exists.

        Flow

        An artist logs in to the timestreams blog and clicks on the Timestreams left-menu. The artist creates a new timestream using the timestream creation form and selecting the appropriate measurement container. The timestream is presented to the artist showing the data as a timeline chart. The artist looks over the data and sets the start time and end time for the performance as well as the play head rate. Then the artist sets the start position of the play head and saves the timestream. The timestream begins to play. The artist adds a new page, post or timestream page from the appropriate left-menu to which the artist adds the timestream, selecting the appropriate visualisation and saves the post or page. Now the artist provides the URL to the post or page to the audience.

        Alternative Flow

        Alternatively, instead of adding a visualisation to the post or page, the artist uses an application that was written outside of WordPress (perhaps in Java, Python, using Unity, or Arduino) to access the Timestreams API and perform the data.

      • Performing live data

        User Story

        As an artist, I want to create performances out of live data. This data will be highly relevant to the audience I’m engaging, such as using their own data streams. The data may also come from additional communities that my audience are aware of, such as linking live data from a Nottingham school group with their friends in Brazil. Creating performances out of live data will allow me to generate performative artworks (such as visual, aural, or machines) for public engagement in situations where liveness excites and engages the audience in ways that recorded data does not.

        Use Case

        Description

        Performing live data is about setting up a timestream for a measurement container that may be empty or contain some data but visualising (or otherwise outputting) the timestream as new data is added to it in real time.

        Precondition

        The artist has a timestream blog account. A measurement container exists which may or may not have data in it. Also, the output method (such as a visualisation) exists.

        Flow

        An artist logs in to the timestreams blog and clicks on the Timestreams left-menu. The artist creates a new timestream using the timestream creation form and selecting the appropriate measurement container. The timestream is presented to the artist either showing existing data or empty. The artist toggles the start/end time disabled option, sets the play rate to 1 and saves the timestream. The timestream plays as new data is added to the corresponding measurement container. The artist outputs the timestream as per the Performing existing data use case.

      • Collecting new data

        User Story

        As a community member, I want to be able to use Timestreams to collect energy and environmental data from fixed locations and as I move around. This will help me to better understand energy use and climate change, as well as to engage in dialog about related issues. It will also help me with maintaining a long-term archive of my data for future review.

        Use Case

        Description

        Collecting new data is about creating a measurement container and adding data to it.

        Precondition

        A community member has a timestream blog account.

        Flow

        A community member logs in to a timestreams blog and selects the measurements timestreams left-submenu. The community member completes the add measurement container form and clicks add metadata record. The s/he makes a note of the table name. The community member then selects the API Keys timestreams left-submenu and generates a new set of keys, making a note of both values. The community member then configures her/his data upload application with the table name and keys. After the application is started, the community member views the data for the measurement container to make sure that data is being transferred correctly.

      • Sharing data

        User Story

        Both as an artist and as a community member, I want to share the data in my blog with other blogs, and access data from other blogs that permit me. This lets me become part of a wider community and better understand and perform community data.

        Use Case

        Description

        Sharing data is about providing measurement access from one timestreams blog to another, whether those blogs are part of the same WordPress multisite instance or not.

        Precondition

        Two blogs exist and the first one (the source) has a measurement container.

        Flow

        The user, a community member or artist, wishes to share a measurement container with one or more other blogs in the same multisite instance. S/he logs in to a timestreams blog and selects the measurements timestreams left-submenu, then clicks the Share button next to the source measurement container. S/he ticks the blogs to share the data with and clicks save.

        Alternative Flow

        Alternative, if s/he wants to share data across WordPress instances, then s/he should follow the replication instructions.

      • Keeping data in synch

        User Story

        As a community member, I want to capture data during times when my Internet connection isn’t stable. Then I want to synchronise my local copy of the data with a long-term data archive when my Internet connection improves. This will benefit me because my data won’t be lost when the network connection isn’t reliable.

        Use Case

        Description

        Synchronising data is copying measurements from one timestreams blog to another across WordPress instances. This allows users to store data locally and move it to a server in the Cloud when it’s convinient for them. It also allows data to be kept up to date across shared public server instances.

        Precondition

        Two blogs exist on different servers (the source may be an instance of WordPress running locally to the user) which each have measurement containers set up.

        Flow

        A community member wants to keep a measurement container on a local server in sync with one running on a cloud-hosted server. S/he logs in to the destination timestreams blog and creates API keys to access it and makes anote of the keys as well as the table name of the measurement container and the blog id from settings > Timestreams left-submenu. The user then logs in to the source local blog and selects the replication timestreams left-submenu. The user completes the form toggling on the “Continuous” option so that new data is automatically replicated.

        Alternative Flow

        Alternatively, if the user didn’t expect more data to arrive in the source measurement container, then s/he would complete the steps above, but leave “Continuous” toggled-off.

      • Comparing data

        User Story

        As an artist and researcher I want to be able to compare and contrast data from multiple data sources. This will help me to better represent community data and engage others in artistic interventions.

        Use Case

        Description

        Timestreams can be used to view multiple measurement containers at the same time in order to compare and contrast them, as well as to show relationships between them.

        Precondition

        The artist’s blog has access to measurement containers from multiple communities.

        Flow

        An artist wants to make a webpage with measurements (for example CO2) collected from school groups in different countries in order to show the school children the similarities and differences between their environments. The artist logs in to the timestreams enabled blog and adds timestreams for each of the measurement containers to be compared. S/he sets the start times, end times, rates, and playhead start points to the same values. After the timestreams are set up the artist creates a post, page or timestream page. S/he inserts visualisations or each timestream and embellishes the page with additional information (text, pictures, etc) to help the audience understand the data.

        Alternative Flow

        Alternatively, the artist could design a visualisation that fuses multiple timestreams together. The artist could also use the Timestream API to populate applications and services from multiple timestreams.

      • Adding a new community blog

        User Story

        As an artist I want to be able to introduce new communities to my work and give them their own blogs within my own network so that they can start to collect and share measurements about their environment. This will help me to engage a broader audience and widen the discussion about energy and climate change through art.

        Use Case

        Description

        It’s pretty easy to install WordPress on most web servers in multi-site mode. This means artists can add as many timestreams enabled blogs as they want and manage the data sharing within their own WordPress networks.

        Precondition

        An artist (the user) has access to a multi-site enabled WordPress installation. The user has network administration rights.

        Flow

    The user wants to add a new timestreams blog to thee network. S/he logs in as a network administrator, clicks the “Add New” Sites left submenu, and completes the form. If the timestreams plugin has been activated network-wide then timestreams is automatically available to the new blog. Otherwise the user will need to switch to the new blog by clicking its “Dashboard” submenu (viewable by rolling over its name in the sites list) then selecting the “Plugins” left menu and activating the Timestreams plugin.

    Sites interface
    Sites interface

    Once the plugin is activated the user should go into the “Settings” “Timestreams” submenu and complete the settings form as appropriate.

Scaling artistic practice and public engagement to understand energy and climate change…