Utils Module

Functions for describing wind farm layouts and creating wind farm representations

farmnet.utils.date_to_str(t: datetime) → str

Convert a datetime object to a standardized string format.

Parameters:

t (datetime.datetime) – A datetime object to be converted.

Returns:

String representation in format “%Y-%m-%d %H:%M:%S”

Return type:

str

Example

>>> from datetime import datetime
>>> dt = datetime(2023, 5, 15, 14, 30, 0)
>>> date_to_str(dt)
'2023-05-15 14:30:00'

See also

datetime.datetime.strftime() For custom formatting options.

farmnet.utils.getenv(key: str, default: T = 0) → T

Get an environment variable and return it as the same type as default value.

Parameters:

• key (str) – Name of the environment variable

• default (T) – Default value if key doesn’t exist (determines return type)

Returns:

Environment variable value converted to default’s type

Return type:

T

Examples

>>> value = getenv("EXAMPLE", default=-1)
>>> value, type(value)
(-1, <class 'int'>)

>>> os.environ["EXAMPLE"] = "1"
>>> value = getenv("EXAMPLE", default="-1")
>>> value, type(value)
('1', <class 'str'>)

See also

os.getenv() The underlying environment variable access

farmnet.utils.load_data(filename: str | Path) → DataFrame | Series

Load a pandas DataFrame or Series from a pickle file.

Parameters:

filename (Union[str, Path]) – Path to the pickle file (without .pkl extension)

Returns:

The loaded DataFrame or Series

Return type:

Union[pd.DataFrame, pd.Series]

Raises:

FileNotFoundError – If the specified file doesn’t exist

Example

>>> import pandas as pd
>>> from pathlib import Path
>>> import os
>>> # Create and save test data
>>> test_df = pd.DataFrame({'A': [1, 2], 'B': ['x', 'y']})
>>> test_df.to_pickle("test_load.pkl")
>>> # Load and verify
>>> loaded = load_data("test_load")
>>> isinstance(loaded, pd.DataFrame)
True
>>> loaded.shape
(2, 2)
>>> # Clean up
>>> os.remove("test_load.pkl")

>>> loaded = load_data("test_load")
Traceback (most recent call last):
...
FileNotFoundError: [Errno 2] No such file or directory: 'test_load.pkl'

farmnet.utils.load_pickle(filename: str | Path) → Any

Load and deserialize a Python object from a pickle file.

Parameters:

filename (Union[str, Path]) – Path to the pickle file

Returns:

Deserialized Python object

Return type:

Any

Raises:

• FileNotFoundError – If the specified file does not exist

• pickle.UnpicklingError – If the file cannot be unpickled

• EOFError – If the file is empty or truncated

• ModuleNotFoundError – If required module is not available

Example

>>> test_data = {'Surname': 'Michael ', 'Name': 'Palin'}
>>> pickle_object(test_data, "test_dict")
>>> data = load_pickle("test_dict.pkl")
>>> isinstance(data, dict)
True
>>> data
{'Surname': 'Michael ', 'Name': 'Palin'}
>>> os.remove("test_dict.pkl")

>>> config = load_pickle("not_existing.pkl")
Traceback (most recent call last):
...
FileNotFoundError: [Errno 2] No such file or directory: 'not_existing.pkl'

See also

pickle.load() The underlying deserialization function pickle_object() The corresponding serialization function

farmnet.utils.pickle_object(obj: Any, filename: str | Path)

Save obj as a pickle file.

Parameters:

• obj (Any) – Object to be dumped into the pickle file

• filename (Union[str, Path]) – Path to the pickle file (without .pkl extension)

Example

>>> from pathlib import Path
>>> import os
>>> test_data = {'Surname': 'Michael', 'Name': 'Palin'}
>>> pickle_object(test_data, "test_dict")
>>> Path("test_dict.pkl").exists()
True
>>> data = load_pickle("test_dict.pkl")
>>> isinstance(data, dict)
True
>>> data == test_data
True
>>> os.remove("test_dict.pkl")

farmnet.utils.read_config(file_path: str | Path) → dict

Read and parse a TOML configuration file for wind turbine data processing.

This function loads a configuration file that defines the structure and metadata of wind turbine datasets, including CSV/Parquet file formats, column mappings, and dataset locations.

Parameters:

file_path (Union[str, Path]) – Path to the configuration file in TOML format. Can be either a string or pathlib.Path object.

Returns:

A dictionary containing the parsed configuration

Return type:

dict

Raises:

• FileNotFoundError – If the specified configuration file doesn’t exist.

• tomllib.TOMLDecodeError – If the TOML file is malformed.

Example Configuration Structure

{
    'csv': {
        'encoding': 'utf8',
        'sep': ',',
        'header': 0
    },
    'index': {
        'name-from-source': '# Date and time',
        'time-zone-from-source': 'UTC',
        'name': 'datetime',
        'unit': 'ns',
        'time-zone': 'UTC'
    },
    'columns': [
        {'name-from-source': 'Wind direction (°)', 'name': 'wind_direction'},
        # ... more column mappings
    ],
    'dataset': {
        'root_dir': 'kelmarsh_data_imputation',
        'data': 'featured_windeurope_data.parquet',
        'static': 'Kelmarsh_WT_static.csv'
    }
}

Example

Basic usage:

>>> import json
>>> default_cfg_path = Path(getenv("CONFIG_PATH", "examples/kelmarsh.toml"))
>>> config = read_config(default_cfg_path)
>>> print(json.dumps(config, indent=4, sort_keys=True, ensure_ascii=False))
{
    "columns": [
        {
            "name": "wind_direction",
            "name-from-source": "Wind direction (°)"
        },
        {
            "name": "nacelle_direction",
            "name-from-source": "Nacelle position (°)"
        },
        {
            "name": "wind_speed",
            "name-from-source": "Wind speed (m/s)"
        },
        {
            "name": "power",
            "name-from-source": "Power (kW)"
        },
        {
            "name": "wt_id",
            "name-from-source": "Wind turbine ID"
        }
    ],
    "csv": {
        "encoding": "utf8",
        "header": 0,
        "sep": ","
    },
    "dataset": {
        "data": "featured_windeurope_data.parquet",
        "root_dir": "kelmarsh_data_imputation",
        "static": "Kelmarsh_WT_static.csv"
    },
    "index": {
        "name": "datetime",
        "name-from-source": "# Date and time",
        "time-zone": "UTC",
        "time-zone-from-source": "UTC",
        "unit": "ns"
    }
}

>>> config = read_config("not_existing_config.toml")
Traceback (most recent call last):
...
FileNotFoundError: [Errno 2] No such file or directory: 'not_existing_config.toml'

See also

tomllib Python standard library module for TOML parsing.

farmnet.utils.save_data(df: DataFrame, filename: str | Path)

Save a pandas DataFrame or Series to a pickle file.

Parameters:

• df (Union[pd.DataFrame, pd.Series]) – DataFrame or Series to be saved

• filename (Union[str, Path]) – Output filename (without .pkl extension)

Example

>>> import pandas as pd
>>> from pathlib import Path
>>> import os
>>> # Create test data
>>> test_df = pd.DataFrame({'A': [1, 2], 'B': ['x', 'y']})
>>> # Save the data
>>> save_data(test_df, "test_dataframe")
>>> # Verify file exists
>>> Path("test_dataframe.pkl").exists()
True
>>> # Clean up
>>> os.remove("test_dataframe.pkl")