Skip to content

Commit

Permalink
Update documentation to cleanly build with Doxygen
Browse files Browse the repository at this point in the history
  • Loading branch information
@BrianMichell
BrianMichell committed Dec 10, 2024
1 parent 9cc237c commit 5f12765
Show file tree
Hide file tree
Showing 5 changed files with 259 additions and 22 deletions.
52 changes: 47 additions & 5 deletions mdio/dataset.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -390,6 +390,7 @@ from_zmetadata(const std::string& dataset_path) {
}
} // namespace internal

/// @brief A mapping of coordinates to their Variables
using coordinate_map =
std::unordered_map<std::string, std::vector<std::string>>;

Expand All @@ -399,6 +400,15 @@ using coordinate_map =
*/
class Dataset {
public:
/**
* @brief Constructs a Dataset object. It is recommended to use the
* `mdio::Dataset::Open` or `mdio::Dataset::from_json` factory methods to
* construct a Dataset.
* @param metadata The metadata of the dataset.
* @param variables The variables of the dataset.
* @param coordinates The coordinates of the dataset.
* @param domain The domain of the dataset.
*/
Dataset(const nlohmann::json& metadata, const VariableCollection& variables,
const coordinate_map& coordinates,
const tensorstore::IndexDomain<>& domain)
Expand All @@ -407,6 +417,12 @@ class Dataset {
coordinates(coordinates),
domain(domain) {}

/**
* @brief Outputs a string representation of the Dataset.
* @param os The output stream to write to.
* @param dataset The Dataset object to represent.
* @return The output stream.
*/
friend std::ostream& operator<<(std::ostream& os, const Dataset& dataset) {
// Output metadata
os << "Metadata: " << dataset.metadata.dump(4) << "\n";
Expand Down Expand Up @@ -450,6 +466,13 @@ class Dataset {
return variables.get<T, R, M>(variable_name);
}

/**
* @brief Retrieves the intervals for the given labels in the dataset.
* @param labels The labels to retrieve the intervals for or empty to retrieve
* all intervals in the dataset.
* @return An `mdio::Result` containing the intervals if successful, or an
* error if the labels are not found.
*/
template <typename... DimensionIdentifier>
mdio::Result<std::vector<Variable<>::Interval>> get_intervals(
const DimensionIdentifier&... labels) const {
Expand Down Expand Up @@ -479,6 +502,8 @@ class Dataset {
* @brief Constructs a Dataset from a JSON schema.
* This method will validate the JSON schema against the MDIO Dataset schema.
* @param json_schema The JSON schema to validate.
* @param path The path to the dataset.
* @param options The open options to use for the dataset.
* @details \b Usage
*
* Create a dataset given a schema and a path, for a new dataset use options,
Expand Down Expand Up @@ -580,6 +605,11 @@ class Dataset {
typename outer_type<Rest>::type>);
}

/// @cond IGNORE_RECURSIVE_TEMPLATES
// These internal usecase structs were generating potential recursive class
// relation warnings during documentation build, so the warnings are ignored
// here.

// Generate an index sequence
template <size_t... I>
struct index_sequence {};
Expand All @@ -589,6 +619,7 @@ class Dataset {

template <size_t... I>
struct make_index_sequence<0, I...> : index_sequence<I...> {};
/// @endcond

// Function to call `isel` with a parameter pack expanded from the vector
/**
Expand Down Expand Up @@ -975,7 +1006,7 @@ class Dataset {

/**
* @brief Performs a label-based slice on the Dataset
* @param descriptors The descriptors to use for the slice.
* @param label The label to slice on.
* @return An `mdio::Result` containing a sliced Dataset if successful, or an
* error if the slice is invalid.
*/
Expand Down Expand Up @@ -1015,6 +1046,7 @@ class Dataset {
* This method will assume that the Dataset already exists at the specified
* path.
* @param dataset_path The path to the dataset.
* @param options The open options to use for the dataset.
* @details \b Usage
* @code
* auto existing_dataset = mdio::Dataset::Open(
Expand Down Expand Up @@ -1050,6 +1082,7 @@ class Dataset {
* compliant Variable specs.
* @param metadata The metadata for the dataset.
* @param json_variables A vector of correctly constructed Variable specs.
* @param options The open options to use for the dataset.
* @return An `mdio::Result` containing a Dataset if successful, or an error
* if the schema is invalid.
*/
Expand Down Expand Up @@ -1296,6 +1329,11 @@ class Dataset {
return pair.future;
}

/**
* @brief Commits updated Variable level metadata to disk.
* @return A future that will be ready when the metadata has been committed to
* disk.
*/
tensorstore::Future<void> CommitMetadata() {
auto keys = variables.get_iterable_accessor();

Expand Down Expand Up @@ -1414,19 +1452,23 @@ class Dataset {
return pair.future;
}

/**
* @brief Retrieves the dataset level metadata.
* @return The dataset level metadata.
*/
const nlohmann::json& getMetadata() const { return metadata; }

// variables contained in the dataset
/// variables contained in the dataset
VariableCollection variables;

// link a variable name to its coordinates via its name(s)
/// link a variable name to its coordinates via its name(s)
coordinate_map coordinates;

// enumerate the dimensions
/// enumerate the dimensions
tensorstore::IndexDomain<> domain;

private:
// the metadata associated with the dataset (root .zattrs)
/// the metadata associated with the dataset (root .zattrs)
::nlohmann::json metadata;
};
} // namespace mdio
7 changes: 7 additions & 0 deletions mdio/impl.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@
#include "tensorstore/index_space/dimension_identifier.h"
#include "tensorstore/tensorstore.h"

// Suppress warnings about typedefs in the documentation
// These typedefs are all self-explanatory and shouldn't require explicit
// documentation.
/// @cond SUPPRESS_TYPEDEF_WARNINGS

/**
* MDIO makes extensive use of the Tensorstore library.
* Ideally the user should never know that Tensorstore is being used under the
Expand Down Expand Up @@ -144,4 +149,6 @@ constexpr std::string_view kInertSliceKey =

} // namespace mdio

/// @endcond

#endif // MDIO_IMPL_H_
89 changes: 87 additions & 2 deletions mdio/stats.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,13 @@ namespace internal {
*/
class Histogram {
public:
/// @brief Destructor
virtual ~Histogram() = default;
/// @brief Retrieves the histogram as a JSON object
virtual nlohmann::json getHistogram() const = 0;
/// @brief Clones the histogram
virtual std::unique_ptr<const Histogram> clone() const = 0;
/// @brief Constructs a Histogram from a JSON object
virtual mdio::Result<std::unique_ptr<const Histogram>> FromJson(
const nlohmann::json& j) const = 0;
/**
Expand All @@ -93,6 +97,7 @@ class Histogram {
*/
virtual bool isBindable() const = 0;

/// @brief The key for the histogram in the JSON object
const std::string HIST_KEY = "histogram";

private:
Expand All @@ -105,16 +110,32 @@ class Histogram {
virtual bool isHist(const nlohmann::json& j) const = 0;
};

/**
* @brief A histogram with bin centers and counts
* @tparam T The type of the histogram (Default: float)
*/
template <typename T = float>
class CenteredBinHistogram : public Histogram {
public:
/**
* @brief Constructs a CenteredBinHistogram object
* @param binCenters The centers of the bins
* @param counts The counts of the bins
*/
CenteredBinHistogram(const std::vector<T>& binCenters,
const std::vector<int32_t>& counts)
: binCenters(binCenters), counts(counts) {
static_assert(std::is_same_v<T, float> || std::is_same_v<T, int32_t>,
"Histograms may only be float32 or int32_t.");
}

/**
* @brief Attempts to construct a new CenteredBinHistogram from a JSON
* representation
* @param j The JSON representation of the histogram
* @return A new CenteredBinHistogram if the input JSON is valid, otherwise an
* error
*/
mdio::Result<std::unique_ptr<const Histogram>> FromJson(
const nlohmann::json& j) const override {
if (isHist(j)) {
Expand All @@ -137,31 +158,57 @@ class CenteredBinHistogram : public Histogram {
HIST_KEY + ";");
}

/**
* @brief Returns the histogram as a JSON object
* @return The histogram as a JSON object
*/
nlohmann::json getHistogram() const override {
nlohmann::json histogram;
histogram[HIST_KEY]["binCenters"] = this->binCenters;
histogram[HIST_KEY]["counts"] = this->counts;
return histogram;
}

/**
* @brief Clones the histogram
* @return A unique pointer to a new histogram
*/
std::unique_ptr<const Histogram> clone() const override {
return std::make_unique<CenteredBinHistogram>(*this);
}

/**
* @brief Whether or not the histogram is JSON bindable
* @return True if the histogram is JSON bindable, false otherwise
*/
bool isBindable() const override { return true; }

private:
const std::vector<T> binCenters;
const std::vector<int32_t> counts;

/**
* @brief Whether or not the histogram is JSON bindable
* @return True if the histogram is JSON bindable, false otherwise
*/
bool isHist(const nlohmann::json& j) const override {
return j.contains(HIST_KEY);
}
};

/**
* @brief A histogram with bin edges and widths
* @tparam T The type of the histogram (Default: float)
*/
template <typename T = float>
class EdgeDefinedHistogram : public Histogram {
public:
/**
* @brief Constructs an EdgeDefinedHistogram object
* @param binEdges The edges of the bins
* @param binWidths The widths of the bins
* @param counts The counts of the bins
*/
EdgeDefinedHistogram(const std::vector<T>& binEdges,
const std::vector<T>& binWidths,
const std::vector<int32_t>& counts)
Expand Down Expand Up @@ -201,6 +248,10 @@ class EdgeDefinedHistogram : public Histogram {
"EdgeDefinedHistogram\n\tMissing parent key: 'histogram'");
}

/**
* @brief Returns the histogram as a JSON object
* @return The histogram as a JSON object
*/
nlohmann::json getHistogram() const override {
nlohmann::json histogram;
histogram[HIST_KEY]["binEdges"] = this->binEdges;
Expand All @@ -209,24 +260,44 @@ class EdgeDefinedHistogram : public Histogram {
return histogram;
}

/**
* @brief Clones the histogram
* @return A unique pointer to a new histogram
*/
std::unique_ptr<const Histogram> clone() const override {
return std::make_unique<EdgeDefinedHistogram>(*this);
}

/**
* @brief Whether or not the histogram is JSON bindable
* @return True if the histogram is JSON bindable, false otherwise
*/
bool isBindable() const override { return true; }

private:
const std::vector<T> binEdges;
const std::vector<T> binWidths;
const std::vector<int32_t> counts;

/**
* @brief Whether or not the histogram is JSON bindable
* @return True if the histogram is JSON bindable, false otherwise
*/
bool isHist(const nlohmann::json& j) const override {
return j.contains(HIST_KEY);
}
};

/**
* @brief A collection of summary statistics
* @tparam T The type of the histogram (Default: float)
*/
class SummaryStats {
public:
/**
* @brief Constructs a SummaryStats object
* @param other The SummaryStats object to copy from
*/
SummaryStats(const SummaryStats& other)
: count(other.count),
max(other.max),
Expand All @@ -235,6 +306,10 @@ class SummaryStats {
sumSquares(other.sumSquares),
histogram(other.histogram->clone()) {}

/**
* @brief Returns the statsV1 object as a JSON object
* @return The statsV1 object as a JSON object
*/
const nlohmann::json getBindable() const {
nlohmann::json stats = this->histogram->getHistogram();
stats["count"] = this->count;
Expand Down Expand Up @@ -335,6 +410,9 @@ class SummaryStats {

} // namespace internal

/**
* @brief A collection of user defined attributes
*/
class UserAttributes {
public:
/**
Expand All @@ -359,8 +437,8 @@ class UserAttributes {
* static member function `FromJson(nlohmann::json)`.
* @tparam T The type of the histogram (May either be flaot or int32_t)
* (Default: float)
* @param j The JSON representation of the dataset
* @param varible The name of the Variable which may contain the user
* @param dataset The JSON representation of the dataset
* @param variable The name of the Variable which may contain the user
* attributes
* @return A UserAttributes object if the variable is a Variable in the
* Dataset, otherwise an error
Expand All @@ -384,6 +462,13 @@ class UserAttributes {
" not found in Dataset");
}

/**
* @brief Constructs a UserAttributes object from the JSON representation of a
* Variable
* @param variable The JSON representation of the Variable
* @return A UserAttributes object if the Variable is valid, otherwise an
* error
*/
static mdio::Result<UserAttributes> FromVariableJson(
const nlohmann::json& variable) {
auto param = variable.contains("metadata") ? variable["metadata"]
Expand Down
Loading

0 comments on commit 5f12765

Please sign in to comment.