1246 Export TimeSeries into csv file (#1255)

HenrZu · reneSchm · web-flow · commit add315f39dff · 2025-06-03T14:27:39.000+02:00
- New function to easily write the data from a TimeSeries into a csv file
- This function uses mainly the already existing print_table function

Co-authored-by: reneSchm &lt;49305466+reneSchm@users.noreply.github.com&gt;
diff --git a/cpp/examples/abm_minimal.cpp b/cpp/examples/abm_minimal.cpp
@@ -113,7 +113,7 @@ int main()
     auto test_parameters       = model.parameters.get<mio::abm::TestData>()[test_type];
     auto testing_criteria_work = mio::abm::TestingCriteria();
     auto testing_scheme_work   = mio::abm::TestingScheme(testing_criteria_work, validity_period, start_date, end_date,
-                                                         test_parameters, probability);
+                                                       test_parameters, probability);
     model.get_testing_strategy().add_testing_scheme(mio::abm::LocationType::Work, testing_scheme_work);
 
     // Assign infection state to each person.
@@ -169,7 +169,7 @@ int main()
     // I_Crit = InfectedCritical, R = Recovered, D = Dead
     std::ofstream outfile("abm_minimal.txt");
     std::get<0>(historyTimeSeries.get_log())
-        .print_table({"S", "E", "I_NS", "I_Sy", "I_Sev", "I_Crit", "R", "D"}, 7, 4, outfile);
+        .print_table(outfile, {"S", "E", "I_NS", "I_Sy", "I_Sev", "I_Crit", "R", "D"}, 7, 4);
     std::cout << "Results written to abm_minimal.txt" << std::endl;
 
     return 0;
diff --git a/cpp/examples/ode_seair.cpp b/cpp/examples/ode_seair.cpp
@@ -89,7 +89,7 @@ int main()
     const std::string file_name = "seair-compare.csv";
     std::ofstream file(file_name);
     std::cout << "Writing output to " << file_name << std::endl;
-    seair1.print_table({}, 21, 10, file);
+    seair1.print_table(file, {}, 21, 10);
     file.close();
 
     auto last1 = seair1.get_last_value();
diff --git a/cpp/memilio/utils/time_series.h b/cpp/memilio/utils/time_series.h
@@ -28,6 +28,7 @@
 #include <iterator>
 #include <vector>
 #include <ostream>
+#include <fstream>
 
 namespace mio
 {
@@ -177,7 +178,7 @@ class TimeSeries
     }
 
     /** move ctor and assignment */
-    TimeSeries(TimeSeries&& other)            = default;
+    TimeSeries(TimeSeries&& other) = default;
     TimeSeries& operator=(TimeSeries&& other) = default;
 
     /// Check if the time is strictly monotonic increasing.
@@ -485,7 +486,8 @@ class TimeSeries
     /**
      * @brief Print out the TimeSeries as a table.
      *
-     * All entries in the table are spaced separatedly with at least one space. The first row of the table starts with
+    * All row entries in the table are separated by the given separator, followed by additional spaces filling the width
+    * of the next entry. Each row is terminated by a newline character '\n'. The first row of the table starts with
      * "Time", followed by other column labels. Each row after that contains the time (see get_time) followed by the
      * value (see get_value) for every row (i.e. time point) in the TimeSeries.
      * The width parameter sets the minimum width of each table entry. For the numbers from the TimeSeries, this width
@@ -495,26 +497,34 @@ class TimeSeries
      * (starting at 1, as "Time" is used for column 0). Labels in the column_labels vector that go beyond the TimeSeries column
      * numbers are ignored.
      *
-     * @param column_labels Vector of custom labels for each column.
-     * @param width The number of characters reserved for each number.
-     * @param precision The number of decimals.
-     * @param out Which ostream to use. Prints to terminal by default.
+     * This method can be called in two ways:
+     * 1. With an output stream as the first parameter: print_table(out, column_labels, width, precision, separator, header_prefix)
+     * 2. Without specifying an output stream (defaults to std::cout): print_table(column_labels, width, precision, separator, header_prefix)
+     *
+     * @param[in,out] out Which ostream to use (optional, see above).
+     * @param[in] column_labels Vector of custom labels for each column.
+     * @param[in] width The number of characters reserved for each number.
+     * @param[in] precision The number of decimals.
+     * @param[in] separator Separator character between columns.
+     * @param[in] header_prefix Prefix before the header row.
+     *
+     * @{
      */
-    void print_table(const std::vector<std::string>& column_labels = {}, size_t width = 16, size_t precision = 5,
-                     std::ostream& out = std::cout) const
+    void print_table(std::ostream& out, const std::vector<std::string>& column_labels = {}, size_t width = 16,
+                     size_t precision = 5, char separator = ' ', const std::string header_prefix = "\n") const
     {
         // Note: input manipulators (like std::setw, std::left) are consumed by the first argument written to the stream
         // print column labels
         const auto w = width, p = precision;
-        set_ostream_format(out, w, p) << std::left << "\nTime";
+        out << header_prefix;
+        set_ostream_format(out, w, p) << std::left << "Time";
         for (size_t k = 0; k < static_cast<size_t>(get_num_elements()); k++) {
+            out << separator;
             if (k < column_labels.size()) {
-                out << " ";
                 set_ostream_format(out, w, p) << std::left << column_labels[k];
             }
             else {
-                out << " ";
-                set_ostream_format(out, w, p) << std::left << "#" + std::to_string(k + 1);
+                set_ostream_format(out, w, p) << std::left << "C" + std::to_string(k + 1);
             }
         }
         // print values as table
@@ -524,13 +534,46 @@ class TimeSeries
             set_ostream_format(out, w, p) << std::right << get_time(i);
             auto res_i = get_value(i);
             for (size_t j = 0; j < static_cast<size_t>(res_i.size()); j++) {
-                out << " ";
+                out << separator;
                 set_ostream_format(out, w, p) << std::right << res_i[j];
             }
         }
         out << "\n";
     }
 
+    void print_table(const std::vector<std::string>& column_labels = {}, size_t width = 16, size_t precision = 5,
+                     char separator = ' ', const std::string header_prefix = "\n") const
+    {
+        print_table(std::cout, column_labels, width, precision, separator, header_prefix);
+    }
+    /** @} */
+
+    /**
+     * @brief Exports a TimeSeries object into a CSV file.
+     *
+     * The first column of the CSV file contains the time points. The remaining columns
+     * contain the values at each time point. Column headers can be specified with column_labels.
+     * This function utilizes the print_table method with a width of 1, the 
+     * specified separator, and an empty string as header prefix.
+     *
+     * @param[in] filepath Path to the CSV file.
+     * @param[in] column_labels [Default: {}] Vector of labels for each column after the time column.
+     * @param[in] separator [Default: ','] Separator character.
+     * @param[in] precision [Default: 6] Number of decimals for floating point values.
+     * @return IOResult<void> indicating success or failure.
+     */
+    IOResult<void> export_csv(const std::string& filename, const std::vector<std::string>& column_labels = {},
+                              char separator = ',', int precision = 6) const
+    {
+        std::ofstream file(filename);
+        if (!file.is_open()) {
+            return mio::failure(mio::StatusCode::FileNotFound, "Failed to export TimeSeries as CSV to " + filename);
+        }
+
+        print_table(file, column_labels, 1, precision, separator, "");
+        return mio::success();
+    }
+
     /**
      * print this object (googletest)
      */
@@ -617,9 +660,8 @@ struct TimeSeriesIterTraits {
     }
     using Matrix      = typename TimeSeries<FP>::Matrix;
     using MatrixPtr   = std::conditional_t<IsConst, const Matrix, Matrix>*;
-    using VectorValue = typename decltype(std::declval<MatrixPtr>()
-                                              ->col(std::declval<Eigen::Index>())
-                                              .tail(std::declval<Eigen::Index>()))::PlainObject;
+    using VectorValue = typename decltype(
+        std::declval<MatrixPtr>()->col(std::declval<Eigen::Index>()).tail(std::declval<Eigen::Index>()))::PlainObject;
     using VectorReference =
         decltype(std::declval<MatrixPtr>()->col(std::declval<Eigen::Index>()).tail(std::declval<Eigen::Index>()));
     using TimeValue     = FP;
diff --git a/cpp/tests/test_time_series.cpp b/cpp/tests/test_time_series.cpp
@@ -22,6 +22,7 @@
 #include "matchers.h"
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
+#include "temp_file_register.h"
 
 template <class T>
 using TestTimeSeries = ::testing::Test;
@@ -314,7 +315,7 @@ TYPED_TEST(TestTimeSeries, iteratorsRandomAccess)
 
 TYPED_TEST(TestTimeSeries, create)
 {
-    auto ts = mio::TimeSeries<double>::zero(5, 10);
+    auto ts = mio::TimeSeries<TypeParam>::zero(5, 10);
     for (int i = 0; i < 5; i++) {
         ASSERT_EQ(ts.get_time(i), 0.0);
         for (int j = 0; j < 10; j++) {
@@ -326,40 +327,166 @@ TYPED_TEST(TestTimeSeries, create)
 TYPED_TEST(TestTimeSeries, print_table)
 {
     std::stringstream output;
-    mio::TimeSeries<double> ts = mio::TimeSeries<double>::zero(2, 2);
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(2, 2);
     for (int i = 0; i < 2; i++) {
         for (int j = 0; j < 2; j++) {
-            ts[i][j] = i + j + 0.123456789;
+            ts[i][j] = static_cast<TypeParam>(i + j + 0.123456);
         }
     }
-    ts.get_time((Eigen::Index)0) = 0.0;
-    ts.get_time((Eigen::Index)1) = 1.0;
+    ts.get_time((Eigen::Index)0) = static_cast<TypeParam>(0.0);
+    ts.get_time((Eigen::Index)1) = static_cast<TypeParam>(1.0);
 
     std::string expected_output_1 = "\nTime col_1 col_2\n0.00 0.12 1.12\n1.00 1.12 2.12\n";
-    ts.print_table({"col_1", "col_2"}, 4, 2, output);
+    ts.print_table(output, {"col_1", "col_2"}, 4, 2);
     std::string actual_output_1 = output.str();
     EXPECT_EQ(expected_output_1, actual_output_1);
 
     output.str("");
 
-    std::string expected_output_2 = "\nTime  #1     #2    \n   0.0    0.1    1.1\n   1.0    1.1    2.1\n";
-    ts.print_table({}, 6, 1, output);
+    std::string expected_output_2 = "\nTime   C1     C2    \n   0.0    0.1    1.1\n   1.0    1.1    2.1\n";
+    ts.print_table(output, {}, 6, 1);
     std::string actual_output_2 = output.str();
     EXPECT_EQ(expected_output_2, actual_output_2);
 
     output.str("");
 
-    std::string expected_output_3 = "\nTime        col_1        #2          \n      0.0000       0.1235       "
+    std::string expected_output_3 = "\nTime         col_1        C2          \n      0.0000       0.1235       "
                                     "1.1235\n      1.0000       1.1235       2.1235\n";
-    ts.print_table({"col_1"}, 12, 4, output);
+    ts.print_table(output, {"col_1"}, 12, 4);
     std::string actual_output_3 = output.str();
     EXPECT_EQ(expected_output_3, actual_output_3);
 }
 
-TEST(TestTimeSeries, printTo)
+TYPED_TEST(TestTimeSeries, print_table_cout_overload)
+{
+    // Just test that the print_table overload without ostream argument doesn't throw any exceptions.
+    // The function behaviour is tested in "TestTimeSeries.print_table".
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(1, 1);
+    ASSERT_NO_FATAL_FAILURE(ts.print_table());
+}
+
+TYPED_TEST(TestTimeSeries, export_csv)
+{
+    // Fill time series with test data
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(2, 2);
+    for (int i = 0; i < 2; i++) {
+        for (int j = 0; j < 2; j++) {
+            ts[i][j] = static_cast<TypeParam>(i + j + 0.123456);
+        }
+    }
+    ts.get_time((Eigen::Index)0) = static_cast<TypeParam>(0.0);
+    ts.get_time((Eigen::Index)1) = static_cast<TypeParam>(1.0);
+
+    // Create a temp file for testing
+    TempFileRegister file_register;
+    auto csv_file_path = file_register.get_unique_path("test_csv-%%%%-%%%%.csv");
+
+    // Test export_csv function
+    auto result = ts.export_csv(csv_file_path, {"column1", "column2"});
+    ASSERT_TRUE(result);
+
+    // Read file and check data
+    std::ifstream file(csv_file_path);
+    ASSERT_TRUE(file.is_open());
+
+    std::string line;
+    std::getline(file, line);
+    EXPECT_EQ(line, "Time,column1,column2");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "0.000000,0.123456,1.123456");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "1.000000,1.123456,2.123456");
+
+    file.close();
+}
+
+TYPED_TEST(TestTimeSeries, export_csv_no_labels)
+{
+    // Fill time series with test data
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(2, 2);
+    for (int i = 0; i < 2; i++) {
+        for (int j = 0; j < 2; j++) {
+            ts[i][j] = static_cast<TypeParam>(i + j + 0.123456);
+        }
+    }
+    ts.get_time((Eigen::Index)0) = static_cast<TypeParam>(0.0);
+    ts.get_time((Eigen::Index)1) = static_cast<TypeParam>(1.0);
+
+    // Create a temp file for testing
+    TempFileRegister file_register;
+    auto csv_file_path = file_register.get_unique_path("test_csv-%%%%-%%%%.csv");
+
+    // Test export_csv function without column names
+    auto result = ts.export_csv(csv_file_path);
+    ASSERT_TRUE(result);
+
+    // Read file and check data
+    std::ifstream file(csv_file_path);
+    ASSERT_TRUE(file.is_open());
+
+    std::string line;
+    std::getline(file, line);
+    EXPECT_EQ(line, "Time,C1,C2");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "0.000000,0.123456,1.123456");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "1.000000,1.123456,2.123456");
+
+    file.close();
+}
+
+TYPED_TEST(TestTimeSeries, export_csv_different_separator)
+{
+    // Fill time series with test data
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(2, 2);
+    for (int i = 0; i < 2; i++) {
+        for (int j = 0; j < 2; j++) {
+            ts[i][j] = static_cast<TypeParam>(i + j + 0.123456);
+        }
+    }
+    ts.get_time((Eigen::Index)0) = static_cast<TypeParam>(0.0);
+    ts.get_time((Eigen::Index)1) = static_cast<TypeParam>(1.0);
+
+    // Create a temp file for testing
+    TempFileRegister file_register;
+    auto csv_file_path = file_register.get_unique_path("test_csv-%%%%-%%%%.csv");
+
+    // Export using semicolon as separator and precision of 3
+    auto result = ts.export_csv(csv_file_path, {"col1", "col2"}, ';', 3);
+    ASSERT_TRUE(result);
+
+    // Read file and check data
+    std::ifstream file(csv_file_path);
+    ASSERT_TRUE(file.is_open());
+
+    std::string line;
+    std::getline(file, line);
+    EXPECT_EQ(line, "Time;col1;col2");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "0.000;0.123;1.123");
+
+    std::getline(file, line);
+    EXPECT_EQ(line, "1.000;1.123;2.123");
+
+    file.close();
+}
+
+TYPED_TEST(TestTimeSeries, export_csv_failed)
+{
+    mio::TimeSeries<TypeParam> ts = mio::TimeSeries<TypeParam>::zero(2, 2);
+    auto result                   = ts.export_csv("/test_false_dir/file.csv");
+    ASSERT_FALSE(result);
+}
+
+TYPED_TEST(TestTimeSeries, printTo)
 {
     //PrintTo is test code, so we don't check the exact output, just that it exists and doesn't fail
-    auto ts = mio::TimeSeries<double>::zero(3, 2);
+    auto ts = mio::TimeSeries<TypeParam>::zero(3, 2);
     std::stringstream ss;
     PrintTo(ts, &ss);
     ASSERT_FALSE(ss.str().empty());
diff --git a/pycode/memilio-simulation/memilio/simulation/bindings/utils/time_series.cpp b/pycode/memilio-simulation/memilio/simulation/bindings/utils/time_series.cpp
@@ -63,13 +63,28 @@ void bind_time_series(py::module_& m, std::string const& name)
                 }
             },
             py::is_operator(), py::arg("index"), py::arg("v"))
-        .def("print_table",
-             [](const mio::TimeSeries<double>& self, const std::vector<std::string>& column_labels, size_t width,
-                size_t precision) {
-                 std::ostringstream oss;
-                 self.print_table(column_labels, width, precision, oss);
-                 return oss.str();
-             })
+        .def(
+            "print_table",
+            [](const mio::TimeSeries<double>& self, const std::vector<std::string>& column_labels, size_t width,
+               size_t precision, char separator, const std::string& header_prefix) {
+                std::ostringstream oss;
+                self.print_table(oss, column_labels, width, precision, separator, header_prefix);
+                return oss.str();
+            },
+            py::arg("column_labels") = std::vector<std::string>{}, py::arg("width") = 16, py::arg("precision") = 5,
+            py::arg("separator") = ' ', py::arg("header_prefix") = "\n")
+
+        .def(
+            "export_csv",
+            [](const mio::TimeSeries<double>& self, const std::string& filename,
+               const std::vector<std::string>& column_labels, char separator, int precision) {
+                auto result = self.export_csv(filename, column_labels, separator, precision);
+                if (!result) {
+                    throw py::value_error(result.error().message());
+                }
+            },
+            py::arg("filename"), py::arg("column_labels") = std::vector<std::string>{}, py::arg("separator") = ',',
+            py::arg("precision") = 6)
         .def("add_time_point",
              [](mio::TimeSeries<double>& self) {
                  return self.add_time_point();
diff --git a/pycode/memilio-simulation/memilio/simulation_test/test_time_series.py b/pycode/memilio-simulation/memilio/simulation_test/test_time_series.py
