Docs & examples

Author: taehyounpark

README.md

@@ -21,14 +21,13 @@
 
 ## Hello World
 ```cpp
-#include "queryosity/json.h"
-#include "queryosity/hist.h"
-
-#include "queryosity.h"
-
 #include <fstream>
-#include <vector>
 #include <sstream>
+#include <vector>
+
+#include "queryosity.h"
+#include "queryosity/hist.h"
+#include "queryosity/json.h"
 
 using dataflow = qty::dataflow;
 namespace multithread = qty::multithread;
@@ -41,31 +40,30 @@ using h1d = qty::hist::hist<double>;
 using linax = qty::hist::axis::regular;
 
 int main() {
-
-	dataflow df( multithread::enable(10) );
-
-	std::ifstream data("data.json");
-	auto [x, w] = df.read( 
-		dataset::input<json>(data), 
-		dataset::column<std::vector<double>>("x"),
-		dataset::column<double>("w") 
-		);
-
-	auto zero = df.define( column::constant(0) );
-	auto x0 = x[zero];
-
-	auto sel = df.weight(w).filter(
-		column::expression([](std::vector<double> const& v){return v.size()}), x
-		);
-
-	auto h_x0_w = df.get( 
-		query::output<h1d>( linax(100,0.0,1.0) ) 
-		).fill(x0).book(sel).result();
-
-	std::ostringstream os;
-	os << *h_x0_w;
-	std::cout << os.str() << std::endl;
-
+  dataflow df(multithread::enable(10));
+
+  std::ifstream data("data.json");
+  auto [x, v, w] = df.read(
+      dataset::input<json>(data), dataset::column<double>("x"),
+      dataset::column<std::vector<double>>("v"), dataset::column<double>("w"));
+
+  auto zero = df.define(column::constant(0));
+  auto v0 = v[zero];
+
+  auto sel =
+      df.weight(w)
+          .filter(column::expression(
+              [](std::vector<double> const &v) { return v.size(); }))(v)
+          .filter(column::expression([](double x) { return x > 100.0; }))(x);
+
+  auto h_x0_w = df.get(query::output<h1d>(linax(20, 0.0, 200.0)))
+                    .fill(v0)
+                    .at(sel)
+                    .result();
+
+  std::ostringstream os;
+  os << *h_x0_w;
+  std::cout << os.str() << std::endl;
 }
 ```
 

docs/pages/conceptual.md

@@ -72,7 +72,7 @@ For multithreaded runs, the user must also define how outputs from individual th
 
 - It must be associated with a selection whose cut determines which entries to count.
     - (Optional) The result is populated with the weight taken into account.
-- How an entry is to be counted to populate the query depends on the user definition, i.e. it is an arbitrary action.
+- How an entry populates the query depends on its implementation.
     - (Optional) The result is populated based on values of inputs columns.
 
 Two common workflows exist in associating queries with selections:
@@ -87,7 +87,7 @@ A sensitivity analysis means to study how changes in the system's inputs affect
 In the context of dataset queries, a **systematic variation** constitutes a __change in a column value that affects the outcome of selections and queries__.
 
 Encapsulating the nominal and variations of a column creates a `varied` node in which each variation is mapped by the name of its associated systematic variation.
-A varied node in a dataflow can be treated functionally identical to a non-varied one, with all nominal+variations being propagated through all relevant task graphs implicitly:
+A varied node can be treated functionally identical to a non-varied one, with all nominal+variations being propagated through the relevant task graphs implicitly:
 
 - Any column definitions and selections evaluated out of varied input columns will be varied.
 - Any queries performed filled with varied input columns and/or at varied selections will be varied.
@@ -97,7 +97,7 @@ The propagation proceeds in the following fashion:
 - **Lockstep.** If two actions each have a variation of the same name, they are in effect together.
 - **Transparent.** If only one action has a given variation, then the nominal is in effect for the other.
 
-All variations are processed at once in a single dataset traversal, i.e. they do not incur additional runtime overhead other than what is already required to perform the actions themselves.
+All variations are processed at once in a single dataset traversal; in other words, they do not incur any additional runtime overhead other than what is needed to perform the actions themselves.
 
 @image html variation.png "Propagation of systematic variations."
 

docs/pages/design.md

@@ -3,31 +3,31 @@
 
 `queryosity` has been purposefully designed for data analysis workflows in high-energy physics experiments prioritizing the following principles.
 
-@section design-clear-interface Clear interface above all else.
+@section design-clear-interface Clarity and consistency above all else.
 
-- Provide a faithful, one-to-one correspondence between the description of the analysis logic by the interface and its underlying graph(s) of tasks being performed.
-- The analysis code written by Alice must be readable and understandable to Bob, and vice versa.
+- The interface should be a faithful representation of the analysis task graph.
+- The analysis code written by Alice should be readable and understandable to Bob, and vice versa.
 
-@section design-arbitrary-data Arbirary data types.
+@section design-arbitrary-data Arbitrary data types.
 
-- Many "columns" are not POD: they are of non-trivial data types containing nested properties, links to data of other types, etc. The interface for handling these columns should be front-and-center.
+- Many "columns" are not trivial: they can contain nested properties, links to other data, etc.
 - If a dataset has rows, or "events", the library should be able to run over it.
 - Output results of any data structure as desired.
 
 @section design-cutflow Unified cutflow for cuts and weights.
 
-- There is exactly one difference between a decision to (1) accept an event (cut), or (2) assign a statistical significance to it (weight): one is a yes-or-no, and the other is a number.
-- Selections are defined individually, then connected through a "cutflow" that is as deep (compounded selections) or wide (branched selections) as needed.
-- Whenever a particular selection is in effect for an event, all queries are consistently populated with the same cut and weight.
+- There is only one difference between (1) accepting an event (cut), or (2) assigning a statistical significance to it (weight): one is a yes-or-no, and the other is a number.
+- Selections can be arbitrarily deep (compounded selections) or wide (branched selections).
+- Whenever a particular selection is in effect for an event, all queries are populated with the same entries and weights.
 
 @section design-performance Optimal(maximal) efficiency(usage) of computational resources.
 
 - Never perform an action for an event unless needed.
-- The dataset is partitioned, and the traversal over each sub-range is parallelized.
+- Partition the dataset and traverse over each sub-range in parallel.
 
 @section design-systematic-variations Built-in, generalized handling of systematic variations.
 
 - An experiment can be subject to @f$ O(100) @f$ sources of "systematic uncertainties".
-- Applying systematic variations that are (1) specified once and automatically propagated, and (2) processed all at once in one dataset traversal, are crucial in minimizing "time-to-insight".
+- Applying systematic variations that are (1) specified once and automatically propagated, and (2) processed all at once in one dataset traversal, is crucial for minimizing "time-to-insight".
 
 @see @ref conceptual