-Start by setting up your data, scales, and dataset:
+Start by setting up your data, dimensions, axes, and dataset:
```elixir
data = [
@@ -38,44 +38,39 @@ data = [
%{date: ~D[2023-08-05], value: 50.0}
]
-date_scale = date_scale(Date.range(~D[2023-08-01], ~D[2023-08-05]))
-number_scale = number_scale(0.0, 80.0)
+dimensions = Plox.Dimensions.new(800, 250)
-dataset =
- dataset(data,
- x: {date_scale, & &1.date},
- y: {number_scale, & &1.value}
- )
-```
+x_axis = Plox.XAxis.new(
+ Plox.DateScale.new(Date.range(~D[2023-08-01], ~D[2023-08-05])),
+ dimensions
+)
-Once you have those, you can build a `Plox.Graph` struct:
+y_axis = Plox.YAxis.new(Plox.NumberScale.new(0.0, 80.0), dimensions)
-```elixir
-example_graph =
- to_graph(
- scales: [date_scale: date_scale, number_scale: number_scale],
- datasets: [dataset: dataset]
+dataset =
+ Plox.Dataset.new(data,
+ x: {x_axis, & &1.date},
+ y: {y_axis, & &1.value}
)
```
-Finally, render the `Plox.Graph` directly within your HEEx template:
+Once you have those, you can render a `graph` component within your HEEx template:
```html
-<.graph :let={graph} id="example_graph" for={@example_graph} width="800" height="250">
- <:legend>
- <.legend_item color="#EC7E16" label="Data" />
-
+<.graph id="example_graph" dimensions={@dimensions}>
+ <.x_axis_labels :let={date} axis={@x_axis}>
+ {Calendar.strftime(date, "%-m/%-d")}
+
- <.x_axis :let={date} scale={graph[:date_scale]}>
- <%= Calendar.strftime(date, "%-m/%-d") %>
-
+ <.y_axis_labels :let={value} axis={@y_axis} ticks={5}>
+ {value}
+
- <.y_axis :let={value} scale={graph[:number_scale]} ticks={5}>
- <%= value %>
-
+ <.x_axis_grid_lines axis={@x_axis} stroke="#D3D3D3" />
+ <.y_axis_grid_lines axis={@y_axis} ticks={5} stroke="#D3D3D3" />
- <.line_plot dataset={graph[:dataset]} color="#EC7E16" />
+ <.polyline points={points(@dataset[:x], @dataset[:y])} stroke="#EC7E16" stroke-width={2} />
- <.points_plot dataset={graph[:dataset]} color="#EC7E16" />
+ <.circle cx={@dataset[:x]} cy={@dataset[:y]} r={3} fill="#EC7E16" />
```
diff --git a/docs/migration_guide.md b/docs/migration_guide.md
new file mode 100644
index 0000000..92debdb
--- /dev/null
+++ b/docs/migration_guide.md
@@ -0,0 +1,112 @@
+# Plox Migration Guide (0.2.0 to X.X.X)
+
+Plox has gone through a major philosophical rewrite since its initial publication. This
+guide will help users convert their current Plox graphs over to the new approach.
+
+## Example of 0.2.0 usage
+
+1. Set up data, scales, and dataset:
+
+```elixir
+data = [
+ %{date: ~D[2023-08-01], value: 35.0},
+ %{date: ~D[2023-08-02], value: 60.0},
+ %{date: ~D[2023-08-03], value: 65.0},
+ %{date: ~D[2023-08-04], value: 10.0},
+ %{date: ~D[2023-08-05], value: 50.0}
+]
+
+date_scale = date_scale(Date.range(~D[2023-08-01], ~D[2023-08-05]))
+number_scale = number_scale(0.0, 80.0)
+
+dataset =
+ dataset(data,
+ x: {date_scale, & &1.date},
+ y: {number_scale, & &1.value}
+ )
+```
+
+2. Build a `Plox.Graph` struct:
+
+```elixir
+example_graph =
+ to_graph(
+ scales: [date_scale: date_scale, number_scale: number_scale],
+ datasets: [dataset: dataset]
+ )
+```
+
+3. Render the `Plox.Graph` within your HEEx template:
+
+```html
+<.graph :let={graph} id="example_graph" for={@example_graph} width="800" height="250">
+ <.x_axis :let={date} scale={graph[:date_scale]}>
+ {Calendar.strftime(date, "%-m/%-d")}
+
+
+ <.y_axis :let={value} scale={graph[:number_scale]} ticks={5}>
+ {value}
+
+
+ <.line_plot dataset={graph[:dataset]} color="#EC7E16" />
+
+ <.points_plot dataset={graph[:dataset]} color="#EC7E16" />
+
+```
+
+## Example of X.X.X usage
+
+1. Set up data, dimensions, axes, and dataset:
+
+```elixir
+data = [
+ %{date: ~D[2023-08-01], value: 35.0},
+ %{date: ~D[2023-08-02], value: 60.0},
+ %{date: ~D[2023-08-03], value: 65.0},
+ %{date: ~D[2023-08-04], value: 10.0},
+ %{date: ~D[2023-08-05], value: 50.0}
+]
+
+# Instead of passing the height and width via the `graph` component,
+# create Dimensions and pass them to each Axis
+dimensions = Plox.Dimensions.new(800, 250)
+
+# Instead of creating separate Scales, we need them when creating our Axes
+x_axis = Plox.XAxis.new(
+ Plox.DateScale.new(Date.range(~D[2023-08-01], ~D[2023-08-05])),
+ dimensions
+)
+
+y_axis = Plox.YAxis.new(Plox.NumberScale.new(0.0, 80.0), dimensions)
+
+# Create a Dataset with our Axes
+dataset =
+ Plox.Dataset.new(data,
+ x: {x_axis, & &1.date},
+ y: {y_axis, & &1.value}
+ )
+```
+
+2. Render the `graph` component within your HEEx template:
+
+```html
+<.graph id="example_graph" dimensions={@dimensions}>
+
+ <.x_axis_labels :let={date} axis={@x_axis}>
+ {Calendar.strftime(date, "%-m/%-d")}
+
+
+ <.y_axis_labels :let={value} axis={@y_axis} ticks={5}>
+ {value}
+
+
+ <.x_axis_grid_lines axis={@x_axis} stroke="#D3D3D3" />
+ <.y_axis_grid_lines axis={@y_axis} ticks={5} stroke="#D3D3D3" />
+
+
+ <.polyline points={points(@dataset[:x], @dataset[:y])} stroke="#EC7E16" stroke-width={2} />
+
+
+ <.circle cx={@dataset[:x]} cy={@dataset[:y]} r={3} fill="#EC7E16" />
+
+```
\ No newline at end of file
diff --git a/examples/animated_demo_live.exs b/examples/animated_demo_live.exs
new file mode 100644
index 0000000..d073039
--- /dev/null
+++ b/examples/animated_demo_live.exs
@@ -0,0 +1,229 @@
+Mix.install([
+ {:phoenix_playground, "~> 0.1.7"},
+ {:plox, path: "."}
+])
+
+defmodule AnimatedDemoLive do
+ @moduledoc """
+ Example animated graph rendered within a Phoenix Playground application.
+
+ $ iex animated_demo_live.exs
+ """
+ use Phoenix.LiveView
+
+ import Plox
+
+ @interval 1000
+
+ @impl Phoenix.LiveView
+ def mount(_params, _session, socket) do
+ dimensions = Plox.Dimensions.new(1_000, 250)
+
+ if connected?(socket) do
+ Process.send_after(self(), :tick, @interval)
+ Process.send_after(self(), :add_point, :rand.uniform(10) * 1_000)
+ end
+
+ now = DateTime.truncate(DateTime.utc_now(), :second)
+ soon = DateTime.add(now, 5, :second)
+ start = DateTime.add(soon, -60, :second)
+ nearest_5_second = get_nearest_5_second(start)
+
+ x_axis =
+ Plox.XAxis.new(
+ Plox.DateTimeScale.new(
+ start,
+ soon
+ ),
+ dimensions
+ )
+
+ y_axis = Plox.YAxis.new(Plox.NumberScale.new(0, 100), dimensions)
+
+ radius_axis = Plox.LinearAxis.new(Plox.NumberScale.new(1, 100), min: 5, max: 15)
+
+ color_axis =
+ Plox.ColorAxis.new(Plox.FixedColorsScale.new(%{cold: "#1E88E5AA", normal: "#43A047AA", warm: "#FFC107AA"}))
+
+ {data1, dataset1} = init_line_data(now, x_axis, y_axis)
+ {data2, dataset2} = init_line_data(now, x_axis, y_axis)
+ {data3, dataset3} = init_line_data(now, x_axis, y_axis)
+
+ points = []
+
+ points_dataset =
+ Plox.Dataset.new(points,
+ x: {x_axis, & &1.x},
+ y: {y_axis, & &1.y},
+ r: {radius_axis, & &1.size},
+ color: {color_axis, & &1.temperature}
+ )
+
+ {:ok,
+ assign(socket,
+ now: now,
+ data1: data1,
+ dataset1: dataset1,
+ data2: data2,
+ dataset2: dataset2,
+ data3: data3,
+ dataset3: dataset3,
+ points: points,
+ points_dataset: points_dataset,
+ x_axis: x_axis,
+ y_axis: y_axis,
+ radius_axis: radius_axis,
+ color_axis: color_axis,
+ dimensions: dimensions,
+ nearest_5_second: nearest_5_second
+ )}
+ end
+
+ @impl Phoenix.LiveView
+ def render(assigns) do
+ ~H"""
+ <.graph dimensions={@dimensions}>
+ <.y_axis_labels :let={value} axis={@y_axis} ticks={5}>
+ {value}
+
+
+ <.y_axis_grid_lines axis={@y_axis} ticks={5} stroke="#D3D3D3" />
+
+ <.x_axis_labels :let={datetime} axis={@x_axis} step={5} start={@nearest_5_second}>
+ {Calendar.strftime(datetime, "%-I:%M:%S")}
+
+
+ <.x_axis_grid_lines axis={@x_axis} step={5} start={@nearest_5_second} stroke="#D3D3D3" />
+ <.x_axis_grid_line axis={@x_axis} value={@x_axis.scale.first} stroke="#D3D3D3" />
+ <.x_axis_grid_line axis={@x_axis} value={@x_axis.scale.last} stroke="#D3D3D3" />
+
+ <%!-- vertical marker for "now" with a label --%>
+ <.x_axis_label axis={@x_axis} value={@now} position={:top} stroke="red">
+ Now ({Calendar.strftime(@now, "%-I:%M:%S")})
+
+
+ <.x_axis_grid_line axis={@x_axis} value={@now} stroke="red" />
+
+ <.polyline points={points(@dataset1[:x], @dataset1[:y])} stroke="orange" stroke-width="2" />
+ <.polyline points={points(@dataset2[:x], @dataset2[:y])} stroke="blue" stroke-width="2" />
+ <.polyline points={points(@dataset3[:x], @dataset3[:y])} stroke="green" stroke-width="2" />
+ <.circle
+ cx={@points_dataset[:x]}
+ cy={@points_dataset[:y]}
+ r={@points_dataset[:r]}
+ fill={@points_dataset[:color]}
+ />
+
+ """
+ end
+
+ @impl Phoenix.LiveView
+ def handle_info(:tick, socket) do
+ Process.send_after(self(), :tick, @interval)
+
+ now = DateTime.truncate(DateTime.utc_now(), :second)
+ soon = DateTime.add(now, 5, :second)
+ start = DateTime.add(soon, -60, :second)
+ nearest_5_second = get_nearest_5_second(start)
+
+ x_axis =
+ Plox.XAxis.new(
+ Plox.DateTimeScale.new(
+ start,
+ soon
+ ),
+ socket.assigns.dimensions
+ )
+
+ {data1, dataset1} = update_line_data(socket.assigns.data1, now, x_axis, socket.assigns.y_axis)
+ {data2, dataset2} = update_line_data(socket.assigns.data2, now, x_axis, socket.assigns.y_axis)
+ {data3, dataset3} = update_line_data(socket.assigns.data3, now, x_axis, socket.assigns.y_axis)
+
+ points =
+ Enum.take_while(socket.assigns.points, fn %{x: time} ->
+ DateTime.compare(time, x_axis.scale.first) != :lt
+ end)
+
+ points_dataset =
+ Plox.Dataset.new(points,
+ x: {socket.assigns.x_axis, & &1.x},
+ y: {socket.assigns.y_axis, & &1.y},
+ r: {socket.assigns.radius_axis, & &1.size},
+ color: {socket.assigns.color_axis, & &1.temperature}
+ )
+
+ {:noreply,
+ assign(socket,
+ now: now,
+ data1: data1,
+ dataset1: dataset1,
+ data2: data2,
+ dataset2: dataset2,
+ data3: data3,
+ dataset3: dataset3,
+ points: points,
+ points_dataset: points_dataset,
+ x_axis: x_axis,
+ nearest_5_second: nearest_5_second
+ )}
+ end
+
+ def handle_info(:add_point, socket) do
+ Process.send_after(self(), :add_point, :rand.uniform(10) * 1_000)
+
+ new_point = %{
+ x: socket.assigns.now,
+ y: :rand.uniform(100),
+ size: :rand.uniform(100),
+ temperature: Enum.random(~w(cold normal warm)a)
+ }
+
+ points = [new_point | socket.assigns.points]
+
+ {:noreply, assign(socket, points: points)}
+ end
+
+ defp get_nearest_5_second(datetime) do
+ seconds = datetime.second
+
+ diff = ceil(seconds / 5) * 5 - seconds
+
+ DateTime.add(datetime, diff)
+ end
+
+ defp init_line_data(now, x_axis, y_axis) do
+ data = [%{x: now, y: :rand.uniform(100)}]
+
+ dataset = Plox.Dataset.new(data, x: {x_axis, & &1.x}, y: {y_axis, & &1.y})
+
+ {data, dataset}
+ end
+
+ defp update_line_data(data, now, x_axis, y_axis) do
+ [previous | _] = data
+
+ diff =
+ case previous.y do
+ 100 -> :rand.uniform(10) - 10
+ 0 -> :rand.uniform(10)
+ _ -> :rand.uniform(20) - 10
+ end
+
+ new = min(max(previous.y + diff, 0), 100)
+
+ data =
+ Enum.take_while([%{x: now, y: new} | data], fn %{x: time} ->
+ DateTime.compare(time, x_axis.scale.first) != :lt
+ end)
+
+ dataset =
+ Plox.Dataset.new(data,
+ x: {x_axis, & &1.x},
+ y: {y_axis, & &1.y}
+ )
+
+ {data, dataset}
+ end
+end
+
+PhoenixPlayground.start(live: AnimatedDemoLive)
diff --git a/examples/demo_live.exs b/examples/demo_live.exs
new file mode 100644
index 0000000..b33448c
--- /dev/null
+++ b/examples/demo_live.exs
@@ -0,0 +1,119 @@
+Mix.install([
+ {:phoenix_playground, "~> 0.1.7"},
+ {:plox, path: "."}
+])
+
+defmodule DemoLive do
+ @moduledoc """
+ Example graph rendered within a Phoenix Playground application.
+
+ $ iex demo_live.exs
+ """
+ use Phoenix.LiveView
+
+ import Plox
+
+ @impl Phoenix.LiveView
+ def mount(_params, _session, socket) do
+ {:ok, mount_simple_line_graph(socket)}
+ end
+
+ @impl Phoenix.LiveView
+ def render(assigns) do
+ ~H"""
+ <.simple_line_graph {@graph} />
+ """
+ end
+
+ defp mount_simple_line_graph(socket) do
+ data =
+ [
+ %{date: ~D[2023-08-01], value: 35.0, intensity: 10, temperature: :cold},
+ %{date: ~D[2023-08-02], value: 60.0, intensity: 20, temperature: :cold},
+ %{date: ~D[2023-08-03], value: 65.0, intensity: 25, temperature: :normal},
+ %{date: ~D[2023-08-04], value: 10.0, intensity: 45, temperature: :warm},
+ %{date: ~D[2023-08-05], value: 50.0, intensity: 15, temperature: :warm}
+ ]
+
+ dimensions = Plox.Dimensions.new(670, 250)
+
+ x_axis =
+ Plox.XAxis.new(Plox.DateScale.new(Date.range(~D[2023-08-01], ~D[2023-08-05])), dimensions)
+
+ y_axis = Plox.YAxis.new(Plox.NumberScale.new(0.0, 80.0), dimensions)
+ radius_axis = Plox.LinearAxis.new(Plox.NumberScale.new(10, 45), min: 4, max: 10)
+
+ color_axis =
+ Plox.ColorAxis.new(Plox.FixedColorsScale.new(%{cold: "#1E88E5", normal: "#43A047", warm: "#FFC107"}))
+
+ dataset =
+ Plox.Dataset.new(data,
+ x: {x_axis, & &1.date},
+ y: {y_axis, & &1.value},
+ radius: {radius_axis, & &1.intensity},
+ color: {color_axis, & &1.temperature}
+ )
+
+ assign(socket,
+ graph: %{
+ x_axis: x_axis,
+ y_axis: y_axis,
+ dataset: dataset,
+ dimensions: dimensions
+ }
+ )
+ end
+
+ defp simple_line_graph(assigns) do
+ ~H"""
+