Added AddNote Algorithm

Refs #12172

Code/Mantid/Framework/Algorithms/CMakeLists.txt

@@ -4,6 +4,7 @@ set ( SRC_FILES
 	# src/UpdatePeakParameterTable.cpp
 	src/AbsorptionCorrection.cpp
 	src/AddLogDerivative.cpp
+	src/AddNote.cpp
 	src/AddPeak.cpp
 	src/AddSampleLog.cpp
 	src/AddTimeSeriesLog.cpp
@@ -267,6 +268,7 @@ set ( INC_FILES
 	# inc/MantidAlgorithms/UpdatePeakParameterTable.h
 	inc/MantidAlgorithms/AbsorptionCorrection.h
 	inc/MantidAlgorithms/AddLogDerivative.h
+	inc/MantidAlgorithms/AddNote.h
 	inc/MantidAlgorithms/AddPeak.h
 	inc/MantidAlgorithms/AddSampleLog.h
 	inc/MantidAlgorithms/AddTimeSeriesLog.h
@@ -541,6 +543,7 @@ set ( TEST_FILES
 	# CountEventsInPulsesTest.h
 	# UpdatePeakParameterTableTest.h
 	AddLogDerivativeTest.h
+	AddNoteTest.h
 	AddPeakTest.h
 	AddSampleLogTest.h
 	AddTimeSeriesLogTest.h

Code/Mantid/Framework/Algorithms/inc/MantidAlgorithms/AddNote.h

+#ifndef MANTID_ALGORITHMS_ADDNOTE_H_
+#define MANTID_ALGORITHMS_ADDNOTE_H_
+
+#include "MantidAPI/Algorithm.h"
+
+namespace Mantid {
+namespace Algorithms {
+
+/** AddNote : TODO: DESCRIPTION
+
+  Copyright © 2015 ISIS Rutherford Appleton Laboratory, NScD Oak Ridge
+  National Laboratory & European Spallation Source
+
+  This file is part of Mantid.
+
+  Mantid is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 3 of the License, or
+  (at your option) any later version.
+
+  Mantid is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  File change history is stored at: <https://github.com/mantidproject/mantid>
+  Code Documentation is available at: <http://doxygen.mantidproject.org>
+*/
+class DLLExport AddNote : public API::Algorithm {
+public:
+  AddNote();
+  virtual ~AddNote();
+
+  virtual const std::string name() const;
+  virtual int version() const;
+  virtual const std::string category() const;
+  virtual const std::string summary() const;
+
+private:
+  void init();
+  void exec();
+
+  /// Remove an existing log of the given name
+  void removeExisting(API::MatrixWorkspace_sptr &logWS,
+                      const std::string &name);
+  /// Create or update the named log entry
+  void createOrUpdate(API::Run &run, const std::string &name);
+};
+
+} // namespace Algorithms
+} // namespace Mantid
+
+#endif /* MANTID_ALGORITHMS_ADDNOTE_H_ */
\ No newline at end of file

Code/Mantid/Framework/Algorithms/src/AddNote.cpp

+#include "MantidAlgorithms/AddNote.h"
+#include "MantidKernel/DateTimeValidator.h"
+#include "MantidKernel/MandatoryValidator.h"
+#include "MantidKernel/TimeSeriesProperty.h"
+
+namespace Mantid {
+namespace Algorithms {
+
+using namespace API;
+using namespace Kernel;
+
+namespace {
+/**
+ * Creates/updates the named log on the given run.
+ * @param run A reference to the run object that stores the logs
+ * @param name The name of the log that is to be either created or updated
+ * @param time A time string in ISO format, passed to the DateAndTime
+ * constructor
+ * @param value The value at the given time
+ */
+void createOrUpdateValue(API::Run &run, const std::string &name,
+                         const std::string &time, const std::string value) {
+  TimeSeriesProperty<std::string> *timeSeries(NULL);
+  if (run.hasProperty(name)) {
+    timeSeries =
+        dynamic_cast<TimeSeriesProperty<std::string> *>(run.getLogData(name));
+    if (!timeSeries)
+      throw std::invalid_argument(
+          "Log '" + name +
+          "' already exists but the values are a different type.");
+  } else {
+    timeSeries = new TimeSeriesProperty<std::string>(name);
+    run.addProperty(timeSeries);
+  }
+  timeSeries->addValue(time, value);
+}
+}
+
+// Register the algorithm into the AlgorithmFactory
+DECLARE_ALGORITHM(AddNote)
+
+//----------------------------------------------------------------------------------------------
+AddNote::AddNote() {}
+
+AddNote::~AddNote() {}
+
+//----------------------------------------------------------------------------------------------
+
+/// Algorithms name for identification. @see Algorithm::name
+const std::string AddNote::name() const { return "AddNote"; }
+
+/// Algorithm's version for identification. @see Algorithm::version
+int AddNote::version() const { return 1; }
+
+/// Algorithm's category for identification. @see Algorithm::category
+const std::string AddNote::category() const { return "DataHandling\\Logs"; }
+
+/// Algorithm's summary for use in the GUI and help. @see Algorithm::summary
+const std::string AddNote::summary() const {
+  return "Adds a timestamped note to a workspace.";
+}
+
+//----------------------------------------------------------------------------------------------
+/** Initialize the algorithm's properties.
+ */
+void AddNote::init() {
+  declareProperty(
+      new WorkspaceProperty<MatrixWorkspace>("Workspace", "", Direction::InOut),
+      "An InOut workspace that will store the new log information");
+
+  declareProperty("Name", "",
+                  boost::make_shared<MandatoryValidator<std::string>>(),
+                  "A String name for either a new time series log to be "
+                  "created or an existing name to update",
+                  Direction::Input);
+  declareProperty(
+      "Time", "", boost::make_shared<DateTimeValidator>(),
+      "An ISO formatted date/time string specifying the timestamp for "
+      "the given log value, e.g 2010-09-14T04:20:12",
+      Direction::Input);
+
+  declareProperty(
+      "Value", "", boost::make_shared<MandatoryValidator<std::string>>(),
+      "A String value for the series log at the given time", Direction::Input);
+
+  declareProperty(
+      "DeleteExisting", false,
+      "If true and the named log exists then the whole log is removed first.",
+      Direction::Input);
+}
+
+//----------------------------------------------------------------------------------------------
+/** Executes the algorithm.
+ */
+void AddNote::exec() {
+  MatrixWorkspace_sptr logWS = getProperty("Workspace");
+  std::string name = getProperty("Name");
+
+  const bool deleteExisting = getProperty("DeleteExisting");
+  auto &run = logWS->mutableRun();
+  if (deleteExisting && run.hasProperty(name)) {
+    removeExisting(logWS, name);
+  }
+  createOrUpdate(run, name);
+}
+
+/**
+ * Removes an existing instance of the log from the Workspace
+ * @param logWS The workspace containing the log
+ * @param name The name of the log to delete
+ */
+void AddNote::removeExisting(API::MatrixWorkspace_sptr &logWS,
+                             const std::string &name) {
+  auto deleter = createChildAlgorithm("DeleteLog", -1, -1, false);
+  deleter->setProperty("Workspace", logWS);
+  deleter->setProperty("Name", name);
+  deleter->executeAsChildAlg();
+}
+
+/**
+ * Obtains variables to use in createOrUpdateValue function
+ * @param run The run object that either has the log or will store it
+ * @param name The name of the log to create/update
+ */
+void AddNote::createOrUpdate(API::Run &run, const std::string &name) {
+  std::string time = getProperty("Time");
+  std::string value = getProperty("Value");
+
+  createOrUpdateValue(run, name, time, value);
+}
+
+} // namespace Algorithms
+} // namespace Mantid
\ No newline at end of file

Code/Mantid/Framework/Algorithms/test/AddNoteTest.h

+#ifndef MANTID_ALGORITHMS_ADDNOTETEST_H_
+#define MANTID_ALGORITHMS_ADDNOTETEST_H_
+
+#include <cxxtest/TestSuite.h>
+#include "MantidAlgorithms/AddNote.h"
+#include "MantidKernel/TimeSeriesProperty.h"
+#include "MantidTestHelpers/WorkspaceCreationHelper.h"
+
+class AddNoteTest : public CxxTest::TestSuite {
+
+private:
+  enum UpdateType { Update, Delete };
+
+public:
+  // This pair of boilerplate methods prevent the suite being created statically
+  // This means the constructor isn't called when running other tests
+  static AddNoteTest *createSuite() { return new AddNoteTest(); }
+  static void destroySuite(AddNoteTest *suite) { delete suite; }
+
+  void test_delete_existing_removes_complete_log_first() {
+    auto ws = WorkspaceCreationHelper::Create2DWorkspace(10, 10);
+    TS_ASSERT_THROWS_NOTHING(executeAlgorithm(
+        ws, "Test Name", "2010-09-14T04:20:12", "First Test String"));
+    checkLogWithEntryExists<std::string>(ws, "Test Name", "2010-09-14T04:20:12",
+                                         "First Test String", 0);
+    TS_ASSERT_THROWS_NOTHING(executeAlgorithm(
+        ws, "Test Name", "2010-09-14T04:20:19", "Second Test String", Delete));
+    checkLogWithEntryExists<std::string>(ws, "Test Name", "2010-09-14T04:20:19",
+                                         "Second Test String", 0);
+  }
+
+  //-------------------------- Failure cases----------------------------
+  void test_empty_log_name_not_allowed() {
+    Mantid::Algorithms::AddNote alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+
+    TS_ASSERT_THROWS(alg.setPropertyValue("Name", ""), std::invalid_argument);
+  }
+
+  void test_empty_time_not_allowed() {
+    Mantid::Algorithms::AddNote alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+
+    TS_ASSERT_THROWS(alg.setPropertyValue("Time", ""), std::invalid_argument);
+  }
+
+  void test_empty_value_not_allowed() {
+    Mantid::Algorithms::AddNote alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+
+    TS_ASSERT_THROWS(alg.setPropertyValue("Value", ""), std::invalid_argument);
+  }
+
+  void test_time_as_non_iso_formatted_string_throws_invalid_argument() {
+    Mantid::Algorithms::AddNote alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+
+    TS_ASSERT_THROWS(alg.setPropertyValue("Time", "NotATime"),
+                     std::invalid_argument);
+    TS_ASSERT_THROWS(alg.setPropertyValue("Time", "2014 03 31 09 30"),
+                     std::invalid_argument);
+    TS_ASSERT_THROWS(alg.setPropertyValue("Time", "09:30:00"),
+                     std::invalid_argument);
+  }
+
+  void test_algorithm_fails_if_log_exists_but_is_not_a_time_series() {
+    auto ws = WorkspaceCreationHelper::Create2DWorkspace(10, 10);
+    auto &run = ws->mutableRun();
+    run.addProperty<std::string>("Test Name", "Test");
+    TS_ASSERT_THROWS(
+        executeAlgorithm(ws, "Test Name", "2010-09-14T04:20:12", "Test String"),
+        std::invalid_argument);
+  }
+
+  void test_Init() {
+    Mantid::Algorithms::AddNote alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+    TS_ASSERT(alg.isInitialized());
+  }
+
+private:
+  void executeAlgorithm(Mantid::API::MatrixWorkspace_sptr testWS,
+                        const std::string &logName, const std::string &logTime,
+                        const std::string logValue,
+                        const UpdateType update = Update) {
+
+    Mantid::Algorithms::AddNote alg;
+    alg.setChild(true);
+    TS_ASSERT_THROWS_NOTHING(alg.initialize());
+    TS_ASSERT(alg.isInitialized());
+
+    alg.setProperty("Workspace", testWS);
+    alg.setPropertyValue("Name", logName);
+    alg.setPropertyValue("Time", logTime);
+    alg.setProperty("Value", logValue);
+    if (update == Delete) {
+      alg.setProperty("DeleteExisting", true);
+    }
+    alg.setRethrows(true);
+    alg.execute();
+  }
+
+  template <typename T>
+  void checkLogWithEntryExists(Mantid::API::MatrixWorkspace_sptr testWS,
+                               const std::string &logName,
+                               const std::string &logTime,
+                               const std::string logValue,
+                               const size_t position) {
+    using Mantid::Kernel::DateAndTime;
+    using Mantid::Kernel::TimeSeriesProperty;
+
+    const auto &run = testWS->run();
+    TSM_ASSERT("Run does not contain the expected log entry",
+               run.hasProperty(logName));
+
+    auto *prop = run.getLogData(logName);
+    auto *timeSeries = dynamic_cast<TimeSeriesProperty<T> *>(prop);
+    TSM_ASSERT(
+        "A log entry with the given name exists but it is not a time series",
+        timeSeries);
+    auto times = timeSeries->timesAsVector();
+    TS_ASSERT(times.size() >= position + 1);
+    auto values = timeSeries->valuesAsVector();
+    TS_ASSERT_EQUALS(DateAndTime(logTime), times[position]);
+    TS_ASSERT(values.size() >= position + 1);
+    TS_ASSERT_EQUALS(logValue, values[position]);
+  }
+};
+
+#endif /* MANTID_ALGORITHMS_ADDNOTETEST_H_ */
\ No newline at end of file

Code/Mantid/docs/source/algorithms/AddNote-v1.rst

+
+.. algorithm::
+
+.. summary::
+
+.. alias::
+
+.. properties::
+
+Description
+-----------
+
+TODO: Enter a full rst-markup description of your algorithm here.
+
+
+Usage
+-----
+..  Try not to use files in your examples,
+    but if you cannot avoid it then the (small) files must be added to
+    autotestdata\UsageData and the following tag unindented
+    .. include:: ../usagedata-note.txt
+
+**Example - AddNote**
+
+.. testcode:: AddNoteExample
+
+   # Create a host workspace
+   ws = CreateWorkspace(DataX=range(0,3), DataY=(0,2))
+   or
+   ws = CreateSampleWorkspace()
+
+   wsOut = AddNote()
+
+   # Print the result
+   print "The output workspace has %i spectra" % wsOut.getNumberHistograms()
+
+Output:
+
+.. testoutput:: AddNoteExample
+
+  The output workspace has ?? spectra
+
+.. categories::
+