Welcome to weather386’s documentation!¶
Module Documentation¶
- weather386.forecast.get_forecast(lat, long)[source]¶
Retrieves weather forecast data for a specified latitude and longitude using the NWS API.
This function sends a request to the National Weather Service (NWS) API and retrieves a variety of weather forecast data for the provided geographic coordinates. The data includes temperature, dewpoint, maximum and minimum temperatures, relative humidity, wind direction and speed, precipitation, and snowfall amounts. Each category of data is returned as a separate DataFrame within a dictionary.
Parameters: lat (float): Latitude of the location for the weather forecast. long (float): Longitude of the location for the weather forecast.
Returns: dict: A dictionary of pandas DataFrames, with keys representing different types of weather
data (‘temperature’, ‘dewpoint’, ‘maxTemperature’, ‘minTemperature’, ‘relativeHumidity’, ‘windDirection’, ‘windSpeed’, ‘precipitation’, ‘snowfall’). Each DataFrame contains the respective forecast data.
If the API request is unsuccessful, the function returns an empty dictionary. It’s recommended to check the returned data for emptiness to handle any potential API request failures.
- weather386.history.get_history(latitude, longitude)[source]¶
Retrieves historical weather data for a specified location using the Open-Meteo API.
This function queries the Open-Meteo API for historical weather data based on the provided latitude and longitude. It uses a cached and retry-enabled session for the API requests to handle potential network issues and improve performance. The function returns a DataFrame containing hourly weather data over a fixed historical period.
Parameters: latitude (float): Latitude of the location for which historical weather data is requested. longitude (float): Longitude of the location for which historical weather data is requested.
Returns: pandas.DataFrame: A DataFrame containing hourly historical weather data for the specified location.
Columns include ‘date’, ‘temperature_2m’, ‘relative_humidity_2m’, ‘dew_point_2m’, ‘precipitation’, ‘rain’, ‘snowfall’, and ‘wind_speed_10m’.
The function sets up a request session with caching and retry mechanisms, then sends a request to the Open-Meteo API with the specified parameters. The response is processed into a pandas DataFrame, with each column representing a different weather variable. The date column is timezone-localized to UTC.
Note: - The historical period for which data is retrieved is currently fixed within the function. - The function assumes the existence of the ‘openmeteo_requests’ custom module and
‘retry_requests’ for handling API requests.
- weather386.combined_graph.combined_graph(historical_df, forecast_df)[source]¶
Creates a combined plot with separate graphs for precipitation, temperature, and wind speed.
This function takes historical and forecasted weather data and plots three separate graphs on a single figure. Each graph represents a different aspect of the weather data: precipitation, temperature, and wind speed. The function utilizes specific graphing functions from the ‘weather386’ module for each of these aspects.
Parameters: historical_df (pandas.DataFrame): A DataFrame containing historical weather data.
Required columns include ‘precipitation’, ‘windSpeed’, and ‘temperature’.
- forecast_df (pandas.DataFrame): A DataFrame containing forecasted weather data.
Required columns are the same as for historical_df.
The function creates a figure with three subplots arranged vertically. It then calls the precip_graph, temp_graph, and wind_graph functions from the ‘weather386’ module, passing each a subplot Axes object along with the historical and forecasted DataFrames. The function adjusts the layout for better readability and displays the combined plot.
Note: This function relies on the ‘weather386’ module’s specific graphing functions. It assumes these functions are correctly implemented and available.
- weather386.expand.expand_df(row)[source]¶
Expands a single row of weather data into a DataFrame with hourly records.
This function takes a row from a DataFrame representing a single weather data record and expands it into a DataFrame with hourly intervals. It is particularly useful for expanding weather data that spans multiple hours into individual hourly records.
Parameters: row (pandas.Series): A row from a DataFrame, expected to contain the columns ‘validTime’ and ‘value’.
The ‘validTime’ field should be a string in the format “YYYY-MM-DDTHH:MM/PTnH”, where ‘n’ is the duration in hours.
Returns: pandas.DataFrame: A DataFrame with two columns: ‘validTime’ and ‘value’. The ‘validTime’ column
contains a range of datetime objects at hourly intervals, starting from the start time specified in the input row and continuing for the duration specified. The ‘value’ column is filled with the value from the input row.
The function parses the ‘validTime’ field to extract the start time and duration, then creates a range of datetime objects at hourly intervals. Each datetime object corresponds to a separate row in the returned DataFrame, and the ‘value’ column in each row is filled with the value from the input row.
- weather386.join_clean.join_clean(df_dict)[source]¶
Joins and cleans multiple weather data DataFrames.
This function takes a dictionary of DataFrames, each representing a different type of weather data, and combines them into a single DataFrame. It performs expansion of each DataFrame, conversion of temperature values to Fahrenheit (where applicable), and then merges them on a common time column.
Parameters: df_dict (dict): A dictionary where keys are strings representing the type of weather data
(e.g., ‘temperature’, ‘dewpoint’, ‘precipitation’, ‘windSpeed’) and values are pandas DataFrames containing the corresponding data.
Returns: pandas.DataFrame: A combined DataFrame with each weather data type as a column, aligned by the
‘validTime’ column. Temperature and dewpoint values are converted to Fahrenheit. precipitation is converted from mm to in.
Each DataFrame in the input dictionary is first expanded using the expand_df function. Then, for DataFrames representing temperature or dewpoint, values are converted from Celsius to Fahrenheit. Then, for the precipitation DataFrame, values are converted to inches from millimeters. The DataFrames are then merged into a single DataFrame on the ‘validTime’ column. If the ‘validTime’ column does not exist in any of the DataFrames, the merge may not align the data correctly.
- weather386.precip_graph.precip_graph(ax, historical_df, forecast_df)[source]¶
Plots precipitation data comparing forecast data with historical data.
This function takes a matplotlib Axes object and two DataFrames containing historical and forecasted precipitation data. It processes and visualizes the data as line plots, focusing on precipitation values across different hours of the day. The function aligns data by day-hour for direct comparison between the forecast and historical data.
Parameters: ax (matplotlib.axes.Axes): The matplotlib Axes object to plot on. It should be pre-initialized. historical_df (pandas.DataFrame): A DataFrame containing historical weather data. forecast_df (pandas.DataFrame): A DataFrame containing forecast weather data.
Returns: matplotlib.axes.Axes: The matplotlib Axes object with the plotted data.
The function first standardizes the column names in both DataFrames. It then filters the historical data to match the days present in the forecast data. The function plots the precipitation data for each hour of the day, represented in the ‘day_hour’ column, for the forecast data. Historical average precipitation is not plotted as it is often unhelpful. The plot is customized with appropriate labels, a legend, and adjusted axis limits. The x-axis represents ‘Month-Day-Hour’ in UTC, and the y-axis represents precipitation in inches.
- weather386.temp_graph.temp_graph(ax, historical_df, forecast_df)[source]¶
Plots temperature data comparing historical averages with forecast data.
This function takes two dataframes containing historical and forecasted temperature data, along with an Axes object for plotting. It processes the data to align by day-hour and plots both historical and forecasted temperature data on the same graph.
Parameters: ax (matplotlib.axes.Axes): The matplotlib Axes object to plot on. historical_df (pandas.DataFrame): Dataframe containing historical temperature data. forecast_df (pandas.DataFrame): Dataframe containing forecasted temperature data.
Returns: matplotlib.axes.Axes: The matplotlib Axes object with the plotted data.
- weather386.wind_graph.wind_graph(ax, historical_df, forecast_df)[source]¶
Creates a line plot comparing historical and forecasted wind speed data.
This function generates a plot on a provided Axes object, displaying wind speed data from both historical and forecasted sources. It aligns data by the hour of the day (UTC) for comparison and visualizes it using line plots.
Parameters: ax (matplotlib.axes.Axes): The matplotlib Axes object to plot on. It should be pre-initialized. historical_df (pandas.DataFrame): A DataFrame containing historical weather data. forecast_df (pandas.DataFrame): A DataFrame containing forecast weather data.
Returns: matplotlib.axes.Axes: The matplotlib Axes object with the plotted data.
The function first standardizes the column names in both DataFrames and then filters the historical data to match the days present in the forecast data. It plots the wind speed (‘windSpeed’) for each hour of the day, represented in the ‘day_hour’ column, for both historical and forecast data. The plot is customized with appropriate labels and a legend. The x-axis represents ‘Month-Day-Hour’ in UTC, and the y-axis represents wind speed in miles per hour (MPH).