Base classes for metadata and others

This module gathers the classes to handle metadata and snow surface property data. These classes are designed to be used in the SnowProfile class.

class snowprofile.classes.Person[source]

Bases: BaseModel

Class to describe a contact person

Fields:
field id: str | None = None
field name: str | None = None
field website: str | None = None
field comment: str | None = None
field additional_data: AdditionalData | None = None
class snowprofile.classes.Time[source]

Bases: BaseModel, BaseMergeable

Class to store the date and time of observation (and additional date/time considerations)

If left empty, the time zone will be automatically filled and the time zone is assumed to be UTC.

Fields:
field record_time: Annotated[datetime, BeforeValidator(func=force_utc, json_schema_input_type=PydanticUndefined), PlainSerializer(func=serialize_datetime, return_type=str | None, when_used=always)] = datetime.datetime(2026, 5, 5, 16, 3, 17, 734576)

Time of the observation or measurement (python datetime object).

Constraints:

  • func = <function serialize_datetime at 0x7b4f470b6050>

  • json_schema_input_type = PydanticUndefined

  • return_type = typing.Optional[str]

  • when_used = always

field record_period: Annotated[Tuple[datetime | None, datetime | None], BeforeValidator(func=force_utc_tuple, json_schema_input_type=PydanticUndefined), PlainSerializer(func=serialize_datetime_tuple, return_type=List[str | None] | None, when_used=always)] = (None, None)

Time period of the observation (tuple of two python datetime objects giving the start time and the end time).

Constraints:

  • func = <function serialize_datetime_tuple at 0x7b4f470b6c20>

  • json_schema_input_type = PydanticUndefined

  • return_type = typing.Optional[typing.List[typing.Optional[str]]]

  • when_used = always

field report_time: Annotated[datetime, BeforeValidator(func=force_utc, json_schema_input_type=PydanticUndefined), PlainSerializer(func=serialize_datetime, return_type=str | None, when_used=always)] | None = None

Reporting time of the observation (python datetime object).

field last_edition_time: Annotated[datetime, BeforeValidator(func=force_utc, json_schema_input_type=PydanticUndefined), PlainSerializer(func=serialize_datetime, return_type=str | None, when_used=always)] | None = None

Last edition time of the observation (python datetime object).

field comment: str | None = None

Comment on the date and time of observation (str)

field additional_data: AdditionalData | None = None

Field to store additional data for CAAML compatibility (customData), do not use.

class snowprofile.classes.Observer[source]

Bases: BaseModel, BaseMergeable

Class to store information about the observer and about the institution / lab.

source refers to the observation institution and person to the observer.

source_id

Unique identifier of the observation institution

source_name

Name of the observation institution

source_comment

Comment on the observation institution

contact_persons

The list of contact persons (or observers)

additional_data

Field to store additional data for CAAML compatibility (customData), do not use.

Fields:
field source_id: str | None = None
field source_name: str | None = None
field source_website: str | None = None
field source_comment: str | None = None
field source_additional_data: AdditionalData | None = None
field contact_persons: List[Person] = [Person(id=None, name=None, website=None, comment=None, additional_data=None)]
Constraints:

  • min_length = 1

class snowprofile.classes.Location[source]

Bases: BaseModel, BaseMergeable

Class to store information on the measurement location (geographical position and details of the observation site).

The required field is name.

id

Unique identifier of the geographical position

name

The name of the observation location (str)

latitude

Latitude (degrees north)

longitude

Longitude (degrees East)

comment

Free comment on the location (str)

elevation

Point elevation (meters above sea level)

aspect

Slope aspect (degrees, int. between 0 and 360)

slope

Slope inclination (degrees, int. between 0 and 90)

point_type

A point type description (str)

country

Country code according to ISO3166

region

Region (detail in the country, optional, str)

additonal_data

Field to store additional data for CAAML compatibility (customData), do not use.

Fields:
Validators:
field id: str | None = None
field name: str [Required]
field point_type: str | None = None
field aspect: int | None = None
Constraints:

  • ge = 0

  • le = 360

field elevation: int | None = None
field slope: int | None = None
Constraints:

  • ge = 0

  • lt = 90

field latitude: float | None = None
field longitude: float | None = None
field country: Literal['AD', 'AE', 'AF', 'AG', 'AL', 'AM', 'AO', 'AR', 'AT', 'AU', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BW', 'BY', 'BZ', 'CA', 'CD', 'CF', 'CG', 'CH', 'CI', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FM', 'FR', 'GA', 'GB', 'GD', 'GE', 'GH', 'GL', 'GM', 'GN', 'GQ', 'GR', 'GT', 'GW', 'GY', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IN', 'IQ', 'IR', 'IS', 'IT', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MR', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NE', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NZ', 'OM', 'PA', 'PE', 'PG', 'PH', 'PK', 'PL', 'PS', 'PT', 'PW', 'PY', 'QA', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SY', 'SZ', 'TD', 'TG', 'TH', 'TJ', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'UM', 'US', 'UY', 'UZ', 'VC', 'VE', 'VN', 'VU', 'WF', 'WS', 'YE', 'ZA', 'ZM', 'ZW'] | None = None
Validated by:

  • _preprocess_country

field region: str | None = None
field comment: str | None = None
field additional_data: AdditionalData | None = None
class snowprofile.classes.Weather[source]

Bases: BaseModel, BaseMergeable

Class to store the weather at time of observation.

cloudiness
The cloudiness in octas (from 0 to 8) or in the form of METAR code:

  • CLR: clear

  • FEW: few clouds

  • SCT: scattered

  • BKN: broken

  • OVC: overcast

  • X: precipitation

precipitation
Precipitation type, in the form of METAR code:

  • Nil: No precipitation

  • DZ: Drizzle

  • RA: Rain

  • SN: Snow (snow flakes)

  • SG: Snow grains (very small opaque grains, generally less than 1 mm)

  • IC: Ice crystals

  • PE: Ice pellets

  • GR: Hail (Grèle)

  • GS: Small hail and/or graupel (Grésil, grains below 5mm)

  • UP: Unknown precipitation type

  • RASN: Rain and snow

  • FZRA: Freezing rain

The precipitation type can be preceded by ‘-’ for light intensity or ‘+’ for heavy intensity. The qualifier without +/- is moderate intensity. For a definition and pictures of the precipitation types, see e.g. the International Cloud Atlas

air_temperature

Temperature of air (°C)

air_humidity

Relative humidity (%)

wind_speed

Wind speed (m/s)

wind_direction

Wind direction (in degree, from 0 to 360)

air_temperature_measurement_height

Height of the air temperature measurement and humidity measurement (m)

wind_measurement_height

Height of the wind speed and direction measurement (m)

comment

Free comment on the weather

additonal_data

Field to store additional data for CAAML compatibility (customData), do not use.

Fields:
Validators:
field cloudiness: Literal['CLR', 'FEW', 'SCT', 'BKN', 'OVC', 'X'] | None = None
Validated by:

  • _preprocess_cloudiness

field precipitation: Literal['-DZ', 'DZ', '+DZ', '-RA', 'RA', '+RA', '-SN', 'SN', '+SN', '-SG', 'SG', '+SG', '-IC', 'IC', '+IC', '-PE', 'PE', '+PE', '-GR', 'GR', '+GR', '-GS', 'GS', '+GSUP', 'Nil', 'RASN', 'FZRA'] | None = None
field air_temperature: float | None = None
field air_humidity: float | None = None
Constraints:

  • ge = 0

  • le = 100

field wind_speed: float | None = None
Constraints:

  • ge = 0

field wind_direction: int | None = None
Constraints:

  • ge = 0

  • le = 360

field air_temperature_measurement_height: float | None = None
Constraints:

  • gt = 0

field wind_measurement_height: float | None = None
Constraints:

  • gt = 0

field comment: str | None = None
field additional_data: AdditionalData | None = None
class snowprofile.classes.SurfaceConditions[source]

Bases: BaseModel, BaseMergeable

Class to describe the snow surface conditions.

surface_roughness
Surface roughness according to Fierz et al., 2009:

  • rsm: smooth

  • rwa: wavy (ripples)

  • rcv: concave furrows (ablation hollows, sun cups, penitents, due to melt or sublimation)

  • rcx: conex furrows (rain or melt groves)

  • rrd: random furrows (due to wind erosion)

surface_wind_features
Wind features observable at the surface:

  • No observable wind bedforms

  • Snowdrift around obstacles

  • Snow ripples

  • Snow waves

  • Barchan dunes

  • Dunes

  • Loose patches

  • Pits

  • Snow steps

  • Sastrugi

  • mixed

  • other

surface_melt_rain_features
Other surface features:

  • Sun cups

  • Penitents

  • Melt or rain furrows

  • other

surface_features_amplitude

Amplitude of the surface features (m)

surface_features_amplitude_max

Maximum amplitude of the surface features (m)

surface_features_amplitude_min

Minimum amplitude of the surface features (m)

surface_features_wavelength

Wavelength of the surface features (m)

surface_features_wavelength_max

Maximum wavelength of the surface features (m)

surface_features_wavelength_min

Minimum wavelength of the surface features (m)

surface_features_aspect

Orientation of surface features (degree, from 0 to 360)

comment

Free comment on surface conditions

lap_presence
Indication of the presence of light absorbing particule at the snow surface. Values among:

  • No LAP

  • Black Carbon

  • Dust

  • Mixed

  • other

surface_temperature

Snow surface temperature (°C)

surface_temperature_measurement_method
Measurement method for the surface temperature:

  • Thermometer

  • Hemispheric IR

  • IR thermometer

  • other

surface_albedo

Snow surface albedo (0 -1)

surface_albedo_comment

Free comment on the snow albedo

spectral_albedo

Spectral albedo data, see snowprofile.classes.SpectralAlbedo

spectral_albedo_comment

Free comment on the spectral snow albedo

penetration_foot

Depth of snowpack penetration by foot (float, m)

penetration_ram

Depth of snowpack penetration with the ramsonde (probe alone) (float, m)

penetration_ski

Depth of snowpack penetration by ski (float, m)

additonal_data

Field to store additional data for CAAML compatibility (customData), do not use.

Fields:
field surface_roughness: Literal['rsm', 'rwa', 'rcv', 'rcx', 'rrd'] | None = None
field surface_wind_features: Literal['No observable wind bedforms', 'Snowdrift around obstacles', 'Snow ripples', 'Snow waves', 'Barchan dunes', 'Dunes', 'Loose patches', 'Pits', 'Snow steps', 'Sastrugi', 'mixed', 'other'] | None = None
field surface_melt_rain_features: Literal['Sun cups', 'Penitents', 'Melt or rain furrows', 'other'] | None = None
field surface_features_amplitude: float | None = None
Constraints:

  • gt = 0

field surface_features_amplitude_min: float | None = None
Constraints:

  • gt = 0

field surface_features_amplitude_max: float | None = None
Constraints:

  • gt = 0

field surface_features_wavelength: float | None = None
Constraints:

  • gt = 0

field surface_features_wavelength_min: float | None = None
Constraints:

  • gt = 0

field surface_features_wavelength_max: float | None = None
Constraints:

  • gt = 0

field surface_features_aspect: int | None = None
Constraints:

  • ge = 0

  • le = 360

field lap_presence: Literal['No LAP', 'Black Carbon', 'Dust', 'Mixed', 'other'] | None = None
field surface_temperature: float | None = None
field surface_temperature_measurement_method: Literal['Thermometer', 'Hemispheric IR', 'IR thermometer', 'other'] | None = None
field surface_albedo: float | None = None
field surface_albedo_comment: str | None = None
field spectral_albedo: SpectralAlbedo | None = None
field penetration_ram: float | None = None
Constraints:

  • ge = 0

field penetration_foot: float | None = None
Constraints:

  • ge = 0

field penetration_ski: float | None = None
Constraints:

  • ge = 0

field comment: str | None = None
field additional_data: AdditionalData | None = None
class snowprofile.classes.Environment[source]

Bases: BaseModel, BaseMergeable

Description of the site environment, which is independant of the date and time of observation.

solar_mask

The solar mask at the observation site. snowprofile.classes.SolarMask object.

solar_mask_method_of_measurement
Measurement method for the solar mask

  • Theodolite

  • Manual measurement

  • From DTM

  • From DSM

  • other

solar_mask_uncertainty

Quantitative uncertainty of the solar mask measurement.

solar_mask_quality

Qualitative quality of the solar mask measurement

solar_mask_comment

Free comment on the solar mask measurement

bed_surface
Characterization of the surface below the snowpack:

  • Sea ice

  • Glacier

  • Ice cap

  • Fresh water ice

  • Wetlands

  • Grassland

  • Shrubs

  • Rocks

  • Bare ground

  • Needle litter

  • Broadleaf litter

  • Artificial surface

  • Mixed

  • Other

bed_surface_comment

Free comment on the bed surface

litter_thickness

Thickness of the litter, if applicable (m)

ice_thickness

Thickness of the ice, if applicable (m)

low_vegetation_height

Height of the low vegetation, if applicable (m)

LAI

Leaf area index, measured at the vegetation peak (summer, m2/m2).

forest_presence
Type of forest, if applicable:

  • Open Area

  • Broadleaf forest

  • Needle forest

  • Mixed forest

  • Shrubs

  • Other

forest_presence_comment

Free comment to describe the forest

sky_view_factor

In case of forest site, the sky view factor (0 - 1)

tree_height

In case of forest site, the mean height of trees (m).

solar_mask_additional_data

Field to store additional data for CAAML compatibility (customData), do not use.

Fields:
field solar_mask: SolarMask | None = None

The spectral albedo data.

field solar_mask_method_of_measurement: Literal['Theodolite', 'Manual measurement', 'From DTM', 'From DSM', 'other'] | None = None
field solar_mask_uncertainty: float | None = None
Constraints:

  • ge = 0

field solar_mask_quality: Literal['Good', 'Uncertain', 'Low', 'Bad'] | None = None
field solar_mask_comment: str | None = None
field bed_surface: Literal['Sea ice', 'Glacier', 'Ice cap', 'Fresh water ice', 'Wetlands', 'Grassland', 'Shrubs', 'Rocks', 'Bare ground', 'Needle litter', 'Broadleaf litter', 'Artificial surface', 'Mixed', 'Other'] | None = None
field bed_surface_comment: str | None = None
field litter_thickness: float | None = None
Constraints:

  • ge = 0

field ice_thickness: float | None = None
Constraints:

  • ge = 0

field low_vegetation_height: float | None = None
Constraints:

  • ge = 0

field LAI: float | None = None
Constraints:

  • ge = 0

field forest_presence: Literal['Open Area', 'Broadleaf forest', 'Needle forest', 'Mixed forest', 'Shrubs', 'Other'] | None = None
field forest_presence_comment: str | None = None
field sky_view_factor: float | None = None
Constraints:

  • ge = 0

  • le = 1

field tree_height: float | None = None
Constraints:

  • ge = 0

field solar_mask_additional_data: AdditionalData | None = None
class snowprofile.classes.SolarMask[source]

Bases: BaseModel, BaseData

Class to store solar mask

The data contains:

  • azimuth (degrees from north)

  • elevation (in degrees from horizontal)

class snowprofile.classes.SpectralAlbedo[source]

Bases: BaseModel, BaseData, BaseMergeable

Class to store spectral albedo data

The data contains:

  • min_wavelength (nm)

  • max_wavelength (nm)

  • albedo (between 0 and 1)

and optionnally uncertainty (same unit as data) and/or quality (see Describe data uncertainty and quality).

Fields:
field comment: str | None = None