Merge pull request #14052 from mantidproject/feature/13867_AddNote_make_log_optional

Add Comment Algorithm

Framework/API/inc/MantidAPI/ScriptBuilder.h

@@ -60,6 +60,7 @@ private:
   void buildChildren(std::ostringstream &os,
                      std::vector<HistoryItem>::const_iterator &iter,
                      int depth = 1);
+  const std::string buildCommentString(AlgorithmHistory_const_sptr algHistory);
   const std::string
   buildAlgorithmString(AlgorithmHistory_const_sptr algHistory);
   const std::string

Framework/API/src/ScriptBuilder.cpp

@@ -19,6 +19,8 @@ namespace {
 Mantid::Kernel::Logger g_log("ScriptBuilder");
 }
 
+const std::string COMMENT_ALG = "Comment";
+
 ScriptBuilder::ScriptBuilder(boost::shared_ptr<HistoryView> view,
                              std::string versionSpecificity)
     : m_historyItems(view->getAlgorithmsList()), m_output(),
@@ -99,17 +101,41 @@ void ScriptBuilder::buildChildren(
 }
 
 /**
- * Build the script output for a single algorithm
- *
- * @param algHistory :: pointer to an algorithm history object
- * @returns std::string to run this algorithm
- */
+* Build the script output for a single comment
+*
+* @param algHistory :: pointer to an algorithm history object
+* @returns std::string to run this algorithm
+*/
+const std::string
+ScriptBuilder::buildCommentString(AlgorithmHistory_const_sptr algHistory) {
+  std::ostringstream comment;
+  const std::string name = algHistory->name();
+  if (name == COMMENT_ALG) {
+    auto props = algHistory->getProperties();
+    for (auto propIter = props.begin(); propIter != props.end(); ++propIter) {
+      if ((*propIter)->name() == "Note") {
+        comment << "# " << (*propIter)->value();
+      }
+    }
+  }
+  return comment.str();
+}
+
+/**
+* Build the script output for a single algorithm
+*
+* @param algHistory :: pointer to an algorithm history object
+* @returns std::string to run this algorithm
+*/
 const std::string
 ScriptBuilder::buildAlgorithmString(AlgorithmHistory_const_sptr algHistory) {
   std::ostringstream properties;
   const std::string name = algHistory->name();
   std::string prop = "";
 
+  if (name == COMMENT_ALG)
+    return buildCommentString(algHistory);
+
   auto props = algHistory->getProperties();
   for (auto propIter = props.begin(); propIter != props.end(); ++propIter) {
     prop = buildPropertyString(*propIter);

Framework/Algorithms/CMakeLists.txt

@@ -40,6 +40,7 @@ set ( SRC_FILES
 	src/ClearInstrumentParameters.cpp
 	src/ClearMaskFlag.cpp
 	src/CloneWorkspace.cpp
+	src/Comment.cpp
 	src/CommutativeBinaryOperation.cpp
 	src/ConjoinWorkspaces.cpp
 	src/ConvertAxesToRealSpace.cpp
@@ -126,12 +127,12 @@ set ( SRC_FILES
 	src/FlatPlateAbsorption.cpp
 	src/GeneralisedSecondDifference.cpp
 	src/GenerateEventsFilter.cpp
+	src/GenerateIPythonNotebook.cpp
 	src/GeneratePeaks.cpp
 	src/GeneratePythonScript.cpp
 	src/GetAllEi.cpp
 	src/GetDetOffsetsMultiPeaks.cpp
 	src/GetDetectorOffsets.cpp
-	src/GetAllEi.cpp
 	src/GetEi.cpp
 	src/GetEi2.cpp
 	src/GetTimeSeriesLogInformation.cpp
@@ -272,7 +273,7 @@ set ( SRC_FILES
 	src/WienerSmooth.cpp
 	src/WorkspaceJoiners.cpp
 	src/XDataConverter.cpp
-    src/GenerateIPythonNotebook.cpp)
+)
 
 set ( INC_FILES
 	#	inc/MantidAlgorithms/Q1DTOF.h
@@ -316,6 +317,7 @@ set ( INC_FILES
 	inc/MantidAlgorithms/ClearInstrumentParameters.h
 	inc/MantidAlgorithms/ClearMaskFlag.h
 	inc/MantidAlgorithms/CloneWorkspace.h
+	inc/MantidAlgorithms/Comment.h
 	inc/MantidAlgorithms/CommutativeBinaryOperation.h
 	inc/MantidAlgorithms/ConjoinWorkspaces.h
 	inc/MantidAlgorithms/ConvertAxesToRealSpace.h
@@ -401,11 +403,12 @@ set ( INC_FILES
 	inc/MantidAlgorithms/FixGSASInstrumentFile.h
 	inc/MantidAlgorithms/FlatPlateAbsorption.h
 	inc/MantidAlgorithms/GSLFunctions.h
-	inc/MantidAlgorithms/GetAllEi.h
 	inc/MantidAlgorithms/GeneralisedSecondDifference.h
 	inc/MantidAlgorithms/GenerateEventsFilter.h
+	inc/MantidAlgorithms/GenerateIPythonNotebook.h
 	inc/MantidAlgorithms/GeneratePeaks.h
 	inc/MantidAlgorithms/GeneratePythonScript.h
+	inc/MantidAlgorithms/GetAllEi.h
 	inc/MantidAlgorithms/GetDetOffsetsMultiPeaks.h
 	inc/MantidAlgorithms/GetDetectorOffsets.h
 	inc/MantidAlgorithms/GetEi.h
@@ -549,7 +552,7 @@ set ( INC_FILES
 	inc/MantidAlgorithms/WienerSmooth.h
 	inc/MantidAlgorithms/WorkspaceJoiners.h
 	inc/MantidAlgorithms/XDataConverter.h
-    inc/MantidAlgorithms/GenerateIPythonNotebook.h)
+)
 
 set(SRC_UNITY_IGNORE_FILES src/AlignDetectors.cpp
     src/FFTSmooth.cpp
@@ -603,6 +606,7 @@ set ( TEST_FILES
 	ClearInstrumentParametersTest.h
 	ClearMaskFlagTest.h
 	CloneWorkspaceTest.h
+	CommentTest.h
 	CommutativeBinaryOperationTest.h
 	ConjoinWorkspacesTest.h
 	ConvertAxesToRealSpaceTest.h

Framework/Algorithms/inc/MantidAlgorithms/Comment.h

+#ifndef MANTID_ALGORITHMS_COMMENT_H_
+#define MANTID_ALGORITHMS_COMMENT_H_
+
+#include "MantidAlgorithms/DllConfig.h"
+#include "MantidAPI/Algorithm.h"
+namespace Mantid {
+namespace Algorithms {
+
+/** Comment : Adds a note into the history record of a workspace
+
+  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 Comment : public API::Algorithm {
+public:
+  Comment();
+  virtual ~Comment();
+
+  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();
+};
+
+} // namespace Algorithms
+} // namespace Mantid
+
+#endif /* MANTID_ALGORITHMS_COMMENT_H_ */

Framework/Algorithms/src/Comment.cpp

+#include "MantidAlgorithms/Comment.h"
+#include "MantidKernel/MandatoryValidator.h"
+
+namespace Mantid {
+namespace Algorithms {
+
+using Mantid::Kernel::Direction;
+using Mantid::Kernel::MandatoryValidator;
+using Mantid::API::WorkspaceProperty;
+using Mantid::API::Workspace;
+
+// Register the algorithm into the AlgorithmFactory
+DECLARE_ALGORITHM(Comment)
+
+//----------------------------------------------------------------------------------------------
+/** Constructor
+ */
+Comment::Comment() {}
+
+//----------------------------------------------------------------------------------------------
+/** Destructor
+ */
+Comment::~Comment() {}
+
+//----------------------------------------------------------------------------------------------
+
+/// Algorithms name for identification. @see Algorithm::name
+const std::string Comment::name() const { return "Comment"; }
+
+/// Algorithm's version for identification. @see Algorithm::version
+int Comment::version() const { return 1; }
+
+/// Algorithm's category for identification. @see Algorithm::category
+const std::string Comment::category() const { return "DataHandling"; }
+
+/// Algorithm's summary for use in the GUI and help. @see Algorithm::summary
+const std::string Comment::summary() const {
+  return "Adds a comment into the history record of a workspace";
+}
+
+//----------------------------------------------------------------------------------------------
+/** Initialize the algorithm's properties.
+ */
+void Comment::init() {
+  declareProperty(
+      new WorkspaceProperty<Workspace>("Workspace", "", Direction::InOut),
+      "An InOut workspace that will store the new history comment");
+
+  declareProperty("Text", "",
+                  boost::make_shared<MandatoryValidator<std::string>>(),
+                  "The text you want to store in the history of the workspace",
+                  Direction::Input);
+
+  // always record history for this algorithm
+  enableHistoryRecordingForChild(true);
+}
+
+//----------------------------------------------------------------------------------------------
+/** Execute the algorithm.
+ */
+void Comment::exec() {
+  // do nothing
+}
+
+} // namespace Algorithms
+} // namespace Mantid

Framework/Algorithms/test/CommentTest.h

+#ifndef MANTID_ALGORITHMS_COMMENTTEST_H_
+#define MANTID_ALGORITHMS_COMMENTTEST_H_
+
+#include <cxxtest/TestSuite.h>
+
+#include "MantidAlgorithms/Comment.h"
+#include "MantidAPI/Workspace.h"
+#include "MantidTestHelpers/WorkspaceCreationHelper.h"
+
+using namespace Mantid::API;
+
+class CommentTest : public CxxTest::TestSuite {
+public:
+  // This pair of boilerplate methods prevent the suite being created statically
+  // This means the constructor isn't called when running other tests
+  static CommentTest *createSuite() { return new CommentTest(); }
+  static void destroySuite(CommentTest *suite) { delete suite; }
+
+  void test_Init() {
+    Mantid::Algorithms::Comment alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize())
+    TS_ASSERT(alg.isInitialized())
+  }
+
+  void test_exec() {
+    std::string wsName = "CommentTest_Exec_workspace";
+    // Create test input
+    auto ws = WorkspaceCreationHelper::Create2DWorkspace(10, 10);
+    AnalysisDataService::Instance().add(wsName, ws);
+    // and an identical ws for comparison later
+    auto ws2 = WorkspaceCreationHelper::Create2DWorkspace(10, 10);
+
+    Mantid::Algorithms::Comment alg;
+    TS_ASSERT_THROWS_NOTHING(alg.initialize())
+    TS_ASSERT(alg.isInitialized())
+    TS_ASSERT_THROWS_NOTHING(alg.setPropertyValue("Workspace", wsName));
+    TS_ASSERT_THROWS_NOTHING(alg.setPropertyValue(
+        "Text", "The next algorithm is doing ws equals 1/ws"));
+    TS_ASSERT_THROWS_NOTHING(alg.execute(););
+    TS_ASSERT(alg.isExecuted());
+
+    // Retrieve the workspace from data service.
+    MatrixWorkspace_sptr outputWS;
+    TS_ASSERT_THROWS_NOTHING(
+        outputWS = AnalysisDataService::Instance().retrieveWS<MatrixWorkspace>(
+            wsName));
+    TS_ASSERT(outputWS);
+    if (!outputWS)
+      return;
+
+    IAlgorithm_sptr lastAlgorithm = outputWS->getHistory().lastAlgorithm();
+
+    TS_ASSERT_EQUALS(lastAlgorithm->getPropertyValue("Workspace"),
+                     alg.getPropertyValue("Workspace"));
+    TS_ASSERT_EQUALS(lastAlgorithm->getPropertyValue("Text"),
+                     alg.getPropertyValue("Text"));
+    TSM_ASSERT("The workspace has been altered by Comment",
+               Mantid::API::equals(ws, ws2));
+
+    AnalysisDataService::Instance().remove(wsName);
+  }
+};
+
+#endif /* MANTID_ALGORITHMS_COMMENTTEST_H_ */
\ No newline at end of file

docs/source/algorithms/Comment-v1.rst

+
+.. algorithm::
+
+.. summary::
+
+.. alias::
+
+.. properties::
+
+Description
+-----------
+
+This simple algorithm just adds a comment record to the history of a workspace and is a simple way of annotating your workflow.
+
+It does not change the data within a workspace in any way.
+
+When outputing the histroy to Python this comment will be rendered as a python comment.
+
+
+Usage
+-----
+
+**Example - Comment**
+
+.. testcode:: CommentExample
+
+   ws = CreateSampleWorkspace()
+
+   Comment(ws,"The next algorithm is doing 1/ws")
+
+   # Print the result
+   print ws.getHistory().lastAlgorithm().getPropertyValue("Text")
+
+Output:
+
+.. testoutput:: CommentExample
+
+  The next algorithm is doing 1/ws
+
+.. categories::
+
+.. sourcelink::
+ :h: Framework/Algorithms/inc/MantidAlgorithms/Comment.h