API documentation¶

class ionworks.util.OptionSpec(default_value, other_allowed_values: list | None = None)[source]¶

Bases: object

Specification for an option

Parameters:

default_value (any) – The default value for the option
other_allowed_values (list, optional) – A list of allowed values for the option, by default None. If None, the value can be anything. If a list, the value must be in this list.

ionworks.util.subplots_autolayout(n, *args, n_rows=None, figsize=None, layout='constrained', **kwargs)[source]¶: Create a subplot element

ionworks.util.check_and_combine_options(default_options, custom_options=None, filter_unknown=False) → dict[source]¶

Check that all required options are provided, and combine default and custom options

Parameters:

default_options (dict) –
Dictionary of default options. Each key is an option name, and the value can be either:
- The default value for that option
- ”[required]” if the option must be provided in custom_options
- A list of allowed values for that option. If the option is not provided in custom_options, the first value in the list is used.
custom_options (dict, optional) – Dictionary of custom options, by default None. If a key in custom_options is not in default_options, an error is raised (unless filter_unknown is True).
filter_unknown (bool, optional) – If False (default), raise ValueError for any key in custom_options that is not in default_options. If True, ignore such keys and only use options that have a default.

Returns:

Combined options

Return type:

dict

Raises:

ValueError – If filter_unknown is False and a key in custom_options is not in default_options. If a required option is not provided in custom_options. If a list option is not one of the allowed values.

ionworks.util.read_df(file, **kwargs)[source]¶

ionworks.util.read_df(file: str, **kwargs)

ionworks.util.read_df(file: Path, **kwargs)

ionworks.util.read_df(file: DataFrame, **kwargs)

Read a dataframe from a file. Currently: supports csv, xls, xlsx, json, and parquet.

Parameters:

file (str or Path) – File to read
**kwargs (dict) – Additional keyword arguments to pass to the read function

ionworks.util.iwutil_file_path_helper(file_name: str | Path, **kwargs)[source]¶

ionworks.util.read_json(file_name)[source]¶

Read a json file and sanitize the input

Parameters:: file_name (str or Path) – File to read

ionworks.util.copyfile(src, dst)[source]¶

Copy a file from src to dst, creating the parent directory if it does not exist

Parameters:

src (str or Path) – Source file
dst (str or Path) – Destination file

ionworks.util.this_dir(file)[source]¶: Get the directory of the file

ionworks.util.append_path(path)[source]¶

Append a path to the current path

Parameters:: path (str or Path) – Path to append

ionworks.util.random.current_time_integer() → int[source]¶: Get the current time as an integer in the format %Y%m%d%H%M%S%f

ionworks.util.random.generate_seed() → int[source]¶: Get a new numpy seed from the current time. Numpy seeds are signed 32-bit integers.

ionworks.util.random.seed(value: int | None = None)[source]¶: Set the random seed for numpy to a random number.

ionworks.util.random.get_seed() → int[source]¶: Get the random seed for numpy.

ionworks.util.save.create_folder(filename)[source]¶

Create a folder if it does not exist

Parameters:: filename (str) – File name in the folder to create

ionworks.util.save.json(params, filename)[source]¶

Save params to a json file

Parameters:

params (dict) – Dictionary of parameters
filename (str) – Full path and name of the file to save

ionworks.util.save.csv(df, filename)[source]¶

ionworks.util.save.csv(df: DataFrame, filename)

Save df to a csv file

Parameters:

df (pandas.DataFrame or polars.DataFrame) – DataFrame to save
filename (str) – Full path and name of the file to save

ionworks.util.save.parquet(df, filename)[source]¶

ionworks.util.save.parquet(df: DataFrame, filename)

Save df to a parquet file

Parameters:

df (pandas.DataFrame or polars.DataFrame) – DataFrame to save
filename (str) – Full path and name of the file to save

ionworks.util.save.txt(df, filename)[source]¶

ionworks.util.save.txt(df: DataFrame, filename)

Save df to a txt file (tab-separated)

Parameters:

df (pandas.DataFrame or polars.DataFrame) – DataFrame to save
filename (str) – Full path and name of the file to save

ionworks.util.save.fig(fig_to_save, filename)[source]¶

Save fig to a file

Parameters:

fig_to_save (matplotlib.figure.Figure) – Figure to save
filename (str) – Full path and name of the file to save