diff --git a/swmmio/utils/dataframes.py b/swmmio/utils/dataframes.py index a77e003..4a4e2d1 100644 --- a/swmmio/utils/dataframes.py +++ b/swmmio/utils/dataframes.py @@ -209,8 +209,10 @@ def get_link_coords(row, nodexys, verticies): def get_inp_options_df(inp_path): """ Parse ONLY the OPTIONS section of the inp file into a dataframe + :param inp_path: path to inp file :return: pandas.DataFrame + >>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY >>> ops = get_inp_options_df(MODEL_FULL_FEATURES_XY) >>> ops[:3] diff --git a/swmmio/utils/text.py b/swmmio/utils/text.py index 7c97dda..cf65b36 100644 --- a/swmmio/utils/text.py +++ b/swmmio/utils/text.py @@ -225,13 +225,26 @@ def find_byte_range_of_section(path, start_string): def get_inp_sections_details(inp_path, include_brackets=False): """ - creates a dictionary with all the headers found in an INP file + Creates a dictionary with all the headers found in an INP file (which varies based on what the user has defined in a given model) and updates them based on the definitions in inp_header_dict - this ensures the list is comprehensive - :param inp_path: - :param include_brackets: whether to parse sections including the [] - :return: OrderedDict + to ensure the list is comprehensive. + + Parameters + ---------- + inp_path : str + Path to the INP file. + include_brackets : bool, optional + Whether to parse sections including the brackets ([]). Default is False. + + Returns + ------- + OrderedDict + An ordered dictionary with section headers as keys and their + corresponding details. + + Examples + -------- >>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY >>> headers = get_inp_sections_details(MODEL_FULL_FEATURES_XY) >>> [header for header, cols in headers.items()][:4] @@ -283,14 +296,20 @@ def get_inp_sections_details(inp_path, include_brackets=False): return found_sects -def get_rpt_sections_details(rpt_path): +def get_rpt_sections_details(rpt_path: str): """ + Extracts and returns the details of sections from a SWMM report file. - :param rpt_path: - :param include_brackets: - :return: - # >>> MODEL_FULL_FEATURES__NET_PATH + Parameters + ---------- + rpt_path : str + The file path to the SWMM report file. + Returns + ------- + OrderedDict + An ordered dictionary where the keys are section headers found in the report file + and the values are the corresponding details as defined in the RPT_OBJECTS. """ from swmmio.defs import RPT_OBJECTS found_sects = OrderedDict() diff --git a/swmmio/version_control/inp.py b/swmmio/version_control/inp.py index 8f95b3b..42fd7bd 100644 --- a/swmmio/version_control/inp.py +++ b/swmmio/version_control/inp.py @@ -74,7 +74,20 @@ def __radd__(self, other): def save(self, dir, filename): """ - save the current BuildInstructions instance to file (human readable) + Save the current BuildInstructions instance to a file in a human-readable format. + + Parameters + ---------- + dir : str + The directory where the file will be saved. If the directory does not exist, it will be created. + filename : str + The name of the file to save the BuildInstructions instance to. + + Notes + ----- + This method writes metadata and instructions to the specified file. The instructions are written + by concatenating the removed, altered, and added changes for each section and then writing them + to the file. """ if not os.path.exists(dir): os.makedirs(dir) diff --git a/swmmio/version_control/utils.py b/swmmio/version_control/utils.py index ea99ab8..5b56e9d 100644 --- a/swmmio/version_control/utils.py +++ b/swmmio/version_control/utils.py @@ -6,19 +6,31 @@ from swmmio.utils.functions import format_inp_section_header -def copy_rpts_hsf(from_dir, to_dir, search_dir): +def copy_rpts_hsf(from_dir: str, to_dir: str, search_dir: str): + """ - walk through a directory and find all rpts and hot start files and copy to - another location based on the relative path from the to_dir. - - ex: - to_directory = r'P:\02_Projects\SouthPhila\SE_SFR\MasterModels' - from_dir = r'F:\models\SPhila\MasterModels_170104' - search_dir = r'F:\models\SPhila\MasterModels_170104\Combinations' - copy_rpts_hsf(from_dir, to_dir, search_dir) - - - Good for model results written on a local drive to a network drive + Walk through a directory and find all .rpt and hot start (.hsf) files and copy them to + another location based on the relative path from the `to_dir`. + + Parameters + ---------- + from_dir : str + The source directory from which the relative path is derived. + to_dir : str + The destination directory where the files will be copied. + search_dir : str + The directory to search for .rpt and .hsf files. + + Examples + -------- + >>> to_directory = r'P:\\02_Projects\\SouthPhila\\SE_SFR\\MasterModels' + >>> from_dir = r'F:\\models\\SPhila\\MasterModels_170104' + >>> search_dir = r'F:\\models\\SPhila\\MasterModels_170104\\Combinations' + >>> copy_rpts_hsf(from_dir, to_dir, search_dir) + + Notes + ----- + This function is useful for copying model results written on a local drive to a network drive. """ # chain.from_iterable(os.walk(path) for path in paths): diff --git a/swmmio/version_control/version_control.py b/swmmio/version_control/version_control.py index 76ecdcb..b7dd209 100644 --- a/swmmio/version_control/version_control.py +++ b/swmmio/version_control/version_control.py @@ -47,24 +47,29 @@ def propagate_changes_from_baseline(baseline_dir, alternatives_dir, combi_dir, bi.build(baseline_dir, model.inp.path) # overwrite old inp -def create_combinations(baseline_dir, rsn_dir, combi_dir, version_id='', - comments=''): +def create_combinations(baseline_dir, rsn_dir, combi_dir, version_id='', comments=''): """ Generate SWMM5 models of each logical combination of all implementation phases (IP) across all relief sewer networks (RSN). - Inputs: - baseline_dir -> path to directory containing the baseline SWMM5 model - rsn_dir -> path to directory containing subdirectories for each RSN - containing directories for each IP within the network - combi_dir -> target directory in which child models will be created - version_id -> identifier for a given version (optional) - comments -> comments tracked within build instructions log for - each model scenario (optional) - - Calling create_combinations will update child models if parent models have - been changed. - + Parameters + ---------- + baseline_dir : str + Path to directory containing the baseline SWMM5 model. + rsn_dir : str + Path to directory containing subdirectories for each RSN, which contain + directories for each IP within the network. + combi_dir : str + Target directory in which child models will be created. + version_id : str, optional + Identifier for a given version (default is an empty string). + comments : str, optional + Comments tracked within build instructions log for each model scenario + (default is an empty string). + + Notes + ----- + Calling `create_combinations` will update child models if parent models have """ base_inp_path = Model(baseline_dir).inp.path