SoCG

Author: Lara Chiara Ost

README.md

@@ -1,6 +1,6 @@
 # Banana Trees
 
-This implements the banana tree data structure introduced by Cultrera di Montesano, Edelsbrunner, Henzinger and Ost at SODA 2024.
+This implements the banana tree data structure introduced in Cultrera di Montesano et al. "Dynamically Maintaining the Persistent Homology of Time Series" at SODA 2024.
 
 # Build Instructions
 
@@ -39,9 +39,8 @@ The paramters $m$ and $D$ are user specified (`-m` and `-d`, respectively).
 The size of the left interval relative to the total time series is given by the option `-c`.
 
 Both `ex_local_maintenance` and `ex_topological_maintenance` can run worst-case scenarios by selecting the appropriate subcommand.
-The `num_items` option works slightly differently in these executables than described in the help string:
-the format is `min number_of_divisions max`; `number_of_divisions` values are selected from the interval `[min, max]`,
-such that they are spaced evenly on a logarithmic scale.
+They use the correct generator by default.
+To mix a random walk into the input, use generators `local-wc` and `cut-wc`, respectively, with the appropriate options; see `docs/generators.md` for details.
 
 `ex_time_series construct` reads a time series from standard input in the form of a sequence of function values and constructs the banana tree.
 
@@ -53,5 +52,27 @@ This output can be converted into a csv-file using the python script `tools/stru
 # License
 
 This repository, except files in `ext/`, is published under the MIT license.
-
 See the files in `ext/` for the respective licenses.
+
+If you publish results using our algorithms, please acknowledge our work by citing the corresponding papers:
+```
+@inproceedings{cultrera24,
+  author = {Sebastiano Cultrera di Montesano and Herbert Edelsbrunner and Monika Henzinger and Lara Ost},
+  title = {Dynamically Maintaining the Persistent Homology of Time Series},
+  booktitle = {Proceedings of the 2024 Annual ACM-SIAM Symposium on Discrete Algorithms (SODA)},
+  year = {2024},
+  chapter = {},
+  pages = {243-295},
+  doi = {10.1137/1.9781611977912.11},
+}
+@misc{ost25,
+  title={Banana Trees for the Persistence in Time Series Experimentally}, 
+  author={Lara Ost and Sebastiano Cultrera di Montesano and Herbert Edelsbrunner},
+  year={2025},
+  eprint={2405.17920},
+  archivePrefix={arXiv},
+  primaryClass={cs.DS},
+  note={To appear},
+  url={https://arxiv.org/abs/2405.17920}
+}
+```

docs/generators.md

@@ -1,26 +1,49 @@
 # Synthetic Data Generators
 
+The general format of the string passed to `--gen-args` is `<gen>:<list-of-params>`,
+where `<gen>` is the name of the generator and `<list-of-params>` is a semicolon-separated list of values.
+Parameters have to be provided in the given order.
+Some may be optional, but if one optional parameter is omitted, all subsequent ones must be omitted, too.
+Numerical parameters are converted to a number by `std::stod(...)`.
+
 ## Gaussian Random Walks
 
-Generate a random walk where $f(x_i) = f(x_{i-1}) + \cal{N}(\mu, \sigma)$.
+Generate a random walk where $R(x_i;\mu,\sigma) = R(x_{i-1};\mu,\sigma) + \cal{N}(\mu, \sigma)$,
+with $R(0;\mu,\sigma) = 0$.
+The term $\cal{N}(\mu,\sigma)$ denotes a Gaussian random variable with mean $\mu$ and standard deviation $\sigma$.
 
 Pass to `--gen_args` as
 ```
     grw:<mean>;<sd>
 ```
 `<mean>` is the mean of the normal distribution, `<sd>` its standard deviation.
-All parameters (`<...>`) are converted to a number by `std::stod(...)`.
-Parameter `<sd>` is optional.
+Parameter `<sd>` is optional with default `1`.
+
+## Linear Case for Local Maintenance and Topological Maintenance
+
+Pass to `--gen_args` as
+```
+    <gen>:<noise>;<mean>;<sd>
+```
 
-## Linear Case for Local Maintenance
+Here, `<gen>` is either `local-wc` or `cut-wc`.
+`<noise>` is the amount of noise mixed into the signal: 0 for no noise, 1 for only noise.
+The noise is a Gaussian random walk with mean `<mean>` and standard deviation `<sd>`.
+All parameters (except `<gen>`) are optional.
 
-Pass to `--gen_args` as `local-wc`.
+Default values are:
+- `<noise>`: `0` 
+- `<mean>`: `0`
+- `<sd>`: `1`
+
+The executable `generate_data` also accepts `glue-wc` for `<gen>`; this produces the same series as `cut-wc`.
 
 ## Quasi-Periodic Functions
 
 ### Method 1 -- Sine Wave + Random Walk
 
 $f(x) = a \cdot sin(\omega x) + R(x; \mu, \sigma)$, where $R(x; \mu, \sigma)$ is a Gaussian random walk.
+Items are generated for $x=0,1,\dots$.
 
 Parameters:
 - $a$: amplitude of the sine wave
@@ -32,13 +55,19 @@ Pass to `--gen_args` as
 ```
     sqp:<period>;<amplitude>;<mean>;<sd>
 ```
-All parameters (`<...>`) are converted to a number by `std::stod(...)`.
-All are optional, but must be specified in the given order,
-i.e., if `<mean>` is given, then `<period>` and `<amplitude>` cannot be omitted. 
+All parameters are optional, but must be specified in the given order,
+e.g., if `<mean>` is given, then `<period>` and `<amplitude>` cannot be omitted. 
+
+Default values are:
+- `<period>`: `100` 
+- `<amplitude>`: `1`
+- `<mean>`: `0`
+- `<sd>`: `1`
 
 ### Method 2 -- Sine Wave Modulating a Random Walk
 
 $f(x) = R(x; a \cdot sin(wx), \sigma)$, where $R(x; \mu, \sigma)$ is a Gaussian random walk.
+Items are generated for $x=0,1,\dots$.
 
 Parameters:
 - $a$: amplitude of the sine wave
@@ -49,6 +78,15 @@ Pass to `--gen_args` as
 ```
     mqp:<number of periods>;<amplitude>;<sd>
 ```
-All parameters (`<...>`) are converted to a number by `std::stod(...)`.
 All are optional, but must be specified in the given order,
-i.e., if `<sd>` is given, then `<number of periods>` and `<amplitude>` cannot be omitted. 
+e.g., if `<sd>` is given, then `<number of periods>` and `<amplitude>` cannot be omitted. 
+
+Default values are:
+- `<number of periods>`: `5.5`
+- `<amplitude>`: `1`
+- `<sd>`: `1`
+
+### A Note
+Both of these methods do essentially the same thing.
+For "historical" reasons `sqp` takes the period of the sine wave as input, while in `mqp` you select the number of periods over the whole input.
+Furthermore, `sqp` allows to bias the random walk, which `mqp` does not.

src/app/experiments/ex_local_maintenance.cpp

@@ -246,7 +246,7 @@ int main(int argc, char** argv) {
 
     CLI::App app("Construction Experiments");
 
-    add_num_items_option(app, num_item_limits) -> required();
+    add_logspace_num_items_option(app, num_item_limits) -> required();
     add_seed_option(app, seed);
     add_num_reps_option(app, num_reps);
     add_gudhi_flag(app, run_gudhi);
@@ -272,7 +272,7 @@ int main(int argc, char** argv) {
     CLI11_PARSE(app, argc, argv);
 
     if (num_item_limits[0] < 2 || num_item_limits[1] == 0 || num_item_limits[2] < num_item_limits[0]) {
-        std::cerr << "num_items needs to be of the form min step max, with min >= 2, step >= 1 and max >= min.\n";
+        std::cerr << "num_items needs to be of the form min number_of_steps max, with min >= 2, number_of_steps >= 1 and max >= min.\n";
         std::cerr << app.help() << std::endl;
         return 1;
     }

src/app/experiments/ex_topological_maintenance.cpp

@@ -252,7 +252,7 @@ int main(int argc, char** argv) {
 
     add_seed_option(app, seed);
     add_num_reps_option(app, num_reps);
-    add_num_items_option(app, num_item_limits) -> required();
+    add_logspace_num_items_option(app, num_item_limits) -> required();
     add_gudhi_flag(app, run_gudhi);
     add_persistence1d_flag(app, run_persistence1d);
     auto* gen_opt = add_gen_args_option(app, generator_args);
@@ -275,7 +275,7 @@ int main(int argc, char** argv) {
     const auto step_num_items = num_item_limits[1];
     const auto max_num_items = num_item_limits[2];
     if (min_num_items < 2 || step_num_items == 0 || max_num_items < min_num_items) {
-        std::cerr << "num_items needs to be of the form min step max, with min >= 2, step >= 1 and max >= min.\n";
+        std::cerr << "num_items needs to be of the form min number_of_steps max, with min >= 2, number_of_steps >= 1 and max >= min.\n";
         std::cerr << app.help() << std::endl;
         return 1;
     }
@@ -334,18 +334,18 @@ int main(int argc, char** argv) {
         std::cout << "# Linear-time case for cutting.\n";
         for (auto num_items: logspace_items) {
             // Need an odd number of items
-            if (num_items % 2 == 0) {
+            if (num_items % 2 != 0) {
                 num_items++;
             }
-            if (num_items % 4 != 1) {
+            if (num_items % 4 != 0) {
                 num_items += 2;
             }
-            massert(num_items % 4 == 1, "Expected number of items to be a number divisible by 4 plus 1.");
+            massert(num_items % 4 == 0, "Expected number of items to be divisible by 4.");
             cut_experiment<topological_worst_case_generator<false, decltype(rng)>>(num_items, 0.5, {rng, gen_param_string}, num_reps, run_gudhi, run_persistence1d);
             std::cout << "--\n";
         }
     } else if (app.got_subcommand(wc_glue_app)) {
-        if (*gen_opt && gen_name != topological_worst_case_generator<true>::get_name()) {
+        if (*gen_opt && gen_name != topological_worst_case_generator<false>::get_name()) {
             std::cerr << "wc-glue app requires cut-wc generator.\n";
             return 1;
         }
@@ -356,14 +356,14 @@ int main(int argc, char** argv) {
         std::cout << "# Linear-time case for gluing.\n";
         for (auto num_items: logspace_items) {
             // Need an odd number of items
-            if (num_items % 2 == 0) {
+            if (num_items % 2 != 0) {
                 num_items++;
             }
-            if (num_items % 4 != 1) {
+            if (num_items % 4 != 0) {
                 num_items += 2;
             }
-            massert(num_items % 4 == 1, "Expected number of items to be a number divisible by 4 plus 1.");
-            glue_experiment<topological_worst_case_generator<true, decltype(rng)>>(num_items, 0.5, {rng, gen_param_string}, num_reps, run_gudhi, run_persistence1d);
+            massert(num_items % 4 == 0, "Expected number of items to be divisible by 4.");
+            glue_experiment<topological_worst_case_generator<false, decltype(rng)>>(num_items, 0.5, {rng, gen_param_string}, num_reps, run_gudhi, run_persistence1d);
             std::cout << "--\n";
         }
     }

src/app/experiments/generate_data.cpp

@@ -70,6 +70,10 @@ int main(int argc, char** argv) {
             std::cerr << "Need at least 4 items for topological maintenance worst-case\n";
             return 1;
         }
+        if (num_items % 4 != 0) {
+            std::cerr << "Number of items needs to be a multiple of 4 for topological maintenance worst-case.\n";
+            return 1;
+        }
         random_number_generator rng{seed};
         topological_worst_case_generator<false> gen{{rng, gen_param_string}};
         gen(values, num_items);
@@ -78,12 +82,8 @@ int main(int argc, char** argv) {
             std::cerr << "Need at least 4 items for topological maintenance worst-case\n";
             return 1;
         }
-        if (num_items % 2 == 0) {
-            std::cerr << "Need an odd number of items for topological maintenance worst-case\n";
-            return 1;
-        }
-        if ((num_items/2) % 2 != 0) {
-            std::cerr << "Number of items needs to be a multiple of 4 plus 1 for topological maintenance worst-case.\n";
+        if (num_items % 4 != 0) {
+            std::cerr << "Number of items needs to be a multiple of 4 for topological maintenance worst-case.\n";
             return 1;
         }
         random_number_generator rng{seed};

src/app/experiments/utility/cli_options.h

@@ -33,6 +33,12 @@ inline CLI::Option* add_num_items_option(CLI::App& app, std::array<size_t, 3>& n
                           "Number of items in the form 'min step max'");
 }
 
+inline CLI::Option* add_logspace_num_items_option(CLI::App& app, std::array<size_t, 3>& num_item_limits) {
+    return app.add_option("num_items",
+                          num_item_limits,
+                          "Number of items in the form 'min number_of_steps max'; uniformly spaced on a logarithmic scale");
+}
+
 inline CLI::Option* add_gen_args_option(CLI::App& app, std::string& generator_args) {
     return app.add_option("--gen-args",
                           generator_args,

src/app/experiments/utility/data_generation.h

@@ -450,12 +450,11 @@ struct topological_worst_case_generator {
             decrease = false;
             long value = 1;
             auto size_offset = two_stage ? values.size() : 0;
-            while (values.size() < target_size  - 1 + size_offset) {
-                values.push_back(static_cast<function_value_type>(value) + 0.1);
-                values.push_back(static_cast<function_value_type>(-value) + 0.1);
+            while (values.size() < target_size + size_offset) {
+                values.push_back(static_cast<function_value_type>(value) - 0.1);
+                values.push_back(static_cast<function_value_type>(-value) - 0.1);
                 value++;
             }
-            values.push_back(static_cast<function_value_type>(value) + 0.1);
         }
         if (noise_amount != 0) {
             auto scale = stage_size/2;