Core Types

The vibe_core.data.core_types provides a set of foundation classes and utilities to represent and manipulate various types of data used in the FarmVibes.AI. The BaseVibe class is the base class for all FarmVibes.AI types, and provides a common interface for data access and manipulation. The DataVibe class represents a data object in FarmVibes.AI, and includes properties such as a unique identifier, a time range, a bounding box, and a geometry. Other classes, such as TimeSeries, DataSummaryStatistics, DataSequence, inherit from DataVibe and provide additional functionality for specific data types.

The module is designed to handle a wide range of data types, including geospatial data, time series data, and more. It also provides utility functions and classes to help with tasks such as generating unique identifiers, validating data types, and parsing type specifications.

Hierarchy

classDiagram class AssetVibe { } class BaseVibe { } class CarbonOffsetInfo { } class DataSequence { } class DataSummaryStatistics { } class DataVibe { } class ExternalReference { } class ExternalReferenceList { } class FoodFeatures { } class FoodVibe { } class GHGFlux { } class GHGProtocolVibe { } class GeometryCollection { } class OrdinalTrendTest { } class ProteinSequence { } class PydanticAssetVibe { } class RasterPixelCount { } class TimeSeries { } class Tmp { } class TypeDictVibe { } class TypeParser { } class UnresolvedDataVibe { } PydanticAssetVibe --|> AssetVibe CarbonOffsetInfo --|> DataVibe DataSequence --|> DataVibe DataSummaryStatistics --|> DataVibe DataVibe --|> BaseVibe ExternalReference --|> DataVibe ExternalReferenceList --|> DataVibe FoodFeatures --|> DataVibe FoodVibe --|> BaseVibe GHGFlux --|> DataVibe GHGProtocolVibe --|> DataVibe GeometryCollection --|> DataVibe OrdinalTrendTest --|> DataVibe ProteinSequence --|> DataVibe RasterPixelCount --|> DataVibe TimeSeries --|> DataVibe UnresolvedDataVibe --|> BaseVibe

Documentation

class vibe_core.data.core_types.AssetVibe(reference, type, id)

Bases: object

Represents an asset in FarmVibes.AI.

id: str: A string representing the ID of the asset.

property local_path: str

Returns the local path of the asset.

If the asset is local, this method returns the local path of the asset. If the asset is remote, it downloads the asset to a temporary directory (if not previously downloaded) and returns the local path of the downloaded file.

Returns:: The local path of the asset.

path_or_url: str: A string representing the path or URL of the asset.

type: Optional[str]: An optional string representing the MIME type of the asset.

property url: str

Returns the URL of the asset.

If the asset is local, this method returns the absolute URI of the local path. Otherwise, it returns the original path or URL of the asset.

Returns:: The URL of the asset.

class vibe_core.data.core_types.BaseVibe

Bases: object

Represents a base class for FarmVibes.AI types.

classmethod from_dict(data)

A class method that creates a BaseVibe object from a dictionary of values.

This method takes a dictionary of values as input and returns a BaseVibe object. If the class schema includes a bounding box (bbox) property, this method calculates the bounding box from the geometry property using the shapely.geometry library. If the geometry property is missing, a ValueError is raised. Otherwise, this method creates a new instance of the Pydantic model and returns it.

Parameters:: data (Dict[str, Any]) – A dictionary of values to create the BaseVibe object from.
Returns:: BaseVibe – A BaseVibe object.
Raises:: ValueError – If the geometry property is missing and the class schema includes a bbox property.

property hash_id: str

Returns the hash ID of the object.

If the class has an id attribute that is a non-empty string, this method returns it. Otherwise, it calculates the SHA-256 hash of the JSON representation of the object and returns the hexadecimal digest.

Returns:: The hash ID of the object.

class vibe_core.data.core_types.CarbonOffsetInfo(id, time_range, geometry, assets, carbon)

Bases: DataVibe

Represents carbon offset information.

carbon: str: The carbon offset.

class vibe_core.data.core_types.DataSequence(id, time_range, geometry, assets, asset_order=<factory>, asset_time_range=<factory>, asset_geometry=<factory>)

Bases: DataVibe

Represents a sequence of data assets in FarmVibes.AI.

add_asset(asset, time_range, geometry)

Adds an asset to the sequence.

Parameters:

asset (AssetVibe) – The asset to add to the sequence.
time_range (Tuple[datetime, datetime]) – The time range of the asset.
geometry (BaseGeometry) – The geometry of the asset.

add_item(item)

Adds an item to the sequence.

Parameters:: item (DataVibe) – The item to be added to the sequence.

get_ordered_assets(order_by=None)

Gets a list of assets in the sequence, ordered by the provided dictionary.

Parameters:: order_by (Optional[Dict[str, Any]], default: None) – A dictionary mapping asset IDs to their order in the sequence. If None, the assets will be ordered by their default order in the sequence.
Returns:: List[AssetVibe] – A list of assets in the sequence, ordered by the provided dictionary.

asset_geometry: Dict[str, BaseGeometry]: A dictionary mapping asset IDs to their geometry.

asset_order: Dict[str, int]: A dictionary mapping asset IDs to their order in the sequence.

asset_time_range: Dict[str, Tuple[datetime, datetime]]: A dictionary mapping asset IDs to their time range.

idx: int: Number of data objects in the sequence.

class vibe_core.data.core_types.DataSummaryStatistics(id, time_range, geometry, assets)

Bases: DataVibe

Represents a data summary statistics object in FarmVibes.AI.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.DataVibe(id, time_range, geometry, assets)

Bases: BaseVibe

Represents a data object in FarmVibes.AI.

classmethod clone_from(src, id, assets, **kwargs)

Creates a new DataVibe object with updated fields.

This method takes a source DataVibe object, a new id string, a list of new AssetVibe objects, and any additional keyword arguments to update the fields of the source object. It returns a new DataVibe object with the updated fields.

Parameters:

cls – The class of the new DataVibe object.
src (DataVibe) – The source DataVibe object to clone.
id (str) – The new id string for the cloned object.
assets (List[AssetVibe]) – The new list of AssetVibe objects for the cloned object.
kwargs (Any) – Additional keyword arguments to update the fields of the cloned object.

Returns:

A new DataVibe object with the updated fields.

SKIP_FIELDS: ClassVar[Tuple[str, ...]] = ('id', 'assets', 'hash_id', 'bbox'): A tuple containing the fields to skip when calculating the hash ID of the object.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.ExternalReference(id, time_range, geometry, assets, url)

Bases: DataVibe

Represents a single external reference in FarmVibes.AI.

url: str: The URL representing the external reference.

class vibe_core.data.core_types.ExternalReferenceList(id, time_range, geometry, assets, urls)

Bases: DataVibe

Represents a list of external references in FarmVibes.AI.

urls: List[str]: A list of URLs.

class vibe_core.data.core_types.FoodFeatures(id, time_range, geometry, assets)

Bases: DataVibe

Represents the features of a food in FarmVibes.AI.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.FoodVibe(dietary_fiber, magnesium, potassium, manganese, zinc, iron, copper, protein, trp, thr, ile, leu, lys, met, cys, phe, tyr, val, arg, his, fasta_sequence, protein_families, food_group)

Bases: BaseVibe

Represents a food object in FarmVibes.AI.

arg: float: The amount of arginine in grams.

copper: float: The amount of copper in milligrams.

cys: float: The amount of cysteine in grams.

dietary_fiber: float: The amount of dietary fiber in grams.

fasta_sequence: List[str]: A list with the amino acid sequence of the protein.

food_group: str: The food group the food belongs to.

his: float: The amount of histidine in grams.

ile: float: The amount of isoleucine in grams.

iron: float: The amount of iron in milligrams.

leu: float: The amount of leucine in grams.

lys: float: The amount of lysine in grams.

magnesium: float: The amount of magnesium in milligrams.

manganese: float: The amount of manganese in milligrams.

met: float: The amount of methionine in grams.

phe: float: The amount of phenylalanine in grams.

potassium: float: The amount of potassium in milligrams.

protein: float: The amount of protein in grams.

protein_families: List[str]: A list with the protein families associated to the food.

thr: float: The amount of threonine in grams.

trp: float: The amount of tryptophan in grams.

tyr: float: The amount of tyrosine in grams.

val: float: The amount of valine in grams.

zinc: float: The amount of zinc in milligrams.

class vibe_core.data.core_types.GHGFlux(id, time_range, geometry, assets, scope, value, description)

Bases: DataVibe

Represents a greenhouse gas (GHG) flux in FarmVibes.AI.

description: Optional[str]: An optional description of the GHG flux.

scope: str: The scope of the GHG flux.

value: float: The value of the GHG flux.

class vibe_core.data.core_types.GHGProtocolVibe(id, time_range, geometry, assets, cultivation_area, total_yield, soil_texture_class, soil_clay_content, practice_adoption_period, burn_area, soil_management_area, urea_amount=0.0, synthetic_fertilizer_amount=0.0, synthetic_fertilizer_nitrogen_ratio=0.0, limestone_calcite_amount=0.0, limestone_dolomite_amount=0.0, gypsum_amount=0.0, organic_compound_amount=0.0, manure_amount=0.0, manure_birds_amount=0.0, organic_other_amount=0.0, dry_matter_amount=0.0, is_dry_matter_fermented=False, vinasse_amount=0.0, filter_cake_amount=0.0, filter_cake_application_area=0.0, green_manure_amount=0.0, green_manure_grass_amount=0.0, green_manure_legumes_amount=0.0, soil_preparation='', water_regime='', diesel_type='DIESEL', diesel_amount=0.0, gasoline_amount=0.0, ethanol_amount=0.0, transport_diesel_type='DIESEL', transport_diesel_amount=0.0, current_land_use='conventional_crops', previous_land_use='conventional_crops', biome='')

Bases: DataVibe

Represents the inputs to Green House Gas fluxes estimation workflows.

This is a dataclass that has many attributes, due to the nature of the calculations proposed by the GHG protocol methodology. Not all attributes are required. Below we describe all of them, as well as the units they should be in.

biome: str = '': The biome of the field (can be one of the following “US_FOREST”, “BRAZIL_AMAZON_FOREST”, “BRAZIL_AMAZON_SAVANNA”, “BRAZIL_CERRADO”, “BRAZIL_PANTANAL”, “BRAZIL_CAATINGA”, “BRAZIL_MATA_ATLANTICA”, or “BRAZIL_PAMPA”).

burn_area: Optional[float]: The area of the field that is burned in hectares.

cultivation_area: float: The area of the field that is cultivated in hectares.

current_land_use: str = 'conventional_crops': The current land use of the field (can be one of the following: “conventional_crops”, “direct_seeding”, “sugarcane_with_burning”, or “sugarcane_without_burning”).

diesel_amount: Optional[float] = 0.0: The amount of diesel used in mechanical operations in the field in liters per hectare.

diesel_type: Optional[str] = 'DIESEL': The type of diesel used in the field.

dry_matter_amount: Optional[float] = 0.0: The amount of dry matter applied to the field in kilograms per hectare.

ethanol_amount: Optional[float] = 0.0: The amount of ethanol used in mechanical operations in the field in liters per hectare.

filter_cake_amount: Optional[float] = 0.0: The amount of filter cake applied to the field in kilograms per hectare.

filter_cake_application_area: Optional[float] = 0.0: The area of the field that is applied with filter cake in hectares.

gasoline_amount: Optional[float] = 0.0: The amount of gasoline used in mechanical operations in the field in liters per hectare.

green_manure_amount: Optional[float] = 0.0: The amount of green manure applied to the field in kilograms per hectare.

green_manure_grass_amount: Optional[float] = 0.0: The amount of green manure grass applied to the field in kilograms per hectare.

green_manure_legumes_amount: Optional[float] = 0.0: The amount of green manure legumes applied to the field in kilograms per hectare.

gypsum_amount: Optional[float] = 0.0: The amount of gypsum applied to the field in kilograms per hectare.

is_dry_matter_fermented: Optional[bool] = False: Whether the dry matter is fermented.

limestone_calcite_amount: Optional[float] = 0.0: The amount of limestone calcite applied to the field in kilograms per hectare.

limestone_dolomite_amount: Optional[float] = 0.0: The amount of limestone dolomite applied to the field in kilograms per hectare.

manure_amount: Optional[float] = 0.0: The amount of manure applied to the field in kilograms per hectare.

manure_birds_amount: Optional[float] = 0.0: The amount of manure from birds applied to the field in kilograms per hectare.

organic_compound_amount: Optional[float] = 0.0: The amount of organic compound applied to the field in kilograms per hectare.

organic_other_amount: Optional[float] = 0.0: The amount of other organic fertilizer applied to the field in kilograms per hectare.

practice_adoption_period: Optional[int]: The number of years that the practice has been adopted.

previous_land_use: str = 'conventional_crops': The previous land use of the field (can be one of the following: “conventional_crops”, “direct_seeding”, “sugarcane_with_burning”, “native”, “sugarcane_without_burning”).

soil_clay_content: Optional[float]: The clay content of the soil in percentage.

soil_management_area: Optional[float]: The area of the field that is managed in hectares.

soil_preparation: Optional[str] = '': Whether the soil uses “early” or “conventional” preparation.

soil_texture_class: Optional[str]: The texture class of the soil (one of the following: “sand”, “clay”, or “silt”).

synthetic_fertilizer_amount: Optional[float] = 0.0: The amount of synthetic fertilizer applied to the field in kilograms per hectare.

synthetic_fertilizer_nitrogen_ratio: Optional[float] = 0.0: The nitrogen ratio of the synthetic fertilizer applied to the field in percentage.

total_yield: float: The total yield of the field in tonnes.

transport_diesel_amount: Optional[float] = 0.0: Amount of diesel used in transporting produce from farm to market in liters per hectare.

transport_diesel_type: Optional[str] = 'DIESEL': The type of diesel used in transporting produce from the farm to the market.

urea_amount: Optional[float] = 0.0: The amount of urea applied to the field in kilograms per hectare.

vinasse_amount: Optional[float] = 0.0: The amount of vinasse applied to the field in cubic meters per hectare.

water_regime: Optional[str] = '': The water regime of the field.

class vibe_core.data.core_types.GeometryCollection(id, time_range, geometry, assets)

Bases: DataVibe

Represents a geometry collection in FarmVibes.AI.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.OrdinalTrendTest(id, time_range, geometry, assets, p_value, z_score)

Bases: DataVibe

Represents a trend test (Chochan-Armitage) result object in FarmVibes.AI.

class vibe_core.data.core_types.ProteinSequence(id, time_range, geometry, assets)

Bases: DataVibe

Represents a protein sequence in FarmVibes.AI.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.RasterPixelCount(id, time_range, geometry, assets)

Bases: DataVibe

Represents a data object in FarmVibes.AI that stores the pixel count of a raster.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.TimeSeries(id, time_range, geometry, assets)

Bases: DataVibe

Represents a time series data object in FarmVibes.AI.

assets: List[AssetVibe]: A list of AssetVibe objects of the assets associated with the data object.

bbox: Tuple[float, float, float, float]: A BBox representing the bounding box of the data object. This field is calculated from the geometry property using the shapely.geometry library.

geometry: Dict[str, Any]: A dictionary representing the geometry of the data object.

id: str: A string representing the unique identifier of the data object.

time_range: Tuple[datetime, datetime]: A TimeRange representing the timestamps of to the beginning and end of sample.

class vibe_core.data.core_types.TypeDictVibe

Bases: Dict[str, Union[Type[BaseVibe], Type[List[BaseVibe]]]]

A dictionary subclass used for type validation in FarmVibes.AI.

classmethod validate(v)

Validates a dictionary of values against FarmVibes.AI types.

This method takes a dictionary of values as input and returns a BaseVibe object. It validates each value in the dictionary against FarmVibes.AI types using the TypeParser class. If a value is not a FarmVibes.AI type, a ValueError is raised.

Parameters:: v (Any) – A dictionary of values to validate.
Returns:: BaseVibe – A BaseVibe object.
Raises:: ValueError – If a value in the dictionary is not a FarmVibes.AI type.

class vibe_core.data.core_types.TypeParser

Bases: object

A class that provides a method for parsing type specifications in FarmVibes.AI.

It is used to parse the type specifications of ports in BaseVibe subclasses.

classmethod parse(typespec)

Parses a type specification string and returns a BaseVibe or a List[BaseVibe].

It first checks if the type specification string includes inheritance, and if so, returns an UnresolvedDataVibe object. Otherwise, it extracts the container and data IDs from the type specification string and retrieves the corresponding BaseVibe subclass from the data_registry. If the container or data ID is not supported, a ValueError is raised.

Parameters:

typespec (str) – A string representing the type specification.

Returns:

Union[Type[BaseVibe], Type[List[BaseVibe]]] – A BaseVibe or a List[BaseVibe] object.

Raises:

ValueError – If the container ID is not supported or the data ID is not a BaseVibe subclass.
KeyError – If the data ID is not found in the data_registry.

container_group: int = 1: The group in the regular expression pattern that matches thecontainer type.

inherit_pattern = re.compile('\\s*\\@INHERIT\\((.*)\\)\\s*'): A regular expression pattern to parse type specifications that inherit from other ports.

logger: Logger = <Logger vibe_core.data.core_types.TypeParser (WARNING)>: A logger for the class.

supported_container_types: List[str] = ['List']: A list of supported container types.

type_group: int = 2: The group in the regular expression pattern that matches the type.

type_pattern: re.Pattern[str] = re.compile('((\\w+)\\[)?(\\w+)\\]?'): A regular expression pattern to parse type specifications.

class vibe_core.data.core_types.UnresolvedDataVibe

Bases: Type[BaseVibe], BaseVibe

Meta type that is equivalent to Python’s type built-in.

The output of this class is a new type, not a regular object. This is used internally by FarmVibes.AI and, in general, should never be instantiated. In fact, even if this is instantiated, there’s nothing useful that could be done with an instance of this (which, again, is a new Type).

vibe_core.data.core_types.gen_guid()

Generates a random UUID as a string.

Returns:: A random UUID as a string.

vibe_core.data.core_types.gen_hash_id(name, geometry, time_range)

Generates a hash ID based on a name, a geometry, and a time range.

Parameters:

name (str) – The name associated with the hash ID.
geometry (Union[BaseGeometry, Dict[str, Any]]) – The geometry associated with the hash ID, either as a BaseGeometry object or as a dictionary.
time_range (Tuple[datetime, datetime]) – The time range associated with the hash ID, as a tuple of two datetime objects (start, end).

Returns:

A hash ID as a hexadecimal string.

vibe_core.data.core_types.get_filtered_init_field_names(obj, filter_fun)

Returns a list of filtered field names for an object’s __init__ method.

Parameters:

obj (Any) – The object to retrieve the field names from.
filter_fun (Callable[[Any], bool]) – A function that takes a field name as input and returns a boolean indicating whether the field should be included in the output list.

Returns:

A list of filtered field names for the object’s __init__ method.

vibe_core.data.core_types.get_filtered_init_fields(obj, filter_fun)

Returns a dictionary of filtered fields for an object’s __init__ method.

Parameters:

obj (Any) – The object to retrieve the field values from.
filter_fun (Callable[[Any], bool]) – A function that takes a field name as input and returns a boolean indicating whether the field should be included in the output dictionary.

Returns:

A dictionary of filtered field names and values for the object’s __init__ method.

vibe_core.data.core_types.get_init_field_names(obj)

Returns a list of field names for an object’s __init__ method.

Parameters:: obj (Type[BaseVibe]) – The BaseVibe class to retrieve the field names from.
Returns:: List[str] – A list of field names for the class’s __init__ method.

vibe_core.data.core_types.BBox

Type alias for a bounding box, as a tuple of four floats (minx, miny, maxx, maxy).

alias of Tuple[float, float, float, float]

vibe_core.data.core_types.Point

Type alias for a point, as a tuple of two floats (x, y).

alias of Tuple[float, float]

vibe_core.data.core_types.TimeRange

Type alias for a time range, as a tuple of two datetime objects (start, end).

alias of Tuple[datetime, datetime]