ebm 0.99.5__py3-none-any.whl

ebm/cmd/initialize.py

@@ -0,0 +1,167 @@
+"""Module for setting up input, output and managing default data"""
+import argparse
+import os
+import pathlib
+import shutil
+import typing
+
+from loguru import logger
+
+from ebm.model.file_handler import FileHandler
+from ebm.__version__ import version
+DEFAULT_INPUT = pathlib.Path(f'X:\\NAS\\Data\\ebm\\default-input-{".".join(version.split(".")[:2])}\\')
+
+
+def create_input(file_handler: FileHandler,
+                 source_directory: typing.Optional[pathlib.Path]=None) -> bool:
+    """
+    Create any input file missing in file_handler.input_directory using the default data source.
+
+    Parameters
+    ----------
+    source_directory :
+    file_handler : FileHandler
+
+    Returns
+    -------
+    bool
+    """
+
+    source = file_handler.default_data_directory()
+
+    if source_directory:
+        if not source_directory.is_dir():
+            raise NotADirectoryError(f'{source_directory} is not a directory')
+
+        source_fh = FileHandler(directory=source_directory)
+        missing_files = source_fh.check_for_missing_files()
+        if len(missing_files) > 0:
+            msg = f'File not found {missing_files[0]}'
+            raise FileNotFoundError(msg)
+        source = source_directory
+
+    file_handler.create_missing_input_files(source_directory=source)
+
+    return True
+
+
+def copy_available_calibration_files(file_handler: FileHandler, source_directory: pathlib.Path):
+    """
+
+    Copies calibration file from source to file_handler
+
+    Parameters
+    ----------
+    source_directory : pathlib.Path
+    file_handler : FileHandler
+
+    Returns
+    -------
+    None
+
+    """
+
+    logger.debug(f'Copy calibration files from {source_directory}')
+    for calibration_file in [source_directory / FileHandler.CALIBRATE_ENERGY_REQUIREMENT,
+                             source_directory / FileHandler.CALIBRATE_ENERGY_CONSUMPTION]:
+        if calibration_file.is_file():
+            logger.debug(f'Creating calibration file {file_handler.input_directory / calibration_file.name}')
+            shutil.copy(calibration_file, file_handler.input_directory)
+
+
+def create_output_directory(output_directory: typing.Optional[pathlib.Path]=None,
+                            filename: typing.Optional[pathlib.Path]=None) -> pathlib.Path:
+    """
+    Creates the output directory if it does not exist. If a filename is supplied its parent will be created.
+
+    Parameters
+    ----------
+    output_directory : pathlib.Path, optional
+        The path to the output directory.
+    filename : pathlib.Path, optional
+        The name of a file in a directory expected to exist.
+    Raises
+    -------
+    IOError
+        The output_directory exists, but it is a file.
+    ValueError
+        output_directory and filename is empty
+    Returns
+    -------
+    pathlib.Path
+        The directory
+    """
+    if not output_directory and not filename:
+        raise ValueError('Both output_directory and filename cannot be None')
+    if output_directory and output_directory.is_file():
+        raise IOError(f'{output_directory} is a file')
+
+    if output_directory:
+        if output_directory.is_dir():
+            return output_directory
+        logger.debug(f'Creating output directory {output_directory}')
+        output_directory.mkdir(exist_ok=True)
+        return output_directory
+    elif filename and not filename.is_file():
+        logger.debug(f'Creating output directory {filename.parent}')
+        filename.parent.mkdir(exist_ok=True)
+        return filename.parent
+
+
+def init(file_handler: FileHandler, source_directory: pathlib.Path|None = None) -> pathlib.Path:
+    """
+    Initialize file_handler with input data from ebm.data or DEFAULT_INPUT_OVERRIDE.
+    Create output directory in current working directory if missing
+
+    Parameters
+    ----------
+    file_handler : FileHandler
+    source_directory : pathlib.Path, optional
+        Where location of input data
+
+    Returns
+    -------
+    pathlib.Path
+    """
+    if source_directory is None:
+        default_input_override = pathlib.Path(os.environ.get('EBM_DEFAULT_INPUT', DEFAULT_INPUT))
+        if default_input_override.is_dir():
+            logger.debug(f'{default_input_override=} exists')
+            source_directory = default_input_override
+        else:
+            logger.info(f'{default_input_override=} does not exist.')
+            source_directory = file_handler.default_data_directory()
+    elif not source_directory.is_dir():
+        raise NotADirectoryError(f'{source_directory} is not a directory')
+
+    logger.info(f'Copy input from {source_directory}')
+    create_input(file_handler, source_directory=source_directory)
+    copy_available_calibration_files(file_handler, source_directory=source_directory)
+    create_output_directory(pathlib.Path('output'))
+    return file_handler.input_directory
+
+
+def main() -> int:
+    """
+    Run module using command line arguments. Currently create_input.
+
+    Returns
+    -------
+    int
+
+    See Also
+    --------
+    create_input
+    """
+    ap = argparse.ArgumentParser()
+    ap.add_argument('input', nargs='?', type=pathlib.Path, default='input')
+    ap.add_argument('source',nargs='?', type=pathlib.Path, default=FileHandler.default_data_directory())
+
+    arguments = ap.parse_args()
+
+    init(FileHandler(directory=arguments.input), source_directory=arguments.source)
+    # create_input(FileHandler(directory=arguments.input), source_directory=arguments.source)
+    return 0
+
+if __name__ == '__main__':
+    main()

ebm/cmd/migrate.py

@@ -0,0 +1,92 @@
+import argparse
+import os
+import pathlib
+import sys
+import typing
+
+from loguru import logger
+from ebm.cmd.helpers import load_environment_from_dotenv, configure_loglevel
+from ebm.migrations import migrate_input_directory, translate_heating_system_efficiencies
+from ebm.model.file_handler import FileHandler
+
+
+def migrate_directories(directories: typing.Iterable[pathlib.Path|str]) -> None:
+    """
+    Migrates and validates a list of input directories.
+
+    Parameters
+    ----------
+    directories : Iterable[pathlib.Path or str]
+        A list of directory paths to be migrated and validated.
+
+    Returns
+    -------
+    None
+    """
+
+    for directory in map(pathlib.Path, directories):
+        migrate_directory(directory)
+
+
+def migrate_directory(directory: pathlib.Path):
+    """
+    Migrates and validates a single input directory.
+
+    Applies the `translate_heating_system_efficiencies` migration and validates
+    the input files using `FileHandler`.
+
+    Parameters
+    ----------
+    directory : pathlib.Path
+        The path to the directory to be migrated and validated.
+
+    Returns
+    -------
+    None
+    """
+
+    logger.debug(f'Open {directory} {type(directory)}')
+    migrate_input_directory(directory=directory, migration=translate_heating_system_efficiencies)
+    FileHandler(directory=directory).validate_input_files()
+
+
+def main() -> None:
+    """
+    Main entry point for the migration script.
+
+    Loads environment variables, configures logging, creates missing input files,
+    and performs migration and validation on a set of predefined directories.
+
+    Returns
+    -------
+    None
+    """
+
+    load_environment_from_dotenv()
+    configure_loglevel(log_format=os.environ.get('LOG_FORMAT', None))
+
+    logger.debug(f'Starting {sys.executable} {__file__}')
+
+    parser = argparse.ArgumentParser(description="Migrate and validate EBM input directories.")
+    parser.add_argument("directories",
+                        nargs="*",
+                        help="List of input directories to migrate. If omitted, uses EBM_INPUT_DIRECTORY environment variable.")
+
+    arguments = parser.parse_args()
+
+    directories = arguments.directories or os.environ.get('EBM_INPUT_DIRECTORY', '').split(os.pathsep)
+    if not directories or directories == ['']:
+        logger.error('No input directories provided via CLI or EBM_INPUT_DIRECTORY.')
+        sys.exit(1)
+
+    #new_fh = FileHandler(directory='t3192_input')
+    #new_fh.create_missing_input_files()
+
+    #migration_directories = ['../Energibruksmodell/tests/ebm/data/kalibrert', 't3192_input', 't2734_input',
+    #                         '../Energibruksmodell/ebm/data']
+
+    migrate_directories(directories)
+
+
+if __name__ == '__main__':
+    main()

ebm/cmd/pipeline.py

@@ -0,0 +1,227 @@
+import os
+import pathlib
+
+import pandas as pd
+
+from loguru import logger
+
+from ebm import extractors
+from ebm.cmd.helpers import load_environment_from_dotenv, configure_loglevel, configure_json_log
+from ebm.cmd.result_handler import transform_model_to_horizontal, transform_to_sorted_heating_systems
+from ebm.model import area as a_f, bema
+from ebm.model.data_classes import YearRange
+from ebm.model.database_manager import DatabaseManager
+from ebm.model import energy_need as e_n
+from ebm.model import energy_purpose as e_p
+from ebm.model import energy_use as e_u
+from ebm.model.file_handler import FileHandler
+from ebm.model import heating_systems_parameter as h_s_param
+from ebm.model import heat_pump as h_p
+from ebm.model.heating_systems_share import transform_heating_systems_share_long, transform_heating_systems_share_wide
+from ebm.s_curve import calculate_s_curves
+from ebm.services.spreadsheet import make_pretty, add_top_row_filter
+
+
+def main():
+    load_environment_from_dotenv()
+
+    configure_loglevel(os.environ.get('LOG_FORMAT', None))
+    configure_json_log()
+    input_path, output_path, years = load_config()
+
+    output_path.mkdir(exist_ok=True)
+
+    file_handler = FileHandler(directory=input_path)
+    database_manager = DatabaseManager(file_handler=file_handler)
+    list(export_energy_model_reports(years, database_manager, output_path))
+
+
+def export_energy_model_reports(years: YearRange, database_manager: DatabaseManager, output_path: pathlib.Path):
+    logger.info('Area to area.xlsx')
+    logger.debug('Extract area')
+
+    scurve_parameters = database_manager.get_scurve_params() # 📍
+
+    area_parameters = database_manager.get_area_parameters() # 📍
+    area_parameters['year'] = years.start
+
+    building_code_parameters = database_manager.file_handler.get_building_code() # 📍
+
+    s_curves_by_condition = calculate_s_curves(scurve_parameters, building_code_parameters, years) # 📌
+    area_forecast = extractors.extract_area_forecast(years, s_curves_by_condition, building_code_parameters, area_parameters, database_manager) # 📍
+    energy_need_kwh_m2 = extractors.extract_energy_need(years, database_manager) # 📍
+    heating_systems_projection = extractors.extract_heating_systems_forecast(years, database_manager) # 📍
+    energy_use_holiday_homes = extractors.extract_energy_use_holiday_homes(database_manager) # 📍
+
+    total_energy_need = e_n.transform_total_energy_need(energy_need_kwh_m2, area_forecast)  # 📌
+    heating_systems_parameter = h_s_param.heating_systems_parameter_from_projection(heating_systems_projection) # 📌
+    energy_use_kwh = e_u.building_group_energy_use_kwh(heating_systems_parameter, total_energy_need) # 📌
+
+    existing_area = a_f.filter_existing_area(area_forecast)
+
+    logger.debug('Transform fane 1 (wide)')
+    merged_building_code_and_condition = a_f.merge_building_code_and_condition(existing_area)
+    area_wide = transform_model_to_horizontal(merged_building_code_and_condition)
+    area_wide = area_wide.drop(columns=['building_code', 'building_condition']) #🏙️
+
+    logger.debug('Transform fane 2 (long')
+
+    area_by_year_category_building_code = existing_area.groupby(by='year,building_category,building_code'.split(','))[['m2']].sum()
+    area_by_year_category_building_code = area_by_year_category_building_code.rename(columns={'m2': 'area'})
+    area_by_year_category_building_code.insert(0, 'U', 'm2')
+    area_long = area_by_year_category_building_code.reset_index().sort_values(
+        by=['building_category', 'building_code', 'year'], key=bema.map_sort_order) #🏙️
+
+    logger.debug('Write file area.xlsx')
+
+    area_output = output_path / 'area.xlsx'
+
+    with pd.ExcelWriter(area_output, engine='xlsxwriter') as writer:
+        # Write wide first order matters
+        area_wide.to_excel(writer, sheet_name='wide', index=False) # 🏙️️💾
+        area_long.to_excel(writer, sheet_name='long', index=False) # 🏙️💾
+    logger.debug(f'Adding top row filter to {area_output}')
+    make_pretty(area_output)
+    add_top_row_filter(workbook_file=area_output, sheet_names=['long'])
+    yield area_output
+
+    logger.success(f'Wrote {area_output}')
+
+    logger.info('Energy use to energy_purpose')
+
+    logger.info('Heating_system_share')
+
+    logger.debug('Transform fane 2')
+    heating_systems_share = transform_heating_systems_share_long(heating_systems_projection)
+
+    logger.debug('Transform fane 1')
+    heating_systems_share_wide = transform_heating_systems_share_wide(heating_systems_share) # ♨️
+    heating_systems_share_long = heating_systems_share.rename(columns={ # ♨️
+        'heating_system_share': 'Share',
+        'heating_systems': 'Heating system'})
+
+    heating_systems_share_wide = heating_systems_share_wide.rename(columns={'heating_systems':'Heating technology'})
+
+    logger.debug('Write file heating_system_share.xlsx')
+    heating_system_share_file = output_path / 'heating_system_share.xlsx'
+    with pd.ExcelWriter(heating_system_share_file, engine='xlsxwriter') as writer:
+        # Write wide first order matters
+        heating_systems_share_wide.to_excel(writer, sheet_name='wide', merge_cells=False, index=False) # ♨️💾
+        heating_systems_share_long.to_excel(writer, sheet_name='long', merge_cells=False) # ♨️💾
+    make_pretty(heating_system_share_file)
+    logger.debug(f'Adding top row filter to {heating_system_share_file}')
+    add_top_row_filter(workbook_file=heating_system_share_file, sheet_names=['long'])
+    logger.success(f'Wrote {heating_system_share_file.name}')
+    yield heating_system_share_file
+
+    logger.info('heat_prod_hp')
+    logger.debug('Transform heating_system_parameters')
+
+    logger.debug('Transform to hp')
+    expanded_heating_systems_parameter = h_s_param.expand_heating_system_parameters(heating_systems_parameter)
+    air_air = h_p.air_source_heat_pump(expanded_heating_systems_parameter)
+    district_heating = h_p.district_heating_heat_pump(expanded_heating_systems_parameter)
+
+    production = h_p.heat_pump_production(total_energy_need, air_air, district_heating)
+    heat_prod_hp_wide = h_p.heat_prod_hp_wide(production) # 🧮
+
+    logger.debug('Write file heat_prod_hp.xlsx')
+    heat_prod_hp_file = output_path / 'heat_prod_hp.xlsx'
+
+    with pd.ExcelWriter(heat_prod_hp_file, engine='xlsxwriter') as writer:
+        heat_prod_hp_wide.to_excel(writer, sheet_name='wide', index=False) # 🧮💾
+    make_pretty(heat_prod_hp_file)
+    logger.success(f'Wrote {heat_prod_hp_file.name}')
+    yield heat_prod_hp_file
+
+    logger.info('Energy_use')
+
+    logger.debug('Transform energy_use_kwh')
+
+    logger.debug('Transform fane 1')
+    energy_use_gwh_by_building_group = e_u.energy_use_gwh_by_building_group(energy_use_kwh)
+
+    logger.debug('Transform fane 2')
+    logger.debug('Group by category, year, product')
+
+    column_order = ['year', 'building_category', 'building_code', 'energy_product', 'kwh']
+    energy_use_long = energy_use_kwh[column_order].groupby(
+        by=['building_category', 'building_code', 'energy_product', 'year']).sum() / 1_000_000
+    energy_use_long = energy_use_long.reset_index()[column_order].rename(columns={'kwh': 'energy_use'})
+    energy_use_long = energy_use_long.sort_values(
+        by=['building_category', 'building_code', 'year'], key=bema.map_sort_order) #🔌
+
+    logger.debug('Transform fane 1')
+    logger.debug('Group by group, product year')
+    energy_use_wide = transform_to_sorted_heating_systems(energy_use_gwh_by_building_group, energy_use_holiday_homes, #🔌
+                                                          building_column='building_group')
+    logger.debug('Write file energy_use')
+    energy_use_file = output_path / 'energy_use.xlsx'
+    with pd.ExcelWriter(energy_use_file, engine='xlsxwriter') as writer:
+        # Write wide first order matters
+        energy_use_wide.to_excel(writer, sheet_name='wide', index=False) #🔌💾
+        energy_use_long.to_excel(writer, sheet_name='long', index=False) #🔌💾
+    make_pretty(energy_use_file)
+    logger.debug(f'Adding top row filter to {energy_use_file}')
+    add_top_row_filter(workbook_file=energy_use_file, sheet_names=['long'])
+    logger.success(f'Wrote {energy_use_file.name}')
+    yield energy_use_file
+
+    logger.debug('Transform fane 1')
+    energy_purpose_wide = e_p.group_energy_use_kwh_by_building_group_purpose_year_wide(energy_use_kwh=energy_use_kwh) # 🚿
+
+    logger.debug('Transform fane 2')
+    energy_purpose_long = e_p.group_energy_use_by_year_category_building_code_purpose(energy_use_kwh=energy_use_kwh) # 🚿
+
+    logger.debug('Write file energy_purpose.xlsx')
+    energy_purpose_output = output_path / 'energy_purpose.xlsx'
+    with pd.ExcelWriter(energy_purpose_output, engine='xlsxwriter') as writer:
+        # Write wide first order matters
+        energy_purpose_wide.to_excel(writer, sheet_name='wide', index=False) # 🚿 💾
+        energy_purpose_long.to_excel(writer, sheet_name='long', index=False) # 🚿💾
+    make_pretty(energy_purpose_output)
+    logger.debug(f'Adding top row filter to {energy_purpose_output}')
+    add_top_row_filter(workbook_file=energy_purpose_output, sheet_names=['long'])
+    logger.success(f'Wrote {energy_purpose_output.name}')
+    yield energy_purpose_output
+
+    area_change = a_f.transform_area_forecast_to_area_change(area_forecast=area_forecast, building_code_parameters=building_code_parameters)
+
+    logger.info('demolition_construction')
+    logger.debug('Transform demolition_construction')
+    demolition_construction_long = a_f.transform_demolition_construction(energy_use_kwh, area_change)
+    demolition_construction_long = demolition_construction_long.rename(columns={'m2': 'Area [m2]',
+                                                                      'gwh': 'Energy use [GWh]'})
+    demolition_construction_long = demolition_construction_long.sort_values(
+        by=['building_category', 'building_code', 'year', 'demolition_construction'], key=bema.map_sort_order) # 🏗️
+
+    logger.debug('Write file demolition_construction.xlsx')
+    demolition_construction_file = output_path / 'demolition_construction.xlsx'
+    with pd.ExcelWriter(demolition_construction_file, engine='xlsxwriter') as writer:
+        demolition_construction_long.to_excel(writer, sheet_name='long', index=False) # 🏗️💾
+    make_pretty(demolition_construction_file)
+    logger.debug(f'Adding top row filter to {demolition_construction_file}')
+    add_top_row_filter(workbook_file=demolition_construction_file, sheet_names=['long'])
+    logger.success(f'Wrote {demolition_construction_file.name}')
+
+    yield demolition_construction_file
+
+
+def load_config():
+    try:
+        start_year = int(os.environ.get('EBM_START_YEAR', 2020))
+    except ValueError:
+        start_year = 2020
+    try:
+        end_year = int(os.environ.get('EBM_END_YEAR', 2050))
+    except ValueError:
+        end_year = 2050
+    years = YearRange(start_year, end_year)
+    input_path = pathlib.Path(os.environ.get('EBM_INPUT_DIRECTORY', 'input'))
+    output_path = pathlib.Path(os.environ.get('EBM_OUTPUT_DIRECTORY', 'output'))
+    return input_path, output_path, years
+
+
+if __name__ == '__main__':
+    main()
+

ebm/cmd/prepare_main.py

@@ -0,0 +1,174 @@
+"""Utility functions for __main__"""
+import argparse
+import os
+import pathlib
+import sys
+import textwrap
+import typing
+from dataclasses import dataclass
+from typing import List
+
+from loguru import logger
+
+from ebm.__version__ import version
+
+from ebm.model.building_category import BuildingCategory
+from ebm.model.building_condition import BuildingCondition
+from ebm.model.data_classes import YearRange
+from ebm.model.enums import ReturnCode
+from ebm.services.files import file_is_writable
+
+TEK = """PRE_TEK49
+PRE_TEK49
+TEK49
+TEK69
+TEK87
+TEK97
+TEK07
+TEK10
+TEK17
+TEK21""".strip().split('\n')
+
+
+@dataclass
+class EbmConfig:
+    """Prototype for an argument or configuation class to be used by main. Its purpose is improved readability."""
+    default_input: str = None
+    calibration_year: int = 2023
+    years: YearRange = YearRange(2020, 2050)
+    output_directory: pathlib.Path = pathlib.Path('output')
+    input_directory: pathlib.Path = pathlib.Path('input')
+    force_overwrite: bool = False
+    open_after_writing: bool = False
+    csv_delimiter: str = ','
+    always_open: bool = False
+    write_to_disk: bool = False
+
+    #building_categories: typing.List[BuildingCategory]
+    #building_conditions = typing.List[BuildingCondition]
+    #building_code_filter: typing.List[str]
+
+
+def make_arguments(program_name, default_path: pathlib.Path) -> argparse.Namespace:
+    """
+    Create and parse command-line arguments for the area forecast calculation.
+
+    Parameters
+    ----------
+    program_name : str
+        Name of this program
+    default_path : pathlib.Path
+        Default path for the output file.
+
+    Returns
+    -------
+    argparse.Namespace
+        Parsed command-line arguments.
+
+    Notes
+    -----
+    The function sets up an argument parser with various options including version, debug mode,
+    filename, force write, open file after writing, CSV delimiter, building categories,
+    creating default input, start year, and end year.
+    """
+
+    default_building_categories: List[str] = [str(b) for b in iter(BuildingCategory)]
+
+    arg_parser = argparse.ArgumentParser(prog=program_name,
+                                         description=f'Calculate EBM energy use {version}',
+                                         formatter_class=argparse.RawTextHelpFormatter
+                                         )
+    arg_parser.add_argument('--version', '-v', action='version', version=f'{program_name} {version}')
+    arg_parser.add_argument('--debug', action='store_true',
+                            help='Run in debug mode. (Extra information written to stdout)')
+    arg_parser.add_argument('step', type=str, nargs='?',
+                            choices=['area-forecast',
+                                     'energy-requirements',
+                                     'heating-systems',
+                                     'energy-use'],
+                            default='energy-use',
+                            help="""
+The calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run 
+    automatically.""")
+    arg_parser.add_argument('output_file', nargs='?', type=pathlib.Path, default=default_path,
+                            help=textwrap.dedent(
+                                f'''The location of the file you want to be written. default: {default_path}
+    If the file already exists the program will terminate without overwriting. 
+    Use "-" to output to the console instead'''))
+    arg_parser.add_argument('--categories', '--building-categories', '-c',
+                            nargs='*', type=str, default=default_building_categories,
+                            help=textwrap.dedent(f"""
+                                   One or more of the following building categories: 
+                                       {", ".join(default_building_categories)}. 
+                                       The default is to use all categories."""
+                                                 ))
+    arg_parser.add_argument('--input', '--input-directory', '-i',
+                            nargs='?',
+                            type=pathlib.Path,
+                            default=pathlib.Path(os.environ.get('EBM_INPUT_DIRECTORY', 'input')),
+                            help='path to the directory with input files')
+    arg_parser.add_argument('--force', '-f', action='store_true',
+                            help='Write to <filename> even if it already exists')
+    arg_parser.add_argument('--open', '-o', action='store_true',
+                            help='Open output file(s) automatically when finished writing. (Usually Excel)')
+    arg_parser.add_argument('--csv-delimiter', '--delimiter', '-e', type=str, default=',',
+                            help='A single character to be used for separating columns when writing csv. ' +
+                                 'Default: "," Special characters like ; should be quoted ";"')
+    arg_parser.add_argument('--create-input', action='store_true',
+                            help='''
+Create input directory containing all required files in the current working directory''')
+
+    arg_parser.add_argument('--migrate', action='store_true', help=argparse.SUPPRESS)
+
+    arg_parser.add_argument('--start-year', nargs='?', type=int,
+                            default=os.environ.get('EBM_START_YEAR', 2020),
+                            help=argparse.SUPPRESS)
+    arg_parser.add_argument('--end-year', nargs='?', type=int,
+                            default=os.environ.get('EBM_END_YEAR', 2050),
+                            help=argparse.SUPPRESS)
+
+    arg_parser.add_argument('--horizontal-years', '--horizontal', '--horisontal', action='store_true',
+                            help='Show years horizontal (left to right)')
+
+    arguments = arg_parser.parse_args()
+    return arguments
+
+
+def check_output_file_status(output_file: pathlib.Path,
+                             force: bool=False,
+                             default_path: pathlib.Path = None,
+                             program_name: str='ebm') -> ReturnCode:
+    """
+    Checks if the output file exists and that it is writable. If force is true the output_file will be opened for
+    appending. A permission denied at that point is an indication that the file is already open by another process.
+
+    The following values may be returned
+        - 0 RETURN_CODE_OK
+        - 1 RETURN_CODE_FILE_NOT_ACCESSIBLE
+        - 2 RETURN_CODE_FILE_EXISTS
+
+    Parameters
+    ----------
+    output_file : pathlib.Path
+    force : bool
+    default_path : pathlib.Path
+    program_name : str
+
+    Returns
+    -------
+    ReturnCode
+    """
+    default_path = default_path if default_path else pathlib.Path('output/ebm_output.xlsx')
+
+    if output_file.is_file() and output_file != default_path and not force:
+        # If the file already exists and is not the default, display error and exit unless --force was used.
+        logger.error(f'{output_file}. already exists.')
+        print(f"""
+    You can overwrite the {output_file}. by using --force: {program_name} {' '.join(sys.argv[1:])} --force
+    """.strip(),
+              file=sys.stderr)
+        return ReturnCode.FILE_EXISTS
+    if output_file.name != '-' and not file_is_writable(output_file):
+        # logger.error(f'{output_file} is not writable')
+        return ReturnCode.FILE_NOT_ACCESSIBLE
+    return ReturnCode.OK