gemseo / core

dataset module

A generic dataset to store data in memory.

This module implements the concept of dataset which is a key element for machine learning, post-processing, data analysis, …

A Dataset uses its attribute Dataset.data to store \(N\) series of data representing the values of \(p\) multidimensional features belonging to different groups of features.

This attribute Dataset.data is a dictionary of 2D numpy arrays, whose rows are the samples, a.k.a. series, realizations or entries, and columns are the variables, a.k.a. parameters or features. The keys of this dictionary are either the names of the groups of variables or the names of the variables. Thus, a Dataset is not only defined by the raw data stored but also by the names, the sizes and the groups of the different variables.

A Dataset can be set either from a file (Dataset.set_from_file()) or from a numpy arrays (Dataset.set_from_array()), and can be enriched from a group of variables (Dataset.add_group()) or from a single variable (Dataset.add_variable()).

An AbstractFullCache or an OptimizationProblem can also be exported to a Dataset using AbstractFullCache.export_to_dataset() and OptimizationProblem.export_to_dataset() respectively.

From a Dataset, we can easily access its length and data, either as 2D array or as dictionaries indexed by the variables names. We can get either the whole data, or the data associated to a group or the data associated to a list of variables. It is also possible to export the Dataset to an AbstractFullCache or a pandas DataFrame.

Classes:

Dataset([name, by_group])

A generic class to store data.

class gemseo.core.dataset.Dataset(name=None, by_group=True)

Bases: object

A generic class to store data.

name

The name of the dataset.

Type

str

sizes

The sizes of the variables.

Type

Dict[str,int]

dimension

The dimensions of the groups of variables.

Type

Dict[str,int]

length

The length of the dataset.

Type

int

strings_encoding

The encoding structure, mapping the values of the string variables with integers; the keys are the names of the variables and the values are dictionaries whose keys are the components of the variables and the values are the integer values.

Type

Dict

metadata

The metadata used to store any kind of information that are not variables, e.g. the mesh associated with a multi-dimensional variable.

Type

Dict[str,Any]

Parameters

• name (Optional[str]) –

  The name of the dataset. If None, use the name of the class.

  By default it is set to None.

• by_group (bool) –

  If True, store the data by group. Otherwise, store them by variables.

  By default it is set to True.

Return type

None

Attributes:

DEFAULT_GROUP
DEFAULT_NAMES
DESIGN_GROUP
FUNCTION_GROUP
GRADIENT_GROUP
HDF5_CACHE
INPUT_GROUP
MEMORY_FULL_CACHE
OUTPUT_GROUP
PARAMETER_GROUP
columns_names	The names of the columns of the dataset.
groups	The sorted names of the groups of variables.
n_samples	The number of samples.
n_variables	The number of variables.
row_names	The names of the rows.
variables	The sorted names of the variables.

Methods:

add_group(group, data[, variables, sizes, ...])	Add data related to a group.
add_variable(name, data[, group, cache_as_input])	Add data related to a variable.
compare(value_1, logical_operator, value_2)	Compare either a variable and a value or a variable and another variable.
export_to_cache([inputs, outputs, ...])	Export the dataset to a cache.
export_to_dataframe([copy])	Export the dataset to a pandas Dataframe.
find(comparison)	Find the entries for which a comparison is satisfied.
get_all_data([by_group, as_dict])	Get all the data stored in the dataset.
get_available_plots()	Return the available plot methods.
get_data_by_group(group[, as_dict])	Get the data for a specific group name.
get_data_by_names(names[, as_dict])	Get the data for specific names of variables.
get_group(variable_name)	Get the name of the group that contains a variable.
get_names(group_name)	Get the names of the variables of a group.
get_normalized_dataset([excluded_variables, ...])	Get a normalized copy of the dataset.
is_empty()	Check if the dataset is empty.
is_group(name)	Check if a name is a group name.
is_nan()	Check if an entry contains NaN.
is_variable(name)	Check if a name is a variable name.
n_variables_by_group(group)	The number of variables for a group.
plot(name[, show, save])	Plot the dataset from a DatasetPlot.
remove(entries)	Remove entries.
set_from_array(data[, variables, sizes, ...])	Set the dataset from an array.
set_from_file(filename[, variables, sizes, ...])	Set the dataset from a file.
set_metadata(name, value)	Set a metadata attribute.

DEFAULT_GROUP = 'parameters'

DEFAULT_NAMES = {'design_parameters': 'dp', 'functions': 'func', 'inputs': 'in', 'outputs': 'out', 'parameters': 'x'}

DESIGN_GROUP = 'design_parameters'

FUNCTION_GROUP = 'functions'

GRADIENT_GROUP = 'gradients'

HDF5_CACHE = 'HDF5Cache'

INPUT_GROUP = 'inputs'

MEMORY_FULL_CACHE = 'MemoryFullCache'

OUTPUT_GROUP = 'outputs'

PARAMETER_GROUP = 'parameters'

add_group(group, data, variables=None, sizes=None, pattern=None, cache_as_input=True)

Add data related to a group.

Parameters

• group (str) – The name of the group of data to be added.

• data (numpy.ndarray) – The data to be added.

• variables (Optional[List[str]]) –

  The names of the variables. If None, use default names based on a pattern.

  By default it is set to None.

• sizes (Optional[Dict[str, int]]) –

  The sizes of the variables. If None, assume that all the variables have a size equal to 1.

  By default it is set to None.

• pattern (Optional[str]) –

  The name of the variable to be used as a pattern when variables is None. If None, use the Dataset.DEFAULT_NAMES for this group if it exists. Otherwise, use the group name.

  By default it is set to None.

• cache_as_input (bool) –

  If True, cache these data as inputs when the cache is exported to a cache.

  By default it is set to True.

Return type

str

add_variable(name, data, group='parameters', cache_as_input=True)

Add data related to a variable.

Parameters

• name (str) – The name of the variable to be stored.

• data (numpy.ndarray) – The data to be stored.

• group (str) –

  The name of the group related to this variable.

  By default it is set to parameters.

• cache_as_input (bool) –

  If True, cache these data as inputs when the cache is exported to a cache.

  By default it is set to True.

Return type

None

property columns_names

The names of the columns of the dataset.

compare(value_1, logical_operator, value_2, component_1=0, component_2=0)

Compare either a variable and a value or a variable and another variable.

Parameters

• value_1 (Union[str, float]) – The first value, either a variable name or a numeric value.

• logical_operator (str) – The logical operator, either “==”, “<”, “<=”, “>” or “>=”.

• value_2 (Union[str, float]) – The second value, either a variable name or a numeric value.

• component_1 (int) –

  If value_1 is a variable name, component_1 corresponds to its component used in the comparison.

  By default it is set to 0.

• component_2 (int) –

  If value_2 is a variable name, component_2 corresponds to its component used in the comparison.

  By default it is set to 0.

Returns

Whether the comparison is valid for the different entries.

Return type

numpy.ndarray

export_to_cache(inputs=None, outputs=None, cache_type='MemoryFullCache', cache_hdf_file=None, cache_hdf_node_name=None, **options)

Export the dataset to a cache.

Parameters

• inputs (Optional[Iterable[str]]) –

  The names of the inputs to cache. If None, use all inputs.

  By default it is set to None.

• outputs (Optional[Iterable[str]]) –

  The names of the outputs to cache. If None, use all outputs.

  By default it is set to None.

• cache_type (str) –

  The type of cache to use.

  By default it is set to MemoryFullCache.

• cache_hdf_file (Optional[str]) –

  The name of the HDF file to store the data. Required if the type of the cache is ‘HDF5Cache’.

  By default it is set to None.

• cache_hdf_node_name (Optional[str]) –

  The name of the HDF node to store the discipline. If None, use the name of the dataset.

  By default it is set to None.

Returns

A cache containing the dataset.

Return type

gemseo.core.cache.AbstractFullCache

export_to_dataframe(copy=True)

Export the dataset to a pandas Dataframe.

Parameters

copy (bool) –

If True, copy data. Otherwise, use reference.

By default it is set to True.

Returns

A pandas DataFrame containing the dataset.

Return type

DataFrame

static find(comparison)

Find the entries for which a comparison is satisfied.

This search uses a boolean 1D array whose length is equal to the length of the dataset.

Parameters

comparison (numpy.ndarray) – A boolean vector whose length is equal to the number of samples.

Returns

The indices of the entries for which the comparison is satisfied.

Return type

List[int]

get_all_data(by_group=True, as_dict=False)

Get all the data stored in the dataset.

The data can be returned either as a dictionary indexed by the names of the variables, or as an array concatenating them, accompanied with the names and sizes of the variables.

The data can also classified by groups of variables.

Parameters

• by_group –

  If True, sort the data by group.

  By default it is set to True.

• as_dict –

  If True, return the data as a dictionary.

  By default it is set to False.

Returns

All the data stored in the dataset.

Return type

Union[Dict[str, Union[Dict[str, numpy.ndarray], numpy.ndarray]], Tuple[Union[numpy.ndarray, Dict[str, numpy.ndarray]], List[str], Dict[str, int]]]

get_available_plots()

Return the available plot methods.

Return type

List[str]

get_data_by_group(group, as_dict=False)

Get the data for a specific group name.

Parameters

• group (str) – The name of the group.

• as_dict (bool) –

  If True, return values as dictionary.

  By default it is set to False.

Returns

The data related to the group.

Return type

Union[numpy.ndarray, Dict[str, numpy.ndarray]]

get_data_by_names(names, as_dict=True)

Get the data for specific names of variables.

Parameters

• names (Union[str, Iterable[str]]) – The names of the variables.

• as_dict (bool) –

  If True, return values as dictionary.

  By default it is set to True.

Returns

The data related to the variables.

Return type

Union[numpy.ndarray, Dict[str, numpy.ndarray]]

get_group(variable_name)

Get the name of the group that contains a variable.

Parameters

variable_name (str) – The name of the variable.

Returns

The group to which the variable belongs.

Return type

str

get_names(group_name)

Get the names of the variables of a group.

Parameters

group_name (str) – The name of the group.

Returns

The names of the variables of the group.

Return type

List[str]

get_normalized_dataset(excluded_variables=None, excluded_groups=None)

Get a normalized copy of the dataset.

Parameters

• excluded_variables (Optional[Sequence[str]]) –

  The names of the variables not to be normalized. If None, normalize all the variables.

  By default it is set to None.

• excluded_groups (Optional[Sequence[str]]) –

  The names of the groups not to be normalized. If None, normalize all the groups.

  By default it is set to None.

Returns

A normalized dataset.

Return type

gemseo.core.dataset.Dataset

property groups

The sorted names of the groups of variables.

is_empty()

Check if the dataset is empty.

Returns

Whether the dataset is empty.

Return type

bool

is_group(name)

Check if a name is a group name.

Parameters

name (str) – A name of a group.

Returns

Whether the name is a group name.

Return type

bool

is_nan()

Check if an entry contains NaN.

Returns

Whether any entries is NaN or not.

Return type

numpy.ndarray

is_variable(name)

Check if a name is a variable name.

Parameters

name (str) – A name of a variable.

Returns

Whether the name is a variable name.

Return type

bool

property n_samples

The number of samples.

property n_variables

The number of variables.

n_variables_by_group(group)

The number of variables for a group.

Parameters

group (str) – The name of a group.

Returns

The group dimension.

Return type

int

plot(name, show=True, save=False, **options)

Plot the dataset from a DatasetPlot.

See Dataset.get_available_plots()

Parameters

• name (str) – The name of the post-processing, which is the name of a class inheriting from DatasetPlot.

• show (bool) –

  If True, display the figure.

  By default it is set to True.

• save (bool) –

  If True, save the figure.

  By default it is set to False.

• options – The options for the post-processing.

Return type

None

remove(entries)

Remove entries.

Parameters

entries (Union[List[int], numpy.ndarray]) – The entries to be removed, either indices or a boolean 1D array whose length is equal to the length of the dataset and elements to delete are coded True.

Return type

None

property row_names

The names of the rows.

set_from_array(data, variables=None, sizes=None, groups=None, default_name=None)

Set the dataset from an array.

Parameters

• data (numpy.ndarray) – The data to be stored.

• variables (Optional[List[str]]) –

  The names of the variables. If None, use one default name per column of the array based on the pattern ‘default_name’.

  By default it is set to None.

• sizes (Optional[Dict[str, int]]) –

  The sizes of the variables. If None, assume that all the variables have a size equal to 1.

  By default it is set to None.

• groups (Optional[Dict[str, str]]) –

  The groups of the variables. If None, use Dataset.DEFAULT_GROUP for all the variables.

  By default it is set to None.

• default_name (Optional[str]) –

  The name of the variable to be used as a pattern when variables is None. If None, use the Dataset.DEFAULT_NAMES for this group if it exists. Otherwise, use the group name.

  By default it is set to None.

Return type

None

set_from_file(filename, variables=None, sizes=None, groups=None, delimiter=',', header=True)

Set the dataset from a file.

Parameters

• filename (str) – The name of the file containing the data.

• variables (Optional[List[str]]) –

  The names of the variables. If None and header is True, read the names from the first line of the file. If None and header is False, use default names based on the patterns the Dataset.DEFAULT_NAMES associated with the different groups.

  By default it is set to None.

• sizes (Optional[Dict[str, int]]) –

  The sizes of the variables. If None, assume that all the variables have a size equal to 1.

  By default it is set to None.

• groups (Optional[Dict[str, str]]) –

  The groups of the variables. If None, use Dataset.DEFAULT_GROUP for all the variables.

  By default it is set to None.

• delimiter (str) –

  The field delimiter.

  By default it is set to ,.

• header (bool) –

  If True, read the names of the variables on the first line of the file.

  By default it is set to True.

Return type

None

set_metadata(name, value)

Set a metadata attribute.

Parameters

• name (str) – The name of the metadata attribute.

• value (Any) – The value of the metadata attribute.

Return type

None

property variables

The sorted names of the variables.