Nurse rostering (cpmpy.tools.io.nurserostering)

Helper functions for the Nurse Rostering format.

The Nurse Rostering format is a textual format to represent Nurse Rostering problems. More can be read about it here:

List of functions

load_nurserostering

Loader for Nurse Rostering format.

parse_scheduling_period

Parse a nurserostering instance file.

add_fake_names

Transform function to add randomly generated names to staff using Faker.

to_dataframes

Transform function to convert native data structures to Pandas DataFrames.
cpmpy.tools.io.nurserostering.add_fake_names(data: dict[str, Any], seed: int = 0) → dict[str, Any][source]

Transform function to add randomly generated names to staff using Faker.

Parameters:

  • data (dict[str, Any]) – Dictionary returned by parse_scheduling_period()

  • seed (int) – Random seed for reproducible name generation (default: 0)

Returns:

Dictionary with ‘name’ field added to each staff member

Return type:

dict[str, Any]

Raises:

ImportError – If Faker is not installed

cpmpy.tools.io.nurserostering.load_nurserostering(instance: str | PathLike | TextIO, open: Callable = <built-in function open>) → Model[source]

Loader for Nurse Rostering format. Loads an instance and returns its matching CPMpy model.

Parameters:

  • instance (str or os.PathLike or TextIO) –

    • A file path to a Nurse Rostering file

    • OR a string containing the Nurse Rostering content directly

    • OR a TextIO object already open for reading

  • open (Callable) – If instance is the path to a file, a callable to “open” that file (default=python standard library’s ‘open’).

Returns:

The CPMpy model of the Nurse Rostering instance.

Return type:

cp.Model

cpmpy.tools.io.nurserostering.parse_scheduling_period(instance: str | PathLike | TextIO, open: Callable = <built-in function open>)[source]

Parse a nurserostering instance file.

Parameters:

instance (str or os.PathLike or TextIO) – Path, raw instance text, or a TextIO object.

Returns:

A dictionary with native Python data structures (lists of dicts).

Return type:

dict

Raises:

ValueError – If the file is not found.

Note

  • Use to_dataframes() transform to convert to pandas DataFrames if needed.

  • Use add_fake_names() transform to add randomly generated names to staff.

cpmpy.tools.io.nurserostering.to_dataframes(data: dict[str, Any]) → dict[str, Any][source]

Transform function to convert native data structures to Pandas DataFrames.

Parameters:

data (dict[str, Any]) – Dictionary returned by parse_scheduling_period()

Returns:

Dictionary with pandas DataFrames instead of native structures

Return type:

dict[str, Any]

Raises:

ImportError – If pandas is not installed