ScrollableGraphView

Announcements

9-7-2017 - Version 4:

Version 4 was released which adds multiple plots, dynamic reloading of values, more reference line customisation options and various bug fixes.

You can see the major changes in the API here.

The public interface is incompatible with previous versions. If you prefer to keep using the older version, make sure to specify version 3 in your podfile or downloaded the classes from a pre-v4 release.

About

An adaptive scrollable graph view for iOS to visualise simple discrete datasets. Written in Swift. Originally written for a small personal project.

The main goal of the this graph component is to visualise simple discrete datasets and allow the the user to scroll through the graph.

Contribution

All pull requests are welcome. There is a list of features people would like on the issues page, ranging from simple changes to quite complex. Feel free to jump on in.

Sponsors

Development of this component has been sponsored by Anomaly. Check them out here.

Contents

• Features
• Basic Usage
• Customisation
• Customisation Examples
• Improvements
• Other

Features

Feature List
Initialisation animations and range adaption animations.
Multiple plots and dynamic reloading of the values.
Range adaption when scrolling through the graph. The range of the y-axis will automatically adapt to to the min and max of the visible points.
Smooth scrolling around the graph.
Handles as many points as you can throw at it.
Many customisation options. (Check the customisation section)

Usage

Adding the ScrollableGraphView to your project:

Add the ScrollableGraphView class to your project. There are two ways to add the ScrollableGraphView to your project.

Manually

Add all of the files in the Classes directory to your project in Xcode to your project in Xcode.

CocoaPods

Add pod 'ScrollableGraphView' to your Podfile and then make sure to import ScrollableGraphView in your code.

Carthage

Add github "philackm/ScrollableGraphView" ~> 4.0.2 to your Cartfile and then make sure to link the frameworks and import ScrollableGraphView in your code.

Creating a graph and providing it with data.

1. Create a ScrollableGraphView instance. The graph requires a data source, which is an object that conforms to the ScrollableGraphViewDataSource protocol.

   // Compose the graph view by creating a graph, then adding any plots
   // and reference lines before adding the graph to the view hierarchy.
   let graphView = ScrollableGraphView(frame: frame, dataSource: self)
   
   let linePlot = LinePlot(identifier: "line") // Identifier should be unique for each plot.
   let referenceLines = ReferenceLines()
   
   graphView.addPlot(plot: linePlot)
   graphView.addReferenceLines(referenceLines: referenceLines)
   

2. Ensure the dataSource object conforms to the ScrollableGraphViewDataSource protocol and implements the following three methods like so:

   func value(forPlot plot: Plot, atIndex pointIndex: Int) -> Double {
       // Return the data for each plot.
       switch(plot.identifier) { 
       case "line":
           return linePlotData[pointIndex]
       default:
           return 0
       }
   }
   
   func label(atIndex pointIndex: Int) -> String {
       return "FEB \(pointIndex)"
   }
   
   func numberOfPoints() -> Int {
       return numberOfDataPointsInGraph
   }
   

3. Finally, add the ScrollableGraphView to the view hierarchy.

   someViewController.view.addSubview(graphView)
   

This will create a graph that looks something like:

Interface Builder support

There is now support for Interface Builder (from CocoaPod version 2.0.0). See the example project in the folder: graphview_example_ib

Things you could use it for:

• ✔ Study applications to show time studied/etc
• ✔ Weather applications
• ✔ Prototyping
• ✔ Simple data visualisation

Things you shouldn’t/cannot use it for:

• ✘ Rigorous statistical software
• ✘ Important & complex data visualisation
• ✘ Graphing continuous mathematical functions

Customisation

The entire graph is composed by initially creating an empty ScrollableGraphView object and progressively adding whatever plots and reference lines you require.

Create a plot using the any of the LinePlot, DotPlot, BarPlot constructors. Create reference lines using the ReferenceLines() constructor. Before adding the ScrollableGraphView object to the view hierarchy, add the plots and reference lines to the graph using the addPlot and addReferenceLines methods. You can add multiple plots (examples are shown below). Each plot must have the same number of data points.

In the case of interface builder, graph customisation is performed via the properties pane, whilst plots and reference lines customisation is done in the corresponding view controller. See the example project in the folder: graphview_example_ib

Graph Customisation

These settings can be set directly on the ScrollableGraphView object before adding it to the view hierarchy.

Adapting & Animations

Property	Description
shouldAdaptRange: Bool	Whether or not the y-axis’ range should adapt to the points that are visible on screen. This means if there are only 5 points visible on screen at any given time, the maximum on the y-axis will be the maximum of those 5 points. This is updated automatically as the user scrolls along the graph.
shouldAnimateOnAdapt: Bool	If shouldAdaptRange is set to true then this specifies whether or not the points on the graph should animate to their new positions. Default is set to true. Looks very janky if set to false.
shouldAnimateOnStartup: Bool	Whether or not the graph should animate to their positions when the graph is first displayed.

Spacing

Graph Range

Plot Customisation

For all plots you can specify animation related information for when the plot first appears and during adaptions.

Animation

LinePlot

Line plot specific customisation options. These options are available on any LinePlot object.

Line Styles

Fill Styles

DotPlot

Dot plot specific customisation options. These options are available on any DotPlot object.

BarPlot

Bar plot specific customisation options. These options are available on any BarPlot object.

Reference Line Customisation

These options are set on the ReferenceLines object before adding it to the graph view.

Reference Lines

Reference Line Labels (y-axis)

Data Point Labels (x-axis)

Customisation Examples

All of these examples can be seen in action in the example project: graphview_example_code

Open the project in Xcode and hit run.

Note: Examples here use a “colorFromHex” extension for UIColor.

Default

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

let linePlot = LinePlot(identifier: "simple") // Identifier should be unique for each plot.
let referenceLines = ReferenceLines()

graphView.addPlot(plot: linePlot)
graphView.addReferenceLines(referenceLines: referenceLines)

Bar Dark (Bar layer thanks to @RedBlueThing)

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

// Setup the plot
let barPlot = BarPlot(identifier: "bar")

barPlot.barWidth = 25
barPlot.barLineWidth = 1
barPlot.barLineColor = UIColor.colorFromHex(hexString: "#777777")
barPlot.barColor = UIColor.colorFromHex(hexString: "#555555")

barPlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic
barPlot.animationDuration = 1.5

// Setup the reference lines
let referenceLines = ReferenceLines()

referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 8)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.2)
referenceLines.referenceLineLabelColor = UIColor.white

referenceLines.dataPointLabelColor = UIColor.white.withAlphaComponent(0.5)

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#333333")

graphView.shouldAnimateOnStartup = true

graphView.rangeMax = 100
graphView.rangeMin = 0

// Add everything
graphView.addPlot(plot: barPlot)
graphView.addReferenceLines(referenceLines: referenceLines)
return graphView

Smooth Dark

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

// Setup the line plot.
let linePlot = LinePlot(identifier: "darkLine")

linePlot.lineWidth = 1
linePlot.lineColor = UIColor.colorFromHex(hexString: "#777777")
linePlot.lineStyle = ScrollableGraphViewLineStyle.smooth

linePlot.shouldFill = true
linePlot.fillType = ScrollableGraphViewFillType.gradient
linePlot.fillGradientType = ScrollableGraphViewGradientType.linear
linePlot.fillGradientStartColor = UIColor.colorFromHex(hexString: "#555555")
linePlot.fillGradientEndColor = UIColor.colorFromHex(hexString: "#444444")

linePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

let dotPlot = DotPlot(identifier: "darkLineDot") // Add dots as well.
dotPlot.dataPointSize = 2
dotPlot.dataPointFillColor = UIColor.white

dotPlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// Setup the reference lines.
let referenceLines = ReferenceLines()

referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 8)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.2)
referenceLines.referenceLineLabelColor = UIColor.white

referenceLines.positionType = .absolute
// Reference lines will be shown at these values on the y-axis.
referenceLines.absolutePositions = [10, 20, 25, 30]
referenceLines.includeMinMax = false

referenceLines.dataPointLabelColor = UIColor.white.withAlphaComponent(0.5)

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#333333")
graphView.dataPointSpacing = 80

graphView.shouldAnimateOnStartup = true
graphView.shouldAdaptRange = true
graphView.shouldRangeAlwaysStartAtZero = true

graphView.rangeMax = 50

// Add everything to the graph.
graphView.addReferenceLines(referenceLines: referenceLines)
graphView.addPlot(plot: linePlot)
graphView.addPlot(plot: dotPlot)

Dot

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

// Setup the plot
let plot = DotPlot(identifier: "dot")

plot.dataPointSize = 5
plot.dataPointFillColor = UIColor.white

// Setup the reference lines
let referenceLines = ReferenceLines()
referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 10)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.5)
referenceLines.referenceLineLabelColor = UIColor.white
referenceLines.referenceLinePosition = ScrollableGraphViewReferenceLinePosition.both

referenceLines.shouldShowLabels = false

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#00BFFF")
graphView.shouldAdaptRange = false
graphView.shouldAnimateOnAdapt = false
graphView.shouldAnimateOnStartup = false

graphView.dataPointSpacing = 25
graphView.rangeMax = 50
graphView.rangeMin = 0

// Add everything
graphView.addPlot(plot: plot)
graphView.addReferenceLines(referenceLines: referenceLines)

Pink

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

// Setup the plot
let linePlot = LinePlot(identifier: "pinkLine")

linePlot.lineColor = UIColor.clear
linePlot.shouldFill = true
linePlot.fillColor = UIColor.colorFromHex(hexString: "#FF0080")

// Setup the reference lines
let referenceLines = ReferenceLines()

referenceLines.referenceLineThickness = 1
referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 10)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.5)
referenceLines.referenceLineLabelColor = UIColor.white
referenceLines.referenceLinePosition = ScrollableGraphViewReferenceLinePosition.both

referenceLines.dataPointLabelFont = UIFont.boldSystemFont(ofSize: 10)
referenceLines.dataPointLabelColor = UIColor.white
referenceLines.dataPointLabelsSparsity = 3

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#222222")

graphView.dataPointSpacing = 60
graphView.shouldAdaptRange = true

// Add everything
graphView.addPlot(plot: linePlot)
graphView.addReferenceLines(referenceLines: referenceLines)

Multiple Plots v1

// Setup the line plot.
let blueLinePlot = LinePlot(identifier: "multiBlue")

blueLinePlot.lineWidth = 1
blueLinePlot.lineColor = UIColor.colorFromHex(hexString: "#16aafc")
blueLinePlot.lineStyle = ScrollableGraphViewLineStyle.smooth

blueLinePlot.shouldFill = true
blueLinePlot.fillType = ScrollableGraphViewFillType.solid
blueLinePlot.fillColor = UIColor.colorFromHex(hexString: "#16aafc").withAlphaComponent(0.5)

blueLinePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// Setup the second line plot.
let orangeLinePlot = LinePlot(identifier: "multiOrange")

orangeLinePlot.lineWidth = 1
orangeLinePlot.lineColor = UIColor.colorFromHex(hexString: "#ff7d78")
orangeLinePlot.lineStyle = ScrollableGraphViewLineStyle.smooth

orangeLinePlot.shouldFill = true
orangeLinePlot.fillType = ScrollableGraphViewFillType.solid
orangeLinePlot.fillColor = UIColor.colorFromHex(hexString: "#ff7d78").withAlphaComponent(0.5)

orangeLinePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// Setup the reference lines.
let referenceLines = ReferenceLines()

referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 8)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.2)
referenceLines.referenceLineLabelColor = UIColor.white

referenceLines.dataPointLabelColor = UIColor.white.withAlphaComponent(1)

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#333333")

graphView.dataPointSpacing = 80
graphView.shouldAnimateOnStartup = true
graphView.shouldAdaptRange = true

graphView.shouldRangeAlwaysStartAtZero = true

// Add everything to the graph.
graphView.addReferenceLines(referenceLines: referenceLines)
graphView.addPlot(plot: blueLinePlot)
graphView.addPlot(plot: orangeLinePlot)

Multiple Plots v2

It is possible to combine multiple plots to get different looks. We use the the dot plot to add markers to the line plot in this case:

let graphView = ScrollableGraphView(frame: frame, dataSource: self)

// Setup the first plot.
let blueLinePlot = LinePlot(identifier: "multiBlue")

blueLinePlot.lineColor = UIColor.colorFromHex(hexString: "#16aafc")
blueLinePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// dots on the line
let blueDotPlot = DotPlot(identifier: "multiBlueDot")
blueDotPlot.dataPointType = ScrollableGraphViewDataPointType.circle
blueDotPlot.dataPointSize = 5
blueDotPlot.dataPointFillColor = UIColor.colorFromHex(hexString: "#16aafc")

blueDotPlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// Setup the second plot.
let orangeLinePlot = LinePlot(identifier: "multiOrange")

orangeLinePlot.lineColor = UIColor.colorFromHex(hexString: "#ff7d78")
orangeLinePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// squares on the line
let orangeSquarePlot = DotPlot(identifier: "multiOrangeSquare")
orangeSquarePlot.dataPointType = ScrollableGraphViewDataPointType.square
orangeSquarePlot.dataPointSize = 5
orangeSquarePlot.dataPointFillColor = UIColor.colorFromHex(hexString: "#ff7d78")

orangeSquarePlot.adaptAnimationType = ScrollableGraphViewAnimationType.elastic

// Setup the reference lines.
let referenceLines = ReferenceLines()

referenceLines.referenceLineLabelFont = UIFont.boldSystemFont(ofSize: 8)
referenceLines.referenceLineColor = UIColor.white.withAlphaComponent(0.2)
referenceLines.referenceLineLabelColor = UIColor.white
referenceLines.relativePositions = [0, 0.2, 0.4, 0.6, 0.8, 1]

referenceLines.dataPointLabelColor = UIColor.white.withAlphaComponent(1)

// Setup the graph
graphView.backgroundFillColor = UIColor.colorFromHex(hexString: "#333333")

graphView.dataPointSpacing = 80

graphView.shouldAnimateOnStartup = true
graphView.shouldAdaptRange = true
graphView.shouldRangeAlwaysStartAtZero = true

// Add everything to the graph.
graphView.addReferenceLines(referenceLines: referenceLines)
graphView.addPlot(plot: blueLinePlot)
graphView.addPlot(plot: blueDotPlot)
graphView.addPlot(plot: orangeLinePlot)
graphView.addPlot(plot: orangeSquarePlot)

Known Issues

• Some aspects of the graph cannot be customised after it has been added to the view hierarchy.
• Reloading the graph with a different number of data items is currently not supported.
• Performance in the simulator is not great.

If you find any bugs please create an issue on Github.

Other

Follow me on twitter for interesting updates (read: gifs) about other things that I make.