A multi-dimensional, tagged data frame. More...

#include <mdframe.hpp>

Collaboration diagram for ngen::mdframe:

Public Types
using	dimension = detail::dimension

using	dimension_set = std::unordered_set<dimension, dimension::hash>

using	variable = detail::variable<int, float, double>

using	variable_map = std::unordered_map<std::string, variable>

using	size_type = variable::size_type

using	types = variable::types
	The variable value types this frame can support.

using	mdarray_variant = variable::mdarray_variant

Public Member Functions
boost::optional< detail::dimension >	get_dimension (const std::string &name) const noexcept
	Return a dimension if it exists.

bool	has_dimension (const std::string &name) const noexcept
	Check if a dimension exists.

mdframe &	add_dimension (const std::string &name)
	Add a dimension with unlimited size to this mdframe.

mdframe &	add_dimension (const std::string &name, std::size_t size)
	Add a dimension with a specified size to this mdframe, or update an existing dimension.

variable &	get_variable (const std::string &name) noexcept
	Return reference to a mdarray representing a variable, if it exists.

variable &	operator[] (const std::string &name) noexcept
	Return reference to a mdarray representing a variable, if it exists.

bool	has_variable (const std::string &name) const noexcept
	Check if a variable exists.

template<typename T , types::enable_if_supports< T, bool > = true>
mdframe &	add_variable (const std::string &name, std::initializer_list< std::string > dimensions)
	Add a (vector) variable definition to this mdframe.

void	to_csv (const std::string &path, bool header=true) const
	Write this mdframe to a CSV file.

void	to_netcdf (const std::string &path) const
	Write this mdframe to a NetCDF file.

Private Member Functions
dimension_set::const_iterator	find_dimension (const std::string &name) const noexcept
	Get an iterator to a dimension, if it exists in the set.

variable_map::const_iterator	find_variable (const std::string &name) const noexcept
	Get an iterator to a variable, if it exists in the set.

Private Attributes
dimension_set	m_dimensions

variable_map	m_variables

Detailed Description

A multi-dimensional, tagged data frame.

This structure (somewhat) mimics the conceptual format of NetCDF. In particular, we can think of an mdframe as a multimap between dimension tuples to multi-dimensional arrays. In other words, it is similar to an R data.frame or pandas dataframe where the column types are multi-dimensional arrays.

Heterogenous data types are handled via boost::variant types over mdarray types.

Frame Representation

Consider the dimensions: x, y, z; and the variables:

v1<float>(x)
v2<double>(x, y)
v3<int>(x, y, z)

Then, it follows that the corresponding mdframe (spanned over x):

x	v1	v2	v3
0	f_0	[...]_0	[[...]]_0
1	f_1	[...]_1	[[...]]_1
...	...	...	...
n	f_n	[...]_n	[[...]]_n

where:

v1: Vector of floats, rank 1 -> [...]
v2: Matrix of doubles, rank 2 -> [[...]]
v3: Tensor of integers, rank 3 -> [[[...]]]

Alternatively, we can project down to a 2D representation by unpacking the dimensions, such that:

 dimensions ||                variables

=============== || ========================

x	y	z		v1	v2	v3
n	m	p		s[n]	d[n,m]	i[n,m,p]

Member Typedef Documentation

◆ dimension

using ngen::mdframe::dimension = detail::dimension

◆ dimension_set

using ngen::mdframe::dimension_set = std::unordered_set<dimension, dimension::hash>

◆ mdarray_variant

using ngen::mdframe::mdarray_variant = variable::mdarray_variant

◆ size_type

using ngen::mdframe::size_type = variable::size_type

◆ types

using ngen::mdframe::types = variable::types

The variable value types this frame can support.

These are stored as a compile-time type list to derive further type aliases.

See also: detail::variable

◆ variable

using ngen::mdframe::variable = detail::variable<int, float, double>

◆ variable_map

using ngen::mdframe::variable_map = std::unordered_map<std::string, variable>

Member Function Documentation

◆ add_dimension() [1/2]

mdframe & ngen::mdframe::add_dimension ( const std::string & name )

inline

Add a dimension with unlimited size to this mdframe.

Parameters

name	Name of the dimension.

Returns: mdframe&

References m_dimensions.

◆ add_dimension() [2/2]

mdframe & ngen::mdframe::add_dimension	(	const std::string &	name,
		std::size_t	size )

inline

Add a dimension with a specified size to this mdframe, or update an existing dimension.

Parameters

name	Name of the dimension.
size	Size of the dimension.

Returns: mdframe&

References m_dimensions.

◆ add_variable()

template<typename T , types::enable_if_supports< T, bool > = true>

mdframe & ngen::mdframe::add_variable	(	const std::string &	name,
		std::initializer_list< std::string >	dimensions )

inline

Add a (vector) variable definition to this mdframe.

Note: This member function is constrained by {Args} being constructible to a std::initializer_list of std::string (i.e. a list of std::string).

Template Parameters

Arg	list of std::string representing dimension names.

Parameters

name	Name of the variable.
dimensions	Names of the dimensions this variable spans.

Returns: mdframe&

References get_dimension(), m_variables, and ngen::detail::variable< SupportedTypes >::make().

◆ find_dimension()

dimension_set::const_iterator ngen::mdframe::find_dimension ( const std::string & name ) const

inlineprivatenoexcept

Get an iterator to a dimension, if it exists in the set.

Parameters

name	Name of the dimension

Returns: dimension_set::const_iterator or dimension_set::end() if not found

References m_dimensions.

Referenced by get_dimension(), and has_dimension().

◆ find_variable()

variable_map::const_iterator ngen::mdframe::find_variable ( const std::string & name ) const

inlineprivatenoexcept

Get an iterator to a variable, if it exists in the set.

Parameters

name	Name of the variable

Returns: variable_set::const_iterator or variable_set::end() if not found

References m_variables.

Referenced by has_variable().

◆ get_dimension()

boost::optional< detail::dimension > ngen::mdframe::get_dimension ( const std::string & name ) const

inlinenoexcept

Return a dimension if it exists.

Otherwise, returns boost::none.

Parameters

name	Name of the dimension

Returns: boost::optional<detail::dimension>

References find_dimension(), and m_dimensions.

Referenced by add_variable().

◆ get_variable()

variable & ngen::mdframe::get_variable ( const std::string & name )

inlinenoexcept

Return reference to a mdarray representing a variable, if it exists.

Otherwise, returns boost::none.

Parameters

name	Name of the variable.

Returns: boost::optional<variable>

References m_variables.

Referenced by operator[]().

◆ has_dimension()

bool ngen::mdframe::has_dimension ( const std::string & name ) const

inlinenoexcept

Check if a dimension exists.

Parameters

name	Name of the dimension

Returns: true if the dimension exists in this mdframe.; false if the dimension does not exist in this mdframe.

References find_dimension(), and m_dimensions.

◆ has_variable()

bool ngen::mdframe::has_variable ( const std::string & name ) const

inlinenoexcept

Check if a variable exists.

Parameters

name	Name of the variable.

Returns: true if the variable exists in this mdframe.; false if the variables does not exist in this mdframe.

References find_variable(), and m_variables.

◆ operator[]()

variable & ngen::mdframe::operator[] ( const std::string & name )

inlinenoexcept

Return reference to a mdarray representing a variable, if it exists.

Otherwise, returns boost::none.

Parameters

name	Name of the variable.

Returns: boost::optional<variable>

References get_variable().

◆ to_csv()

void ngen::mdframe::to_csv	(	const std::string &	path,
		bool	header = true ) const

Write this mdframe to a CSV file.

The outputted CSV is a projected (or normalized) table spanning all possible dimensions, similar to the description of tidy data by Hadley Wickham (2014): https://www.jstatsoft.org/article/view/v059i10

Note: The dimensions are not outputted to the CSV, since they only form the basis for the mdframe's dimensions, and do not inherently store any information.

Parameters

path	File path to output CSV
basis	Dimension to span CSV over, defaults to "time"
header	Should the CSV header be included?

References ngen::cartesian_indices(), m_dimensions, and m_variables.

◆ to_netcdf()

void ngen::mdframe::to_netcdf ( const std::string & path ) const

Write this mdframe to a NetCDF file.

Parameters

path	File path to the output NetCDF

Member Data Documentation

◆ m_dimensions

dimension_set ngen::mdframe::m_dimensions

private

Referenced by add_dimension(), add_dimension(), find_dimension(), get_dimension(), has_dimension(), and to_csv().

◆ m_variables

variable_map ngen::mdframe::m_variables

private

Referenced by add_variable(), find_variable(), get_variable(), has_variable(), and to_csv().

The documentation for this class was generated from the following files:

include/utilities/mdframe/mdframe.hpp
src/utilities/mdframe/handler_csv.cpp
src/utilities/mdframe/handler_netcdf.cpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Frame Representation

Member Typedef Documentation

◆ dimension

◆ dimension_set

◆ mdarray_variant

◆ size_type

◆ types

◆ variable

◆ variable_map

Member Function Documentation

◆ add_dimension() [1/2]

◆ add_dimension() [2/2]

◆ add_variable()

◆ find_dimension()

◆ find_variable()

◆ get_dimension()

◆ get_variable()

◆ has_dimension()

◆ has_variable()

◆ operator[]()

◆ to_csv()

◆ to_netcdf()

Member Data Documentation

◆ m_dimensions

◆ m_variables