Struct ClimateLazyFrame 

pub struct ClimateLazyFrame {
    pub frame: LazyFrame,
}

A wrapper around a Polars LazyFrame specifically for Meteostat climate data.

This struct provides methods tailored for common operations on climate normals datasets, such as filtering by period and month, while retaining the benefits of lazy evaluation. It also includes methods to collect the results into Rust structs.

Instances are typically obtained via crate::Meteostat::climate.

Errors

Operations that trigger computation on the underlying LazyFrame (e.g., calling .collect(), or the collection methods here) can potentially return a polars::prelude::PolarsError (wrapped as MeteostatError::PolarsError).

The collect_single_climate method returns MeteostatError::ExpectedSingleRow if the frame does not contain exactly one row upon collection.

The initial creation via crate::Meteostat::climate methods can return a MeteostatError if data fetching or station lookup fails.

Fields

frame: LazyFrame

The underlying Polars LazyFrame containing the climate data.

Implementations

impl ClimateLazyFrame

pub fn filter(&self, predicate: Expr) -> ClimateLazyFrame

Filters the climate data based on a Polars predicate expression.

This method allows applying arbitrary filtering logic supported by Polars. It returns a new ClimateLazyFrame with the filter applied lazily. The original ClimateLazyFrame remains unchanged.

Arguments

• predicate - A Polars Expr defining the filtering condition.

Returns

A new ClimateLazyFrame representing the filtered data.

Example

use polars::prelude::{col, lit, PolarsError};

let client = Meteostat::new().await?;
let berlin = LatLon(52.52, 13.40);

let climate_lazy = client.climate().location(berlin).call().await?;

// Filter for months in the second half of the year (July - December)
// Ensure the literal type matches the column type or can be cast.
let summer_autumn_climate = climate_lazy.filter(col("month").gt(lit(6i64))); // Use i64 if column is i64

// Collect the results to see the data
let df = summer_autumn_climate.frame.collect()?;
println!("{}", df);

Errors

While this method itself doesn’t typically error, subsequent operations like .collect() might return a polars::prelude::PolarsError.

pub fn get_at( &self, start_year: Year, end_year: Year, month: u32, ) -> ClimateLazyFrame

Filters the climate data to get the normals for a specific period and month.

This is a convenience method that filters the data based on the start_year, end_year, and month columns, which are standard in Meteostat climate normals data. It assumes these columns are numerical in the underlying frame.

Arguments

• start_year - The starting year of the climate normal period (e.g., Year(1991)).
• end_year - The ending year of the climate normal period (e.g., Year(2020)).
• month - The month number (1-12).

Returns

A new ClimateLazyFrame filtered to the specified period and month. Typically, collecting this frame should result in zero or one row.

Example

use polars::prelude::PolarsError;

let client = Meteostat::new().await?;
let london = LatLon(51.50, -0.12); // London location

let climate_lazy = client.climate().location(london).call().await?;

// Get climate normals for July for the 1991-2020 period
let july_normals_lazy = climate_lazy.get_at(Year(1991), Year(2020), 7);

// Collect the result (should be one row if data exists)
let df = july_normals_lazy.frame.collect()?;
if df.height() == 1 {
    println!("July 1991-2020 Normals:\n{}", df);
} else {
    println!("No 1991-2020 climate normals found for July at the nearest station.");
}

Errors

May eventually lead to a polars::prelude::PolarsError during computation (e.g., .collect()).

pub fn collect_climate(&self) -> Result<Vec<Climate>, MeteostatError>

Executes the lazy query and collects the results into a Vec<Climate>.

This method triggers the computation defined by the LazyFrame (including any previous filtering operations) and maps each resulting row to a Climate struct. Rows where the essential ‘start_year’, ‘end_year’, or ‘month’ columns are missing or invalid are skipped.

Returns

A Result containing a Vec<Climate> on success, or a MeteostatError if the computation or mapping fails (e.g., MeteostatError::PolarsError).

Example

use polars::prelude::PolarsError;

let client = Meteostat::new().await?;
let paris = LatLon(48.85, 2.35);

let climate_lazy = client
    .climate()
    .location(paris)
    .call()
    .await?;

// Collect all available climate normals
let climate_vec: Vec<Climate> = climate_lazy.collect_climate()?;

println!("Collected {} climate normal records.", climate_vec.len());
if let Some(first_normal) = climate_vec.first() {
    println!("First record: {:?}", first_normal);
}

pub fn collect_single_climate(&self) -> Result<Climate, MeteostatError>

Executes the lazy query, expecting exactly one row, and collects it into a Climate struct.

This is useful after filtering the frame down to a single expected record, for example using get_at().

Returns

A Result containing the single Climate struct on success.

Errors

Returns MeteostatError::ExpectedSingleRow if the collected DataFrame does not contain exactly one row. Returns MeteostatError::PolarsError if the computation fails. Returns other potential mapping errors if the single row cannot be converted.

Example

use polars::prelude::PolarsError;

let client = Meteostat::new().await?;
let station_id = "10384"; // Berlin Tempelhof

let climate_lazy = client.climate().station(station_id).call().await?;

// Get data for a specific period and month
let target_start = Year(1991);
let target_end = Year(2020);
let target_month = 8; // August

let single_climate_lazy = climate_lazy.get_at(target_start, target_end, target_month);

// Collect the single expected row
match single_climate_lazy.collect_single_climate() {
    Ok(climate_data) => {
        println!("Collected single climate normal: {:?}", climate_data);
        assert_eq!(climate_data.start_year, 1991);
        assert_eq!(climate_data.end_year, 2020);
        assert_eq!(climate_data.month, 8); // Verify correct month
    },
    Err(MeteostatError::ExpectedSingleRow { actual }) => {
         println!("Expected 1 row, but found {}. Climate normal might be missing.", actual);
         // Handle missing data case if necessary
         // assert_eq!(actual, 0); // Or assert based on expected availability
    },
    Err(e) => return Err(e), // Propagate other errors
}

Trait Implementations

impl Clone for ClimateLazyFrame

fn clone(&self) -> ClimateLazyFrame

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.