Project

class glotaran.project.project.Project(file: Path, folder: Path | None = None)[source]

Bases: object

A project represents a projectfolder on disk which contains a project file.

A project file is a file in yml format with name project.gta

Attributes Summary

`data`	Get all project datasets.
`folder`
`has_data`	Check if the project has datasets.
`has_models`	Check if the project has models.
`has_parameters`	Check if the project has parameters.
`has_results`	Check if the project has results.
`models`	Get all project models.
`parameters`	Get all project parameters.
`results`	Get all project results.
`version`
`file`

Methods Summary

`create`	Create a new project folder and file.
`create_scheme`	Create a scheme for optimization.
`generate_model`	Generate a model.
`generate_parameters`	Generate parameters for a model.
`get_latest_result_path`	Get the path to a result with name `name`.
`get_models_directory`	Get the path to the model directory of the project.
`get_parameters_directory`	Get the path to the parameter directory of the project.
`get_result_path`	Get the path to a result with name `name`.
`import_data`	Import a dataset by saving it as an .nc file in the project's data folder.
`load_data`	Load a dataset, with SVD data if `add_svd` is `True`.
`load_latest_result`	Load a result.
`load_model`	Load a model.
`load_parameters`	Load parameters.
`load_result`	Load a result.
`markdown`	Format the project as a markdown text.
`open`	Open a new project.
`optimize`	Optimize a model.
`show_model_definition`	Show model definition file content with syntax highlighting.
`show_parameters_definition`	Show parameters definition file content with syntax highlighting.
`validate`	Check that the model is valid, list all issues in the model if there are any.

Methods Documentation

static create(folder: str | Path, allow_overwrite: bool = False) → Project[source]

Create a new project folder and file.

Parameters:

folder (str | Path | None) – The folder where the project will be created. If None, the current work directory will be used.
allow_overwrite (bool) – Whether to overwrite an existing project file.

Returns:

The created project.

Return type:

Project

Raises:

FileExistsError – Raised if the project file already exists and allow_overwrite=False.

create_scheme(model_name: str, parameters_name: str, maximum_number_function_evaluations: int | None = None, clp_link_tolerance: float = 0.0, data_lookup_override: Mapping[str, LoadableDataset] | None = None) → Scheme[source]

Create a scheme for optimization.

Parameters:

model_name (str) – The model to optimize.
parameters_name (str) – The initial parameters.
maximum_number_function_evaluations (int | None) – The maximum number of function evaluations.
clp_link_tolerance (float) – The CLP link tolerance.
data_lookup_override (Mapping[str, LoadableDataset] | None) – Allows to bypass the default dataset lookup in the project data folder and use a different dataset for the optimization without changing the model. This is especially useful when working with preprocessed data. Defaults to None.

Returns:

The created scheme.

Return type:

Scheme

property data: Mapping[str, Path]

Get all project datasets.

Returns:: The models of the datasets.
Return type:: Mapping[str, Path]

file: Path

folder: Path = None

generate_model(model_name: str, generator_name: str, generator_arguments: dict[str, Any], *, allow_overwrite: bool = False, ignore_existing: bool = False)[source]

Generate a model.

Parameters:

model_name (str) – The name of the model.
generator_name (str) – The generator for the model.
generator_arguments (dict[str, Any]) – Arguments for the generator.
allow_overwrite (bool) – Whether to overwrite an existing model.
ignore_existing (bool) – Whether to ignore generation of a model file if it already exists.

generate_parameters(model_name: str, parameters_name: str | None = None, *, format_name: Literal['yml', 'yaml', 'csv'] = 'csv', allow_overwrite: bool = False, ignore_existing: bool = False)[source]

Generate parameters for a model.

Parameters:

model_name (str) – The model.
parameters_name (str | None) – The name of the parameters. If None it will be <model_name>_parameters.
format_name (Literal["yml", "yaml", "csv"]) – The parameter format.
allow_overwrite (bool) – Whether to overwrite existing parameters.
ignore_existing (bool) – Whether to ignore generation of a parameter file if it already exists.

get_latest_result_path(result_name: str) → Path[source]

Get the path to a result with name name.

Parameters:: result_name (str) – The name of the result.
Returns:: The path to the result.
Return type:: Path
Raises:: ValueError – Raised if result does not exist.

get_models_directory() → Path[source]

Get the path to the model directory of the project.

Returns:: The path to the project’s model directory.
Return type:: Path

get_parameters_directory() → Path[source]

Get the path to the parameter directory of the project.

Returns:: The path to the project’s parameter directory.
Return type:: Path

get_result_path(result_name: str, *, latest: bool = False) → Path[source]

Get the path to a result with name name.

Parameters:

result_name (str) – The name of the result.
latest (bool) – Flag to deactivate warning about using latest result. Defaults to False

Returns:

The path to the result.

Return type:

Path

Raises:

ValueError – Raised if result does not exist.

property has_data: bool

Check if the project has datasets.

Returns:: Whether the project has datasets.
Return type:: bool

property has_models: bool

Check if the project has models.

Returns:: Whether the project has models.
Return type:: bool

property has_parameters: bool

Check if the project has parameters.

Returns:: Whether the project has parameters.
Return type:: bool

property has_results: bool

Check if the project has results.

Returns:: Whether the project has results.
Return type:: bool

import_data(dataset: LoadableDataset | Mapping[str, LoadableDataset], dataset_name: str | None = None, allow_overwrite: bool = False, ignore_existing: bool = True)[source]

Import a dataset by saving it as an .nc file in the project’s data folder.

Parameters:

dataset (LoadableDataset) – Dataset instance or path to a dataset.
dataset_name (str | None) – The name of the dataset (needs to be provided when dataset is an xarray instance). Defaults to None.
allow_overwrite (bool) – Whether to overwrite an existing dataset.
ignore_existing (bool) – Whether to skip import if the dataset already exists and allow_overwrite is False. Defaults to True.

load_data(dataset_name: str, *, add_svd: bool = False, lsv_dim: Hashable = 'time', rsv_dim: Hashable = 'spectral') → xr.Dataset[source]

Load a dataset, with SVD data if add_svd is True.

Parameters:

dataset_name (str) – The name of the dataset.
add_svd (bool) – Whether or not to calculate and add SVD data. Defaults to False.
lsv_dim (Hashable) – Dimension of the left singular vectors. Defaults to “time”.
rsv_dim (Hashable) – Dimension of the right singular vectors. Defaults to “spectral”,

Returns:

The loaded dataset, with SVD data if add_svd is True.

Return type:

xr.Dataset

Raises:

ValueError – Raised if the dataset does not exist.

load_latest_result(result_name: str) → Result[source]

Load a result.

Parameters:: result_name (str) – The name of the result.
Returns:: The loaded result.
Return type:: Result
Raises:: ValueError – Raised if result does not exist.

load_model(model_name: str) → Model[source]

Load a model.

Parameters:: model_name (str) – The name of the model.
Returns:: The loaded model.
Return type:: Model
Raises:: ValueError – Raised if the model does not exist.

load_parameters(parameters_name: str) → Parameters[source]

Load parameters.

Parameters:: parameters_name (str) – The name of the parameters.
Raises:: ValueError – Raised if parameters do not exist.
Returns:: The loaded parameters.
Return type:: Parameters

load_result(result_name: str, *, latest: bool = False) → Result[source]

Load a result.

Parameters:

result_name (str) – The name of the result.
latest (bool) – Flag to deactivate warning about using latest result. Defaults to False

Returns:

The loaded result.

Return type:

Result

Raises:

ValueError – Raised if result does not exist.

markdown() → MarkdownStr[source]

Format the project as a markdown text.

Returns:: MarkdownStr – The markdown string.
Return type:: str

property models: Mapping[str, Path]

Get all project models.

Returns:: The models of the project.
Return type:: Mapping[str, Path]

classmethod open(project_folder_or_file: str | Path, create_if_not_exist: bool = True) → Project[source]

Open a new project.

Parameters:

project_folder_or_file (str | Path) – The path to a project folder or file.
create_if_not_exist (bool) – Create the project if not existent.

Returns:

The project instance.

Return type:

Project

Raises:

FileNotFoundError – Raised when the project file does not not exist and create_if_not_exist is False.

optimize(model_name: str, parameters_name: str, result_name: str | None = None, maximum_number_function_evaluations: int | None = None, clp_link_tolerance: float = 0.0, data_lookup_override: Mapping[str, LoadableDataset] | None = None) → Result[source]

Optimize a model.

Parameters:

model_name (str) – The model to optimize.
parameters_name (str) – The initial parameters.
result_name (str | None) – The name of the result.
maximum_number_function_evaluations (int | None) – The maximum number of function evaluations.
clp_link_tolerance (float) – The CLP link tolerance.
data_lookup_override (Mapping[str, LoadableDataset] | None) – Allows to bypass the default dataset lookup in the project data folder and use a different dataset for the optimization without changing the model. This is especially useful when working with preprocessed data. Defaults to None.

Returns:

Result of the optimization.

Return type:

Result

property parameters: Mapping[str, Path]

Get all project parameters.

Returns:: The parameters of the project.
Return type:: Mapping[str, Path]

property results: Mapping[str, Path]

Get all project results.

Returns:: The results of the project.
Return type:: Mapping[str, Path]

show_model_definition(model_name: str, syntax: str | None = None) → MarkdownStr[source]

Show model definition file content with syntax highlighting.

Parameters:

model_name (str) – The name of the model.
syntax (str | None) – Syntax used for syntax highlighting. Defaults to None which means that the syntax is inferred based on the file extension. Pass the value "" to deactivate syntax highlighting.

Returns:

Model definition file content with syntax highlighting to render in ipython.

Return type:

MarkdownStr

show_parameters_definition(parameters_name: str, syntax: str | None = None, *, as_dataframe: bool | None = None) → MarkdownStr | DataFrame[source]

Show parameters definition file content with syntax highlighting.

Parameters:

parameters_name (str) – The name of the parameters.
syntax (str | None) – Syntax used for syntax highlighting. Defaults to None which means that the syntax is inferred based on the file extension. Pass the value "" to deactivate syntax highlighting.
as_dataframe (bool | None) – Whether or not to show the Parameters definition as pandas.DataFrame (mostly useful for non string formats). Defaults to None which means that it will be inferred to True for known non string formats like xlsx.

Returns:

Parameters definition file content with syntax highlighting to render in ipython.

Return type:

MarkdownStr | pd.DataFrame

validate(model_name: str, parameters_name: str | None = None) → MarkdownStr[source]

Check that the model is valid, list all issues in the model if there are any.

If parameters_name also consider the Parameters when validating.

Parameters:

model_name (str) – The name of the model to validate.
parameters_name (str | None) – The name of the parameters to use when validating. Defaults to None which means that parameters are not considered when validating the model.

Returns:

Text indicating if the model is valid or not.

Return type:

MarkdownStr

version: str