Utilities

Dictionary Utilities

Convenience functions for dictionary access and YAML

exception range_driver.dict_utils.YAMLProcessingError

Bases: Exception

Indicate downstream processing error of loaded YAML structure

range_driver.dict_utils.deep_update(d1, d2)

Recursively updates d1 with d2

Parameters

• d1 (dict) – A dictionary (possibly nested) to be updated.

• d2 (dict) – A dictionary (possibly nested) which will be used to update d1.

Returns

An updated version of d1, where d2 values were used to update the values of d1. Will add d2 keys if not present in d1. If a key does exist in d1, that key’s value will be overwritten by the d2 value. Works recursively to update nested dictionaries.

Return type

dict

range_driver.dict_utils.make_Bunch(docstr, *args, **kwargs)

Construct a Bunch collection with alternative doc string

All arguments after docstr are passed to the Bunch dict constructor. The main appeal of a bunch d over a dict, is that keys can be accessed via d.key rather than just d[‘key’]

Example:

B = make_Bunch(“””Container for special custom data”””,a=1) B.b = 3 print(B) help(B)

range_driver.dict_utils.merge_dicts(d1, d2)

Performs a deep_update() of d1 using d2. Recursively updates d1 with d2, while also making a deep copy of d1.

Parameters

• d1 (dict) – A dictionary (possibly nested) to be updated.

• d2 (dict) – A dictionary (possibly nested) which will be used to update d1.

Returns

An updated & deep-copied version of d1, where d2 values were used to update the values of d1. Will add d2 keys if not present in d1. If a key does exist in d1, that key’s value will be overwritten by the d2 value. Works recursively to update nested dictionaries.

Return type

dict

range_driver.dict_utils.nested_value(d, keys)

Access an element in nested dictioary d with path given by list of keys

range_driver.dict_utils.select_keys(d, keys)

Returns the items in dict d whose keys are listen in keys

range_driver.dict_utils.set_class_dict(cls, clsdict)

Set builtin class properties

range_driver.dict_utils.set_docstr(cls, docstr, **kwargs)

Modify the docstring of a class cls

range_driver.dict_utils.ydump(data, *args, sort_keys=False, **kwargs)

Create YAML output string for data object. If data is an OrderedDict, original key ordering is preserved in internal call to yaml.dump().

Parameters

• data (dict or Bunch) –

• args – Additional args passed on to yaml.dump()

• sort_keys (bool) – defaults to False

• kwargs – Further keyword args are passed on to yaml.dump()

Returns

YAML string representation of data

Return type

str

range_driver.dict_utils.yload(datastr, Loader=<class 'yaml.loader.SafeLoader'>, MapType=<class 'sklearn.utils.Bunch'>, **kwargs)

Load object from YAML input string or stream

Parameters

• datastr (str or stream) – A string or stream containing YAML formatted text

• Loader (yaml.Loader Object, optional) – The yaml loader object to use, defaults to yaml.SaveLoader

• MapType (type, optional) – type of dictionary to construct, defaults to Bunch

• kwargs – Further keyword args are passed on to yaml.load()

Returns

Python object representation of the YAML string/stream

Return type

Specified in MapType parameter

Geospatial Utilities

range_driver.geo_utils.dist_m(latlon0, latlon1)

Geodesic distance calculation

iPython Utilities

range_driver.ipython_utils.display_full_df(df, max_rows=None, max_columns=None)

range_driver.ipython_utils.displaymd(strmd)

Display Markdown in notebook

MatPlotLib Utilities

range_driver.mpl_utils.mpl_set_notebook_params()

Initializes sensible MatPlotLib parameters for viewing plots in the Jupyter notebook interface.

Returns

None. Makes preset changes to MatPlotLib’s runtime configuration parameters.

Pandas Utilities

range_driver.pandas_utils.dataframe_schema(columns, dtypes)

Create empty pd.DataFrame with columns of given datatypes

range_driver.pandas_utils.get_next_index(df, index_val, lock_bound=False, inc=1)

Determine the index value that follows index_val

Parameters

• df (pd.DataFrame or pd.Series) – dataframe or series, having df.index.

• index_val – index value to start from

• lock_bound (bool) – if true return same index if reaching bounds

• inc (int) – Increment. default +1, use -1 to get previous index

Returns

neighbouring index value

range_driver.pandas_utils.index_columns(df, none_name=None)

Return list of column names that form the (multi-)index or None, if index is a single unnamed column.

range_driver.pandas_utils.remove_microsecond(ts)

range_driver.pandas_utils.split_by_index(df, split_idx)

Split DataFrame df at or around the given index value

Parameters

• df (pandas.DataFrame) – DataFrame with a sorted index

• split_idx (int) – The index value to split df by.

Returns

• low_df (pandas.DataFrame) - DataFrame containing index values below split_idx

• high_df (pandas.DataFrame) - DataFrame containing index values greater than or equal to split_idx.

range_driver.pandas_utils.update_on(df, dfu, on=None)

Use DataFrame.update() function inplace, matching on any set of columns.

Other Utilities

Generic utility functions

range_driver.utils.eval_shell(cmdargs)

Run command in shell and return string output. Input cmdargs is list of command and individual args.

range_driver.utils.load_file(filename)

Loads and returns the contents of filename.

Parameters

filename (str) – A string containing the filepath of the file to be loaded/

Returns

Contents of the loaded file.

Return type

str

range_driver.utils.reload_acoustic(module_name='acoustic', env_name='acoustic_env')

range_driver.utils.reload_all(module_name)

Reload all modules that have module_name in their path.

range_driver.utils.repo_file_path(*fn, folder='data')

range_driver.utils.repo_path()