% Copyright 2025-2026 Lukas C. Bossert. LPPL 1.3c or later; see LICENSE.
\documentclass[11pt,a4paper]{article}
\usepackage[margin=25mm]{geometry}
\usepackage{fontspec}
\setmainfont{TeX Gyre Pagella}
\setsansfont{TeX Gyre Heros}
\setmonofont{TeX Gyre Cursor}[Scale=MatchLowercase]
\usepackage{ddv}
\usepackage{booktabs,array,fancyvrb,enumitem,listings}
\usepackage[colorlinks,linkcolor=blue!50!black,urlcolor=blue!50!black]{hyperref}
\hypersetup{pdftitle={Data Driven Visualization: User Manual},pdfauthor={Lukas C. Bossert}}
\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt}
\setlist{nosep}
\setlist[description]{style=nextline,leftmargin=0pt,labelindent=0pt,labelwidth=0pt,labelsep=0pt}
\DefineVerbatimEnvironment{Code}{Verbatim}{fontsize=\small,frame=single,framesep=6pt}
\newcommand{\key}[1]{\texttt{#1}}
\lstdefinestyle{ddv-example}{
  language=[LaTeX]TeX,
  basicstyle=\ttfamily\fontsize{8.5}{10}\selectfont,
  keywordstyle=\color{blue!55!black},
  commentstyle=\color{black!50},
  columns=fullflexible,keepspaces=true,
  showstringspaces=false,breaklines=true,
  frame=single,rulecolor=\color{black!20},
  framesep=5pt,aboveskip=0pt,belowskip=0pt
}
% The displayed listing and rendered result use the same source file.
\newcommand{\WorkedExample}[3]{%
  \subsection{#1}
  #2\par\smallskip
  \noindent
  \begin{minipage}[t]{.52\linewidth}
    {\sffamily\small\bfseries LaTeX source\par}\smallskip
    \lstinputlisting[style=ddv-example,firstline=2]{#3}%
  \end{minipage}\hfill
  \begin{minipage}[t]{.44\linewidth}
    {\sffamily\small\bfseries Result\par}\smallskip
    \centering\resizebox{\linewidth}{!}{\input{#3}}%
  \end{minipage}\par
}

\begin{document}
\raggedright
{\sffamily\huge Data Driven Visualization\par}
{\Large CSV-driven concentric arc charts\par}
Version 1.0.0 \quad 2026-10-01\par
Lukas C. Bossert\quad\href{mailto:bossert@itc.rwth-aachen.de}{\nolinkurl{bossert@itc.rwth-aachen.de}}

\section{What the package does}
\key{ddv} wraps \key{wheelchart} and \key{datatool}. Each CSV row becomes a
colored arc on its own concentric ring. Optional stages label the circle,
and an optional title follows an outer arc. Category filters and sorting
select and order the rings without editing the data file.

\section{Quick start}
Put \key{ddv.sty} and \key{ddv-example.csv} beside your document and compile
with LuaLaTeX. This example scales the chart to the text width.
\begin{Code}
\documentclass{article}
\usepackage[dataset={ddv-example.csv}]{ddv}
\begin{document}
\resizebox{\linewidth}{!}{%
  \DDV{stages={{Plan,Collect,Analyse,Share}},
       title={A project overview},
       slices={fontcolor=white}}}
\end{document}
\end{Code}
Set shared options in \key{\string\usepackage[...]\{ddv\}}.
Pass overrides to \key{\string\DDV\{...\}}. Local overrides affect only that
chart. An empty argument uses the package options unchanged.

\section{Requirements and installation}
Use LaTeX 2022-06-01 or newer, with \key{wheelchart}, \key{datatool},
\key{xcolor}, and TikZ including \key{decorations.text}. This release was
tested with LuaLaTeX on TeX Live 2026. Other engines and older dependency
versions have not been verified. No shell escape is needed.

For a user-wide installation, place \key{ddv.sty} under
\key{tex/latex/ddv/} in your user TEXMF tree; refresh the filename database
if required by your distribution. The CTAN catalogue name is
\key{data-driven-visualization}; the LaTeX package name remains \key{ddv}.

\newpage
\section{Example and data format}
\begin{center}
\resizebox{.55\linewidth}{!}{\DDV{
 dataset={ddv-example.csv},innercirclesize=2,
 stages={{Plan,Collect,Analyse,Share},bgcolor={0,84,159},fontsize=24},
 title={A project overview,fontsize=28},slices={fontcolor=white,fontsize=24}}}
\end{center}
The included data are fictional. The CSV header is mandatory:
\begin{Code}
category,name,description,startangle,totalangle,color
project,Alpha,Planning,90,90,blue
service,Beta,,0,180,teal
project,Gamma,Analysis,-90,120,orange
service,Delta,Reuse,180,60,purple
\end{Code}
\begin{description}
\item[category] A case-sensitive label used by the filter.
\item[name] Text on the arc; protect LaTeX special characters as usual.
\item[description] Optional text in parentheses after the name. Keep the
column even if every value is empty.
\item[startangle] A signed decimal angle in degrees: 90 is the top,
0 is the right, and $-90$ is the bottom.
\item[totalangle] A clockwise span greater than 0 and at most 360.
From the top to the right is a span of 90 degrees.
\item[color] An xcolor name or expression, such as \key{blue!60!black}.
A quoted RGB triple, such as \key{"0,84,159"}, is also accepted.
\end{description}
Quote CSV fields containing commas with double quotes. CSV cells are
LaTeX input: escape \key{\&}, \key{\%}, \key{\_}, and \key{\#} when they
are literal text. Slash characters are delimiters in wheelchart data;
protect a literal slash in a label with braces, for example \key{A\{/\}B}.
Use decimal notation for angles, not formulas or degree symbols.

\newpage
\section{Selecting data and arranging rings}
\begin{description}
\item[\key{dataset}] Filename shorthand: \key{dataset=\{ddv-example.csv\}}.
The explicit form is \key{dataset=\{name=\{ddv-example.csv\}\}}.
No filename is set by default; an empty filename omits the data rings.
\item[\key{dataset/filter}] A category or a comma-separated list, for example
\key{dataset=\{filter=\{\{project,service\}\}\}}.
The default \key{none} selects all rows; it is reserved for that purpose.
An empty list selects no rows. Matching is case-sensitive.
\item[\key{dataset/sorting}] One or more comma-separated column names,
for example \key{dataset=\{sorting=\{category,name\}\}}.
Sorting is ascending: numeric columns are compared numerically, and text
columns case-insensitively, using datatool.
The default empty value preserves CSV order. Sorting one chart does not
change subsequent charts or databases in the calling document.
\item[\key{innercirclesize}] Initial radius offset, an integer from 0 to 9999;
default 4. It is not a diameter. Data ring $i$ has inner radius
$\texttt{innercirclesize}+i+1$ and outer radius one unit larger,
before wheelchart gap adjustments. TikZ's normal coordinate unit is used.
\end{description}

\begin{Code}
\DDV{
  dataset={ddv-example.csv,
           filter={{project,service}},
           sorting={category,name}},
  innercirclesize=2,
  stages={{Plan,Collect,Analyse,Share},inside=true},
  title={Selected activities},
  slices={description=true,bgcolorseries={{blue,red}}}
}
\end{Code}

\section{Text shared by title, stages, and slices}
Each of \key{title}, \key{stages}, and \key{slices} accepts these subkeys:
\begin{description}
\item[\key{font}] Unexpanded LaTeX font commands; default \key{\string\bfseries}.
Use, for example, \key{font=\{\string\sffamily\}}. Load \key{fontspec} yourself
when selecting system fonts. The package imposes no font family.
\item[\key{fontsize}] Integer point size from 1 to 9999; default 15.
\item[\key{fontcolor}] Named color, xcolor mixture, or a braced RGB triple
with integer components from 0 to 255. Defaults: \key{black!50} for title
and slices; \key{white} for stages.
\item[\key{options}] Additional wheelchart keys, applied after the defaults.
See the wheelchart manual for their syntax and interaction.
\end{description}

\newpage
\section{Titles and stages}
\key{title=\{My title\}} and \key{title=\{name=\{My title\}\}} are equivalent.
Protect commas within a title, for example
\key{title=\{name=\{Research, together\}\}}. The default title is empty.

\key{stages=\{\{Plan,Collect,Analyse,Share\}\}} sets equal-sized stage sectors.
The explicit form is \key{stages=\{name=\{Plan,Collect,Analyse,Share\}\}}.
The default list is empty, so no stage ring is drawn.
\begin{description}
\item[\key{stages/bgcolor}] Color of the stage sectors; default \key{blue}.
Accepts the same color syntax as \key{fontcolor}.
\item[\key{stages/inside}] Boolean; default \key{false}. If true, stages
appear inside the data rings, otherwise outside them. Stages can also be
drawn without a dataset.
\end{description}

\section{Slice appearance}
\begin{description}
\item[\key{slices/description}] Boolean; default \key{false}. Append nonempty
descriptions in parentheses. Empty cells do not produce empty parentheses.
\item[\key{slices/bgcolor}] Use one color for every data ring, overriding
the CSV colors. Accepts a named color, mixture, or RGB triple.
\item[\key{slices/bgcolorseries}] Exactly two colors, for example
\key{bgcolorseries=\{\{blue,red\}\}}. Colors run from the first selected row
to the last, after filtering and sorting. Both endpoints are included.
A one-row chart uses the first color. Without an explicit value the
endpoints are blue and red. For RGB endpoints use
\key{bgcolorseries=\{\{0,84,159\},\{227,0,102\}\}}.
\item[\key{slices/sliceColor}] Compatibility boolean. True restores CSV
colors (the default); false selects the uniform background, initially blue.
\item[\key{slices/bgcolorSeries}] Compatibility boolean. True selects the
current gradient (initially blue to red); false selects the uniform color.
Prefer the lowercase \key{bgcolorseries} key for setting a gradient.
\end{description}
The last color-selection key wins. Thus a local \key{bgcolor} overrides
a global gradient, and \key{sliceColor=true} restores per-row colors.

\section{Advanced wheelchart options}
Inside a chart, \key{\string\thestagesRadius} expands to the current radius
offset. Existing option expressions can use this hook:
\begin{Code}
\DDV{dataset={ddv-example.csv},title={Overview,
  options={radius={7+\thestagesRadius}
                  {10+\thestagesRadius}}}}
\end{Code}
For long labels, reduce the font size or enlarge the chart.
Text is not automatically shortened or wrapped.


\newpage
\section{Worked examples}
These examples adapt the generic poster's overview and category panels to
\key{ddv-example.csv}, the four-row fictional dataset shown earlier.
Each listing is the actual source of the result beside it. Load
\key{ddv} in the preamble and place the listed code in your document body.
The manual scales each result to its column width.

\WorkedExample{A poster-style overview}
{Use the poster's blue palette and a light-to-dark gradient. Black labels
remain readable across the gradient; stages sit outside all four data rings.}
{ddv-demo-overview.tex}

\WorkedExample{A project panel with inner stages}
{As in the poster's project panel, filter to one category and move the stages
inside. Enabling descriptions adds Planning and Analysis to the two labels.}
{ddv-demo-projects.tex}

\newpage
\section*{Worked examples: selection and color}
\WorkedExample{A service panel with a uniform color}
{The same panel structure selects services instead. An RGB background
replaces the per-row CSV colors, giving both service arcs the same appearance.}
{ddv-demo-services.tex}

\WorkedExample{Sort first, then apply the gradient}
{Select both categories and sort numerically by angular span. From the inside
out the rows are Delta, Alpha, Gamma, Beta; the gradient follows that order.
Omitting stages leaves only the data rings and title.}
{ddv-demo-sorting.tex}

\newpage
\section*{Worked examples: typography and geometry}
\WorkedExample{Change fonts and enlarge the centre}
{A larger initial radius leaves more central space. Sans-serif text and a
uniform violet palette give the same data a different visual style.}
{ddv-demo-fonts.tex}

\WorkedExample{Customize the stage ring and title position}
{Adapt the poster's wheelchart radius overrides to move the stage ring outward
and increase its gaps.
The title moves below the chart; its radius uses the current offset through
\key{\string\thestagesRadius}.}
{ddv-demo-geometry.tex}


\newpage
\section*{Worked examples: optional layers}
\WorkedExample{Data rings without stages or a title}
{Only the dataset is essential for a data chart. A zero initial offset makes
a compact centre; a pale uniform background keeps the labels easy to read.}
{ddv-demo-minimal.tex}

\WorkedExample{A stage ring without a dataset}
{An empty filename omits all data rings. Six stage labels form a standalone
workflow diagram, useful before any activities have been entered in the CSV.}
{ddv-demo-stages.tex}

\newpage
\section*{Worked examples: color precedence}
\WorkedExample{Override a gradient with one color}
{The background key follows the gradient key, so the uniform teal color wins.
This same ordering rule applies when local settings override package defaults.}
{ddv-demo-precedence.tex}

\WorkedExample{Restore the colors from the CSV}
{A later \key{sliceColor=true} restores the original blue, teal, orange, and
purple row colors, overriding the earlier uniform violet background.}
{ddv-demo-csv-colors.tex}

\newpage
\section*{Worked examples: wheelchart styling}
\WorkedExample{Add outlines and increase radial gaps}
{Pass drawing styles directly to wheelchart. The custom slice style supplies
both the fill and outline; a larger radial gap separates adjacent rings.}
{ddv-demo-outlines.tex}

\WorkedExample{Rotate the stage sectors}
{Move the start of the stage ring to 45 degrees. Only the stage labels and
arrows rotate; the CSV start angles still determine the positions of data arcs.}
{ddv-demo-rotation.tex}

\newpage
\section*{Worked examples: ordering and small datasets}
\WorkedExample{Sort by category and then by name}
{Multiple sorting columns group projects before services, then order names
within each group. The inner-to-outer sequence is Alpha, Gamma, Beta, Delta.}
{ddv-demo-multisort.tex}

\WorkedExample{A gradient with a single selected row}
{The included \key{ddv-single.csv} contains only the Alpha row from the
original example. A one-row gradient uses its first endpoint, here teal,
without interpolating or dividing by zero.}
{ddv-demo-single.tex}

\newpage
\section{Diagnostics and limitations}
A missing dataset, missing required column, unknown key, invalid integer,
invalid RGB triple, or invalid angle produces an error. Compile with
\key{-halt-on-error} when checking data. A filter with no matching rows
produces a warning and skips the entire chart, including title and stages.
Missing columns and invalid selected-row angles also prevent rendering.

Required headers are checked before drawing. Angle validation applies to
selected rows. Color expressions and custom wheelchart keys are ultimately
validated by xcolor and wheelchart. Rows with very long labels or unusual
TeX code still require visual review. CSV data must be trusted LaTeX input.

\section{Building the documentation}
The CTAN archive includes the source files needed to rebuild the manual and
example. Run these commands in the extracted package directory:
\begin{Code}
lualatex ddv-doc.tex
lualatex ddv-doc.tex
lualatex ddv-example.tex
\end{Code}
LuaLaTeX uses its configured font cache. No machine-specific cache path is
stored in the package. The included makefile also provides \key{make doc},
\key{make example}, and \key{make clean}; plain \key{make} builds the manual
and example. These published targets do not require Python.

The release files are listed in \key{MANIFEST.txt}. Keep the fourteen
\key{ddv-demo-*.tex} files beside the manual source: each supplies both a
listing and its rendered chart. Python development scripts are excluded from
the CTAN archive, along with experiments, domain-model material, logos,
caches, build logs, Git metadata, and editor state.

\section{License, maintenance, and acknowledgements}
Copyright 2025--2026 Lukas C. Bossert. This work is distributed under the
LaTeX Project Public License, version 1.3c or later, and has maintenance
status \emph{maintained}. The Current Maintainer is Lukas C. Bossert,
\href{mailto:bossert@itc.rwth-aachen.de}{\nolinkurl{bossert@itc.rwth-aachen.de}}.
The work consists of the files in \key{MANIFEST.txt}; see \key{LICENSE} and
\key{LPPL-1.3c.txt} for the distribution terms.

Thanks to matexmatics for \href{https://ctan.org/pkg/wheelchart}{wheelchart},
Nicola L. C. Talbot for \href{https://ctan.org/pkg/datatool}{datatool}, and the
TeX Stack Exchange community for help with the original design.
The README lists the relevant discussions.

\section{Changes in version 1.0.0}
The first CTAN release includes fourteen worked examples and regression checks, fixes
chart-state isolation and global radius settings, preserves nested option
values, supports RGB triples, makes gradient endpoints and color precedence
consistent, and improves validation and empty-filter handling.
The unused \key{dataset/database} key has been removed.
\end{document}