ConjoinXRuns.cpp

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2018 ISIS Rutherford Appleton Laboratory UKRI,
//   NScD Oak Ridge National Laboratory, European Spallation Source,
//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
// SPDX - License - Identifier: GPL - 3.0 +
#include "MantidAlgorithms/ConjoinXRuns.h"
 
#include "MantidAPI/ADSValidator.h"
#include "MantidAPI/AnalysisDataService.h"
#include "MantidAPI/Axis.h"
#include "MantidAPI/MatrixWorkspace.h"
#include "MantidAPI/NumericAxis.h"
#include "MantidAPI/Run.h"
#include "MantidAPI/WorkspaceGroup.h"
#include "MantidAPI/WorkspaceHistory.h"
#include "MantidAlgorithms/RunCombinationHelpers/RunCombinationHelper.h"
#include "MantidAlgorithms/RunCombinationHelpers/SampleLogsBehaviour.h"
#include "MantidDataObjects/WorkspaceCreation.h"
#include "MantidGeometry/Instrument.h"
#include "MantidHistogramData/Histogram.h"
#include "MantidHistogramData/HistogramDx.h"
#include "MantidHistogramData/HistogramE.h"
#include "MantidHistogramData/HistogramX.h"
#include "MantidHistogramData/HistogramY.h"
#include "MantidHistogramData/LinearGenerator.h"
#include "MantidKernel/ArrayProperty.h"
#include "MantidKernel/Exception.h"
#include "MantidKernel/ListValidator.h"
#include "MantidKernel/Strings.h"
#include "MantidKernel/TimeSeriesProperty.h"
#include "MantidKernel/Unit.h"
#include "MantidKernel/UnitFactory.h"
 
namespace Mantid::Algorithms {
 
using namespace API;
using namespace Kernel;
using namespace RunCombinationOptions;
using namespace DataObjects;
using namespace HistogramData;
 
namespace {
static const std::string INPUT_WORKSPACE_PROPERTY = "InputWorkspaces";
static const std::string OUTPUT_WORKSPACE_PROPERTY = "OutputWorkspace";
static const std::string SAMPLE_LOG_X_AXIS_PROPERTY = "SampleLogAsXAxis";
} // namespace
 
// Register the algorithm into the AlgorithmFactory
DECLARE_ALGORITHM(ConjoinXRuns)
 
const std::string ConjoinXRuns::SUM_MERGE = "conjoin_sample_logs_sum";
const std::string ConjoinXRuns::TIME_SERIES_MERGE = "conjoin_sample_logs_time_series";
const std::string ConjoinXRuns::LIST_MERGE = "conjoin_sample_logs_list";
const std::string ConjoinXRuns::WARN_MERGE = "conjoin_sample_logs_warn";
const std::string ConjoinXRuns::WARN_MERGE_TOLERANCES = "conjoin_sample_logs_warn_tolerances";
const std::string ConjoinXRuns::FAIL_MERGE = "conjoin_sample_logs_fail";
const std::string ConjoinXRuns::FAIL_MERGE_TOLERANCES = "conjoin_sample_logs_fail_tolerances";
 
//----------------------------------------------------------------------------------------------
 
const std::string ConjoinXRuns::name() const { return "ConjoinXRuns"; }
 
int ConjoinXRuns::version() const { return 1; }
 
const std::string ConjoinXRuns::category() const { return "Transforms\\Merging"; }
 
const std::string ConjoinXRuns::summary() const {
  return "Joins the input workspaces horizontally by appending their columns.";
}
 
//----------------------------------------------------------------------------------------------
void ConjoinXRuns::init() {
  declareProperty(
      std::make_unique<ArrayProperty<std::string>>(INPUT_WORKSPACE_PROPERTY, std::make_shared<ADSValidator>()),
      "The names of the input workspaces or workspace groups as a list. At "
      "least two point-data MatrixWorkspaces are "
      "required, having the same instrument, same number of spectra and "
      "units.");
  declareProperty(SAMPLE_LOG_X_AXIS_PROPERTY, "",
                  "The name of the numeric sample log to become the x-axis of the output. "
                  "Empty by default, in which case the x-axis of the input "
                  "workspaces are stitched. "
                  "If specified, this will be the x-axis. It has to be numeric, in which "
                  "case all the input workspaces must have only one point or numeric "
                  "time series, in which case the number "
                  "of elements in the series must match the number of points for each "
                  "workspace.");
  declareProperty(std::make_unique<WorkspaceProperty<API::Workspace>>(OUTPUT_WORKSPACE_PROPERTY, "", Direction::Output),
                  "The output workspace.");
 
  declareProperty(SampleLogsBehaviour::TIME_SERIES_PROP, "", SampleLogsBehaviour::TIME_SERIES_DOC);
  declareProperty(SampleLogsBehaviour::LIST_PROP, "", SampleLogsBehaviour::LIST_DOC);
  declareProperty(SampleLogsBehaviour::WARN_PROP, "", SampleLogsBehaviour::WARN_DOC);
  declareProperty(SampleLogsBehaviour::WARN_TOL_PROP, "", SampleLogsBehaviour::WARN_TOL_DOC);
  declareProperty(SampleLogsBehaviour::FAIL_PROP, "", SampleLogsBehaviour::FAIL_DOC);
  declareProperty(SampleLogsBehaviour::FAIL_TOL_PROP, "", SampleLogsBehaviour::FAIL_TOL_DOC);
  declareProperty(SampleLogsBehaviour::SUM_PROP, "", SampleLogsBehaviour::SUM_DOC);
 
  const std::vector<std::string> failBehaviourOptions = {SKIP_BEHAVIOUR, STOP_BEHAVIOUR};
  declareProperty("FailBehaviour", SKIP_BEHAVIOUR, std::make_shared<StringListValidator>(failBehaviourOptions),
                  "Choose whether to skip the workspace and continue, or stop and "
                  "throw and error, when encountering a failure on merging.");
  declareProperty(
      "LinearizeAxis", false,
      "Choose to set a linear x-axis starting from 1, can be used only if the workspaces have common bins.");
}
 
std::map<std::string, std::string> ConjoinXRuns::validateInputs() {
  std::map<std::string, std::string> issues;
 
  const std::vector<std::string> inputs_given = getProperty(INPUT_WORKSPACE_PROPERTY);
  m_logEntry = getPropertyValue(SAMPLE_LOG_X_AXIS_PROPERTY);
 
  std::vector<std::string> workspaces;
  try { // input workspace must be a group or a MatrixWorkspace
    workspaces = RunCombinationHelper::unWrapGroups(inputs_given);
  } catch (const std::exception &e) {
    issues[INPUT_WORKSPACE_PROPERTY] = std::string(e.what());
  }
 
  // find if there are grouped workspaces that are not Matrix or not a
  // point-data
  for (const auto &input : workspaces) {
    MatrixWorkspace_sptr ws = AnalysisDataService::Instance().retrieveWS<MatrixWorkspace>(input);
    if (!ws) {
      issues[INPUT_WORKSPACE_PROPERTY] += "Workspace " + input + " is not a MatrixWorkspace\n";
    } else if (ws->isHistogramData()) {
      issues[INPUT_WORKSPACE_PROPERTY] += "Workspace " + ws->getName() + " is not a point-data\n";
    } else {
      try {
        ws->blocksize();
      } catch (std::length_error &) {
        issues[INPUT_WORKSPACE_PROPERTY] +=
            "Workspace " + ws->getName() + " has different number of points per histogram\n";
      }
      m_inputWS.emplace_back(ws);
    }
  }
 
  if (m_inputWS.empty()) {
    issues[INPUT_WORKSPACE_PROPERTY] += "There are no point-data"
                                        " MatrixWorkspaces in the input list\n";
  } else {
    RunCombinationHelper combHelper;
    combHelper.setReferenceProperties(m_inputWS.front());
 
    for (const auto &ws : m_inputWS) {
      // check if all the others are compatible with the first one
      std::string compatible = combHelper.checkCompatibility(ws, true);
      if (!compatible.empty()) {
        issues[INPUT_WORKSPACE_PROPERTY] += "Workspace " + ws->getName() + " is not compatible: " + compatible + "\n";
      }
      // if the log entry is given, validate it
      const std::string logValid = checkLogEntry(ws);
      if (!logValid.empty()) {
        issues[INPUT_WORKSPACE_PROPERTY] += "Invalid sample log entry for " + ws->getName() + ": " + logValid + "\n";
      }
    }
  }
  if (getProperty("LinearizeAxis")) {
    auto notCommon = std::find_if(m_inputWS.cbegin(), m_inputWS.cend(), [](auto ws) { return !ws->isCommonBins(); });
    if (notCommon != m_inputWS.cend()) {
      issues[INPUT_WORKSPACE_PROPERTY] +=
          "Workspace " + (*notCommon)->getName() + " is ragged, which is not allowed if linearize axis is requested.\n";
    }
  }
  m_inputWS.clear();
 
  return issues;
}
 
//----------------------------------------------------------------------------------------------
std::string ConjoinXRuns::checkLogEntry(const MatrixWorkspace_sptr &ws) const {
  std::string result;
  if (!m_logEntry.empty()) {
 
    const auto &run = ws->run();
 
    if (!run.hasProperty(m_logEntry)) {
      result = "Log entry does not exist";
    } else {
      try {
        run.getLogAsSingleValue(m_logEntry);
 
        // try if numeric time series, then the size must match to the
        // blocksize
        const auto blocksize = static_cast<int>(ws->y(0).size());
 
        TimeSeriesProperty<double> *timeSeriesDouble(nullptr);
        TimeSeriesProperty<int> *timeSeriesInt(nullptr);
        timeSeriesDouble = dynamic_cast<TimeSeriesProperty<double> *>(run.getLogData(m_logEntry));
        timeSeriesInt = dynamic_cast<TimeSeriesProperty<int> *>(run.getLogData(m_logEntry));
 
        if (timeSeriesDouble) {
          if (blocksize != timeSeriesDouble->size()) {
            result = "Size of the double time series does not match the blocksize";
          }
        } else if (timeSeriesInt) {
          if (blocksize != timeSeriesInt->size()) {
            result = "Size of the int time series does not match the blocksize";
          }
        } else {
          // if numeric scalar, must have one bin
          if (ws->blocksize() != 1) {
            result = "One bin workspaces is required if the log is numeric scalar";
          }
        }
      } catch (std::invalid_argument &) {
        result = "Log entry must be numeric or numeric time series";
      }
    }
  }
  return result;
}
 
//----------------------------------------------------------------------------------------------
std::vector<double> ConjoinXRuns::getXAxis(const MatrixWorkspace_sptr &ws, double &xstart) const {
  std::vector<double> axis;
  const size_t s = ws->y(0).size();
  axis.reserve(s);
  auto &run = ws->run();
  if (getProperty("LinearizeAxis")) {
    for (double ix = xstart; ix < xstart + double(s); ++ix) {
      axis.push_back(ix);
    }
    xstart += double(s);
  } else {
    // try time series first
    TimeSeriesProperty<double> *timeSeriesDouble(nullptr);
    timeSeriesDouble = dynamic_cast<TimeSeriesProperty<double> *>(run.getLogData(m_logEntry));
    if (timeSeriesDouble) {
      // try double series
      axis = timeSeriesDouble->filteredValuesAsVector();
    } else {
      // try int series next
      TimeSeriesProperty<int> *timeSeriesInt(nullptr);
      timeSeriesInt = dynamic_cast<TimeSeriesProperty<int> *>(run.getLogData(m_logEntry));
      if (timeSeriesInt) {
        std::vector<int> intAxis = timeSeriesInt->filteredValuesAsVector();
        axis = std::vector<double>(intAxis.begin(), intAxis.end());
      } else {
        // then scalar
        axis.emplace_back(run.getPropertyAsSingleValue(m_logEntry));
      }
    }
  }
 
  return axis;
}
 
//----------------------------------------------------------------------------------------------
void ConjoinXRuns::fillHistory() {
  // If this is not a child algorithm add the history
  if (!isChild()) {
    // Loop over the input workspaces, making the call that copies their
    // history to the output one
    for (auto &inWS : m_inputWS) {
      m_outWS->history().addHistory(inWS->getHistory());
    }
    // Add the history for the current algorithm to the output
    m_outWS->history().addHistory(m_history);
  }
  // this is a child algorithm, but we still want to keep the history.
  else if (isRecordingHistoryForChild() && m_parentHistory) {
    m_parentHistory->addChildHistory(m_history);
  }
}
 
//----------------------------------------------------------------------------------------------
void ConjoinXRuns::joinSpectrum(int64_t wsIndex) {
  std::vector<double> spectrum;
  std::vector<double> errors;
  std::vector<double> axis;
  std::vector<double> xerrors;
  const auto index = static_cast<size_t>(wsIndex);
  const auto ySize = m_outWS->y(index).size();
  spectrum.reserve(ySize);
  errors.reserve(ySize);
  axis.reserve(ySize);
  xerrors.reserve(ySize);
  for (const auto &input : m_inputWS) {
    const auto &y = input->y(index);
    spectrum.insert(spectrum.end(), y.begin(), y.end());
    const auto &e = input->e(index);
    errors.insert(errors.end(), e.begin(), e.end());
    if (!m_logEntry.empty() || getProperty("LinearizeAxis")) {
      const auto &x = m_axisCache[input->getName()];
      axis.insert(axis.end(), x.begin(), x.end());
    } else {
      const auto &x = input->x(index);
      axis.insert(axis.end(), x.begin(), x.end());
    }
    if (input->hasDx(index)) {
      const auto &dx = input->dx(index);
      xerrors.insert(xerrors.end(), dx.begin(), dx.end());
    }
  }
  m_outWS->setPoints(index, std::move(axis));
  m_outWS->setCounts(index, std::move(spectrum));
  m_outWS->setCountStandardDeviations(index, std::move(errors));
  if (!xerrors.empty())
    m_outWS->setPointStandardDeviations(index, std::move(xerrors));
}
 
//----------------------------------------------------------------------------------------------
void ConjoinXRuns::exec() {
 
  const std::vector<std::string> inputs_given = getProperty(INPUT_WORKSPACE_PROPERTY);
  m_logEntry = getPropertyValue(SAMPLE_LOG_X_AXIS_PROPERTY);
 
  SampleLogsBehaviour::SampleLogNames logEntries = {};
  logEntries.sampleLogsSum = getPropertyValue(SampleLogsBehaviour::SUM_PROP);
  logEntries.sampleLogsTimeSeries = getPropertyValue(SampleLogsBehaviour::TIME_SERIES_PROP);
  logEntries.sampleLogsList = getPropertyValue(SampleLogsBehaviour::LIST_PROP);
  logEntries.sampleLogsWarn = getPropertyValue(SampleLogsBehaviour::WARN_PROP);
  logEntries.sampleLogsWarnTolerances = getPropertyValue(SampleLogsBehaviour::WARN_TOL_PROP);
  logEntries.sampleLogsFail = getPropertyValue(SampleLogsBehaviour::FAIL_PROP);
  logEntries.sampleLogsFailTolerances = getPropertyValue(SampleLogsBehaviour::FAIL_TOL_PROP);
  const std::string sampleLogsFailBehaviour = getProperty("FailBehaviour");
 
  m_inputWS.clear();
 
  for (const auto &input : RunCombinationHelper::unWrapGroups(inputs_given)) {
    MatrixWorkspace_sptr ws = AnalysisDataService::Instance().retrieveWS<MatrixWorkspace>(input);
    m_inputWS.emplace_back(ws);
  }
 
  auto first = m_inputWS.front();
 
  SampleLogsBehaviour::ParameterName parName = {ConjoinXRuns::SUM_MERGE,
                                                ConjoinXRuns::TIME_SERIES_MERGE,
                                                ConjoinXRuns::LIST_MERGE,
                                                ConjoinXRuns::WARN_MERGE,
                                                ConjoinXRuns::WARN_MERGE_TOLERANCES,
                                                ConjoinXRuns::FAIL_MERGE,
                                                ConjoinXRuns::FAIL_MERGE_TOLERANCES};
 
  SampleLogsBehaviour sampleLogsBehaviour = SampleLogsBehaviour(first, g_log, logEntries, parName);
  auto it = m_inputWS.begin();
 
  // Temporary workspace to carry the merged sample logs
  // This is cloned from the first workspace and does not have
  // the correct size to be the output, since the size is unknown
  // at this point. We can check only later which ones are going
  // to be skipped, to compute the size of the output respectively.
  MatrixWorkspace_sptr temp = first->clone();
 
  size_t outBlockSize = (*it)->y(0).size();
  // First sequentially merge the sample logs
  for (++it; it != m_inputWS.end(); ++it) {
    // attempt to merge the sample logs
    try {
      sampleLogsBehaviour.mergeSampleLogs(*it, temp);
      sampleLogsBehaviour.setUpdatedSampleLogs(temp);
      outBlockSize += (*it)->y(0).size();
    } catch (std::invalid_argument &e) {
      if (sampleLogsFailBehaviour == SKIP_BEHAVIOUR) {
        g_log.error() << "Could not join workspace: " << (*it)->getName() << ". Reason: \"" << e.what()
                      << "\". Skipping.\n";
        sampleLogsBehaviour.resetSampleLogs(temp);
        // remove the skipped one from the list
        it = m_inputWS.erase(it);
        --it;
      } else {
        throw std::invalid_argument(e);
      }
    }
  }
 
  if (m_inputWS.size() == 1) {
    g_log.warning() << "Nothing left to join [after skipping the workspaces "
                       "that failed to merge the sample logs].";
    // note, we need to continue still, since
    // the x-axis might need to be changed
  }
 
  if (!m_logEntry.empty() || getProperty("LinearizeAxis")) {
    double xstart = 0;
    for (const auto &ws : m_inputWS) {
      m_axisCache[ws->getName()] = getXAxis(ws, xstart);
    }
  }
 
  // now get the size of the output
  size_t numSpec = first->getNumberHistograms();
 
  m_outWS = create<MatrixWorkspace>(*first, Points(outBlockSize));
 
  // copy over the merged sample logs from the temp
  m_outWS->mutableRun() = temp->run();
 
  m_progress = std::make_unique<Progress>(this, 0.0, 1.0, numSpec);
 
  // Now loop in parallel over all the spectra and join the data
  PARALLEL_FOR_IF(threadSafe(*m_outWS))
  for (int64_t index = 0; index < static_cast<int64_t>(numSpec); ++index) {
    PARALLEL_START_INTERRUPT_REGION
    joinSpectrum(index);
    m_progress->report();
    PARALLEL_END_INTERRUPT_REGION
  }
  PARALLEL_CHECK_INTERRUPT_REGION
 
  if (!m_logEntry.empty()) {
    std::string unit = first->run().getLogData(m_logEntry)->units();
    try {
      m_outWS->getAxis(0)->unit() = UnitFactory::Instance().create(unit);
    } catch (Exception::NotFoundError &) {
      m_outWS->getAxis(0)->unit() = UnitFactory::Instance().create("Empty");
    }
  }
 
  setProperty("OutputWorkspace", m_outWS);
  m_inputWS.clear();
  m_axisCache.clear();
}
} // namespace Mantid::Algorithms