“Neowit Playground” - in early Beta

You access the Playground with the following URL: https://app.neowit.io/insights/playground

How It Works ⚙️

You’ll create one or more data sources listing the sources of sensor data you want. Then you'll write a single line of text, called a query, to specify what we should do with the source data before giving it to you. You will also specify the resolution that you want the resulting data to have and the time period it should cover.

Data sources

To create a new data source, click the “New data source” text field, enter a name of your choosing, e.g. room_4, and press enter. You can now select among different sources of sensor data. These can be specific physical or virtual devices, or groups of devices with the same space, integration or user tag. You can add as many sources as you want. You can also restrict which sensor types you want to include in the data of each source.

Query

The query can be as simple as the name of a data source, which will give you the raw data from the source. But usually you’ll want to do something with the data first, like combining data from different devices. For this, you can use functions. A function consists of a name, like agg, followed by a set of arguments enclosed in parentheses, as in agg(room_4, “avg”). There can be different types of arguments:

• Data sources: Names of data sources defined by you, like room_4.

• Strings: Text enclosed in double quotes, like “avg”.

• Numbers: Simple numbers, like 123 or 45.67.

• Lists: A list of items in square brackets, like [room_4, room_5]. The items could be of any type.

• Functions: The output of one function, like agg(room_4, “avg”), can be used as an argument in another function, as in combine(agg(room_4, “avg”), “avg”).

You will find a list of available functions and their arguments below.

Resolution

You can choose which time resolution (e.g. minutes, hours, days) you want for the data returned to you. This resolution will be used by the functions in your query that change the resolution of the input data, like agg. If your query does not contain any such functions, the data will automatically be converted to this resolution before you obtain it.

Time period

You can adjust the first and last date and time of day for the output data. If you request a long time period, you may have to switch to a coarser resolution, otherwise there would be too much data to return.

Common Functions 🛠️

These are the main tools you'll use to build your queries.

agg(data, method, fillna)
Aggregates (or downsamples) data over time for each series individually. It's useful for changing the resolution of your data, like turning one-second data points into one-hour averages. It works like this: each time series in the input data gets divided into multiple intervals based on your selected output resolution. So if the output resolution is one hour, each interval will be one hour long. Then all values that fall into the same interval are combined using the specified aggregation method, and the result becomes the value for that time interval in the output series. 

• data: The data you want to aggregate, usually specified as a data source.
• method: The aggregation method. Must be one of the following strings: “avg”, “sum”, “max”, “min”, “lastValue” or “auto” (see explanations further down).
• fillna: Optional, assumed false by default. Use true to fill in missing data gaps by repeating the previous value before aggregating.

Example
You have defined a data source people_count_device containing a device with people count data, and selected hourly output resolution. agg(people_count_device, “max”) will give you the maximum number of people for each hour that the sensor reported a people count. agg(people_count_device, “max”, true) (that is, enabling the fillna option) will fill in missing counts with the previous count before aggregating (effectively assuming that the people count will stay the same until a new count is reported), giving you the maximum number of people for every hour.

 

avg(data, fillna)
Aggregates the data over time by averaging. Shorthand for agg(data, “avg”, fillna).

sum(data, fillna)
Aggregates the data over time by summing. Shorthand for agg(data, “sum”, fillna).

max(data, fillna)
Aggregates the data over time by taking the maximum. Shorthand for agg(data, “max”, fillna).

min(data, fillna)
Aggregates the data over time by taking the minimum. Shorthand for agg(data, “min”, fillna).

combine(data, method, fillna)
Combines data from multiple devices into a single series for each sensor type. It's perfect for getting an overall picture, like the average temperature across all devices in a room.

• data: The data you want to combine, usually specified as a data source containing multiple devices or a function (like agg) that returns data for multiple devices. It could also be a list of multiple data sources or functions.
• method: The aggregation method to use when combining the values from different devices. Must be one of the following strings: “avg”, “sum”, “max”, “min”, “lastValue” or “auto” (see explanations further down).
• fillna: Optional, assumed false by default. Use true to fill in missing data gaps by repeating the previous values before combining.
• neverFillEmptyRows: Optional, assumed false by default. When the fillna option is enabled, this can be set to true to avoid filling in missing data at times when none of the devices reported a value.
  
  

Example
You have defined a data source temp_devices containing multiple devices that report a temperature every whole minute. combine(temp_devices, “avg”) will give you the average of the temperatures reported by the devices every minute. But what if the devices reported their readings at different times during each minute? To combine values from different sensors, they must be known at the same exact time, so we would have to aggregate the data to “line up” the values before combining them: combine(agg(temp_devices, “avg”), “avg”). For data types like people count or presence, where the value stays the same until a new value is reported, a simpler way to make sure the values “line up” before combining them is to fill in missing values with previous values by enabling the fillna option: combine(people_count_devices, true).

 

clipday(data, startTime, endTime)
Restricts your data to a specific time window within a day.

⚠️ Warning: This function operates in UTC time only.

• data: The data you want to restrict, usually specified as a data source.
• startTime/endTime: The start and end times in seconds from midnight (e.g., 09:00 is 9*60*60=32400).
  
  

Example
clipday(room_4, 8*60*60, 18*60*60) clips the data to the hours between 08:00 and 18:00 UTC.

weekdays(data, dayIndices)
Filters your data to only include specific days of the week.

⚠️ Warning: This function operates in UTC time only.

• data: The data you want to filter, usually specified as a data source.
• dayIndices: A list of numbers for which weekdays to include, where Monday is 0 and Sunday is 6.
  
  

Example
weekdays(room_4, [0, 1, 2, 3, 4]) filters for data from Monday to Friday.

Aggregation Methods

When using agg or combine, you need to specify how to combine the data points.

• “avg”: The average value.
• “sum”: The sum of the values.
• “max”: The highest value.
• “min”: The lowest value.
• “lastValue”: The most recent value.
• “auto”: We try to select a suitable method automatically based on the kind of data.