From e159f94dd087bacb654c608378bc20352f2b2c8b Mon Sep 17 00:00:00 2001 From: Nick H <34072991+nickssl@users.noreply.github.com> Date: Tue, 16 Apr 2024 20:04:31 -0700 Subject: [PATCH] Fixed docstrings and examples. --- pytplot/timebar.py | 134 ++++++++++++++++++++++++++++---------------- pytplot/timespan.py | 77 ++++++++++++------------- 2 files changed, 125 insertions(+), 86 deletions(-) diff --git a/pytplot/timebar.py b/pytplot/timebar.py index 6e2487a3..c462d442 100644 --- a/pytplot/timebar.py +++ b/pytplot/timebar.py @@ -1,96 +1,134 @@ -# Copyright 2018 Regents of the University of Colorado. All Rights Reserved. -# Released under the MIT license. -# This software was developed at the University of Colorado's Laboratory for Atmospheric and Space Physics. -# Verify current version before use at: https://github.com/MAVENSDC/PyTplot - from . import tplot_utilities import pytplot import logging -def timebar(t, varname = None, databar = False, delete = False, color = 'black', thick = 1, dash = False): + +def timebar(t, varname=None, databar=False, delete=False, color="black", thick=1, dash=False): """ This function will add a vertical bar to all time series plots. This is useful if you - want to bring attention to a specific time. - + want to bring attention to a specific time. + Parameters: - t : flt/list + t : float/list The time in seconds since Jan 01 1970 to place the vertical bar. If a list of numbers are supplied, - multiple bars will be created. If "databar" is set, then "t" becomes the point on the y axis to - place a horizontal bar. + multiple bars will be created. If "databar" is set, then "t" becomes the point on the y axis to + place a horizontal bar. varname : str/list, optional - The variable(s) to add the vertical bar to. If not set, the default is to add it to all current plots. + The variable(s) to add the vertical bar to. If not set, the default is to add it to all current plots. databar : bool, optional - This will turn the timebar into a horizontal data bar. If this is set True, then variable "t" becomes - the point on the y axis to place a horizontal bar. + This will turn the timebar into a horizontal data bar. If this is set True, then variable "t" becomes + the point on the y axis to place a horizontal bar. delete : bool, optional If set to True, at lease one varname must be supplied. The timebar at point "t" for variable "varname" - will be removed. + will be removed. color : str The color of the bar thick : int The thickness of the bar dash : bool If set to True, the bar is dashed rather than solid - + Returns: None - + Examples: >>> # Place a green time bar at 2017-07-17 00:00:00 >>> import pytplot >>> pytplot.timebar(1500249600, color='green') - + >>> # Place a dashed data bar at 5500 on the y axis >>> pytplot.timebar(5500, dashed=True, databar=True) - - >>> Place 3 magenta time bars of thickness 5 + + >>> Place 3 magenta time bars of thickness 5 at [2015-12-26 05:20:01, 2015-12-26 08:06:40, 2015-12-26 08:53:19] for variable 'sgx' plot >>> pytplot.timebar([1451107201,1451117200,1451119999],'sgx',color='m',thick=5) """ - + """ + This function will add a vertical bar to all time series plots. This is useful if you + want to bring attention to a specific time. + + Parameters + ---------- + t : float or list + The time in seconds since Jan 01 1970 to place the vertical bar. If a list of numbers are supplied, + multiple bars will be created. If "databar" is set, then "t" becomes the point on the y axis to + place a horizontal bar. + varname : str or list, optional + The variable(s) to add the vertical bar to. If not set, the default is to add it to all current plots. + databar : bool, optional + This will turn the timebar into a horizontal data bar. If this is set True, then variable "t" becomes + the point on the y axis to place a horizontal bar. + delete : bool, optional + If set to True, at least one varname must be supplied. The timebar at point "t" for variable "varname" + will be removed. + color : str + The color of the bar. + thick : int + The thickness of the bar. + dash : bool + If set to True, the bar is dashed rather than solid. + + Returns + ------- + None + + Examples + -------- + >>> # Place a green time bar at 2017-07-17 00:00:00 + >>> import pytplot + >>> pytplot.timebar(1500249600, color='green') + + >>> # Place a dashed data bar at 5500 on the y axis + >>> pytplot.timebar(5500, dash=True, databar=True) + + >>> # Place 3 magenta time bars of thickness 5 + >>> # at [2015-12-26 05:20:01, 2015-12-26 08:06:40, 2015-12-26 08:53:19] + >>> # for variable 'sgx' plot + >>> pytplot.timebar([1451107201,1451117200,1451119999],'sgx',color='m',thick=5) + """ + # make sure t entered is a list if not isinstance(t, list): t = [t] - + # if entries in list not numerical, run str_to_int if not isinstance(t[0], (int, float, complex)): t1 = [] for time in t: t1.append(tplot_utilities.str_to_float_fuzzy(time)) t = t1 - - dim = 'height' + + dim = "height" if databar is True: - dim = 'width' - - dash_pattern = 'solid' + dim = "width" + + dash_pattern = "solid" if dash is True: - dash_pattern = 'dashed' - - + dash_pattern = "dashed" + if delete is True: tplot_utilities.timebar_delete(t, varname, dim) return - - #if no varname specified, add timebars to every plot + + # if no varname specified, add timebars to every plot if varname is None: num_bars = len(t) for i in range(num_bars): tbar = {} - tbar['location'] = t[i] - tbar['dimension'] = dim - tbar['line_color'] = pytplot.tplot_utilities.rgb_color(color)[0] - tbar['line_width'] = thick - tbar['line_dash'] = dash_pattern + tbar["location"] = t[i] + tbar["dimension"] = dim + tbar["line_color"] = pytplot.tplot_utilities.rgb_color(color)[0] + tbar["line_width"] = thick + tbar["line_dash"] = dash_pattern for name in pytplot.data_quants: temp_data_quants = pytplot.data_quants[name] if isinstance(temp_data_quants, dict): # non-record varying variable - continue - temp_data_quants.attrs['plot_options']['time_bar'].append(tbar) - #if varname specified + continue + temp_data_quants.attrs["plot_options"]["time_bar"].append(tbar) + # if varname specified else: if not isinstance(varname, list): varname = [varname] @@ -101,14 +139,14 @@ def timebar(t, varname = None, databar = False, delete = False, color = 'black', num_bars = len(t) for i in range(num_bars): tbar = {} - tbar['location'] = t[i] - tbar['dimension'] = dim - tbar['line_color'] = pytplot.tplot_utilities.rgb_color(color)[0] - tbar['line_width'] = thick - tbar['line_dash'] = dash_pattern + tbar["location"] = t[i] + tbar["dimension"] = dim + tbar["line_color"] = pytplot.tplot_utilities.rgb_color(color)[0] + tbar["line_width"] = thick + tbar["line_dash"] = dash_pattern temp_data_quants = pytplot.data_quants[j] if isinstance(temp_data_quants, dict): # non-record varying variable - continue - temp_data_quants.attrs['plot_options']['time_bar'].append(tbar) - return \ No newline at end of file + continue + temp_data_quants.attrs["plot_options"]["time_bar"].append(tbar) + return diff --git a/pytplot/timespan.py b/pytplot/timespan.py index 24b761a4..8fa5b306 100644 --- a/pytplot/timespan.py +++ b/pytplot/timespan.py @@ -1,53 +1,54 @@ -# Copyright 2018 Regents of the University of Colorado. All Rights Reserved. -# Released under the MIT license. -# This software was developed at the University of Colorado's Laboratory for Atmospheric and Space Physics. -# Verify current version before use at: https://github.com/MAVENSDC/PyTplot - from . import time_double from .xlim import xlim import logging -def timespan(t1, dt, keyword='days'): + +def timespan(t1, dt, keyword="days"): """ - This function will set the time range for all time series plots. This is a wrapper for the function "xlim" to - better handle time axes. - - Parameters: - t1 : flt/str - The time to start all time series plots. Can be given in seconds since epoch, or as a string - in the format "YYYY-MM-DD HH:MM:SS" - dt : flt - The time duration of the plots. Default is number of days. - keyword : str - Sets the units of the "dt" variable. Days, hours, minutes, and seconds are all accepted. - - Returns: - None - - Examples: - >>> # Set the timespan to be 2017-07-17 00:00:00 plus 1 day - >>> import pytplot - >>> pytplot.timespan(1500249600, 1) - - >>> # The same as above, but using different inputs - >>> pytplot.timespan("2017-07-17 00:00:00", 24, keyword='hours') + This function will set the time range for all time series plots. This is a wrapper for the function "xlim" to + better handle time axes. + + Parameters + ---------- + t1 : float or str + The time to start all time series plots. Can be given in seconds since epoch, or as a string + in the format "YYYY-MM-DD HH:MM:SS". + dt : float + The time duration of the plots. Default is number of days. + keyword : str, optional + Sets the units of the "dt" variable. Days, hours, minutes, and seconds are all accepted. Default is 'days'. + + Returns + ------- + None + Examples + -------- + >>> # Set the timespan to be 2017-07-17 00:00:00 plus 1 day + >>> import pytplot + >>> pytplot.timespan(1500249600, 1) + + >>> # The same as above, but using different inputs + >>> pytplot.timespan("2017-07-17 00:00:00", 24, keyword='hours') """ - - if keyword == 'days': + + if keyword == "days": dt *= 86400 - elif keyword == 'hours': + elif keyword == "hours": dt *= 3600 - elif keyword == 'minutes': + elif keyword == "minutes": dt *= 60 - elif keyword == 'seconds': + elif keyword == "seconds": dt *= 1 else: - logging.warning("Invalid 'keyword' option %s.\nEnum(None, 'hours', 'minutes', 'seconds', 'days')",keyword) - + logging.warning( + "Invalid 'keyword' option %s.\nEnum(None, 'hours', 'minutes', 'seconds', 'days')", + keyword, + ) + if not isinstance(t1, (int, float, complex)): t1 = time_double.time_double(t1) - t2 = t1+dt + t2 = t1 + dt xlim(t1, t2) - - return \ No newline at end of file + + return