swvo.io.utils#

Functions

`any_nans`(data)	Calculate if a list of data frames contains any nans.
`construct_updated_data_frame`(data, ...)	Construct an updated data frame providing the previous data frame and the data frame of the current model call.
`datenum`(date_input[, month, year, hour, ...])	Convert a date to a MATLAB serial date number.
`datestr`(datenum)	Convert MATLAB datenum to a formatted date string.
`enforce_utc_timezone`(...)	Ensure datetime object(s) have UTC timezone information.
`nan_percentage`(data)	Calculate the percentage of NaN values in the data column of data frame and log it.
`sw_mag_propagation`(sw_data)	Propagate the solar wind magnetic field to the bow shock and magnetopause.

swvo.io.utils.any_nans(data: list[DataFrame] | DataFrame) → bool[source]#

Calculate if a list of data frames contains any nans.

Parameters:

datalist[pd.DataFrame] | pd.DataFrame: Data frame or list of data frames to process

Returns:

bool: Bool if any data frame of the list contains any nan values

swvo.io.utils.nan_percentage(data: DataFrame) → float[source]#

Calculate the percentage of NaN values in the data column of data frame and log it.

Parameters:

datapd.DataFrame: The data frame to process

Returns:

float: Nan percentage in the data frame

swvo.io.utils.construct_updated_data_frame(data: list[DataFrame] | DataFrame, data_one_model: list[DataFrame] | DataFrame, model_label: str) → list[DataFrame][source]#

Construct an updated data frame providing the previous data frame and the data frame of the current model call.

Also adds the model label to the data frame. :param data: The data frame or list of data frames to update. :type data: list[pd.DataFrame] | pd.DataFrame :param data_one_model: The data frame or list of data frames from the current model call. :type data_one_model: list[pd.DataFrame] | pd.DataFrame :param model_label: The label of the model to add to the data frame. :type model_label: str

Returns:

list[pd.DataFrame]: The updated data frame or list of data frames with the model label added.

swvo.io.utils.datenum(date_input: datetime | int, month: int | None = None, year: int | None = None, hour: int = 0, minute: int = 0, seconds: int = 0) → float[source]#

Convert a date to a MATLAB serial date number.

Parameters:

date_inputdatetime | int: A datetime object or an integer representing the day of the month.
monthint, optional: The month of the date. Required if date_input is an integer.
yearint, optional: The year of the date. Required if date_input is an integer.
hourint: The hour of the date, by default 0
minuteint: The minute of the date, by default 0
secondsint: The seconds of the date, by default 0

Returns:

float: The MATLAB serial date number.

Raises:

ValueError: If the input is invalid, i.e., if date_input is an integer and month or year is not provided.

swvo.io.utils.datestr(datenum: float) → str[source]#

Convert MATLAB datenum to a formatted date string.

Parameters:

datenumfloat: The MATLAB datenum to convert.

Returns:

str: The formatted date string in the format “YYYYMMDDHHMM00”.

swvo.io.utils.sw_mag_propagation(sw_data: DataFrame) → DataFrame[source]#

Propagate the solar wind magnetic field to the bow shock and magnetopause.

Parameters:

sw_datapd.DataFrame: Data frame containing solar wind data with a ‘speed’ column.

Returns:

pd.DataFrame: Data frame with propagated solar wind data, indexed by time.

swvo.io.utils.enforce_utc_timezone(time: datetime) → datetime[source]#

swvo.io.utils.enforce_utc_timezone(time: list[datetime]) → list[datetime]

swvo.io.utils.enforce_utc_timezone(time: Timestamp) → Timestamp

swvo.io.utils.enforce_utc_timezone(time: Series) → Series

swvo.io.utils.enforce_utc_timezone(time: DatetimeIndex) → DatetimeIndex

swvo.io.utils.enforce_utc_timezone(time: Index) → Index

Ensure datetime object(s) have UTC timezone information.

If the provided datetime object(s) are naive (lack timezone info), UTC timezone is assigned. If they already have a timezone, they are converted to UTC.

Parameters:

timedatetime, Iterable[datetime], pd.Timestamp, pd.Series, or pd.DatetimeIndex: The datetime object(s) to process. Can be: - Single datetime.datetime object - List of datetime.datetime objects - Single pandas.Timestamp object - pandas.Series with datetime64 dtype - pandas.DatetimeIndex

Returns:

datetime, list of datetime, pd.Timestamp, pd.Series, or pd.DatetimeIndex: The datetime object(s) in UTC timezone. Returns the same type as input.

Notes

For naive datetimes, this function assumes the times are already in UTC and simply adds the timezone information
For timezone-aware datetimes, conversion to UTC is performed
When processing pandas objects, the operation is vectorized for efficiency