API reference#
Top-level package for coloc_sat.
- class coloc_sat.GenerateColoc(product1_id, destination_folder='/tmp', delta_time=60, minimal_area=1600, listing=False, product_generation=True, **kwargs)[source]#
Class that generates co-locations. It can create listings of co-located products and/or generate co-location products. Some arguments of this class are expressed as keyword arguments because there are 2 use options. For the first option (comparison between a product and a whole dataset), arguments are ds_name, input_ds, level. For the second option (comparison between 2 products), argument is product2_id.
- Parameters:
product1_id (str) – Path of a product for which we want to create a listing of its co-located products and/or generate a co-location product. If it is a SAR Level-1 product, only a listing of its co-located files will be done.
destination_folder (str) – Folder path where listing and / or co-location products will be created
delta_time (int) – Maximum time (in minutes) that can separate two product acquisitions.
minimal_area (int | str) – Minimal intersection area restricted for a valid co-location. If it is an integer, so it is expressed in square kilometers. If it is a string, so the unit can be expressed as follows: 1600km2 or 1600000000m2.
listing (bool) – True if a listing of the co-located_files must be created. Default value is False
product_generation (bool) – True if a co-location product must be created. Default value is True
- Keyword Arguments:
dataset) (- For the first option (comparison between a product and a whole) –
- ds_namestr | None
Name of the dataset to be compared. Choices can be ‘S1’, ‘RS2’, ‘RCM’, ‘HY2’, ‘ERA5’, ‘WS’, ‘SMOS’, ‘SMAP’.
- input_dsstr | list[str] | None, optional
Optional. Used if it is needed to compare with a subset of products. This subset can be a subset of product paths or a text file that contains the different paths. If not specified, the default value is None. NOTE: The subset of products must belong to the mission specified in the ds_name argument.
- levelint | None, optional
When ds_name is SAR, specify the value of the product level. If it is None, get all SAR levels. It is useless to give it a value when ds_name is something other than a SAR (‘S1’, ‘RS2’, ‘RCM’). Values can be 1, 2, or None (default value).
products) (- For the second option (comparison between 2) –
- product2_idstr | None
Path of the product that must be compared with product1.
Arguments (Optional) –
------------------ –
listing_filename (str | None, optional) – Name of the listing file that must be created. It is useless to specify one if listing is False. Default value is None.
colocation_filename (str | None, optional) – Name of the co-location product that must be created. It is useless to specify one if product_generation is False. Default value is None.
- exception UnknownOptionError[source]#
Used to raise errors concerning the 2 arguments subsets given in input of the class GenerateColoc
- colocation_filename(intersection)[source]#
Get the filename of the co-location product that must be created
- Parameters:
intersection (sar_coloc.ProductIntersection) – intersection between 2 products
- Returns:
Filename of the co-location product that must be created
- Return type:
- property compare2products#
Know if the comparison is between 2 products or not
- Returns:
True if the comparison is between 2 products
- Return type:
- fill_colocated_files()[source]#
Fill a dictionary as self.colocated_files with file paths of products from self.comparison_files that can be colocated with self.product1_id. If no products are in self.comparison_files, so self.colocated_files remains with None value.
- fill_intersections()[source]#
Fill a dictionary as self.intersections with intersections (sar_coloc.ProductIntersection) between self.product1_id and products that are in self.comparison_files. If no products are in self.comparison_files, so self.intersections remains with None value.
- property get_comparison_files#
Get all the files from the specified database that match with the start and stop dates
- Returns:
Comparison files.
- Return type:
list | None
- property has_coloc#
Know if the product self.product1_id has co-located products in self.comparison_files
- Returns:
True if the product has co-located products
- Return type:
- property listing#
Know if a listing must be created
- Returns:
True if a listing must be created
- Return type:
- listing_filename(intersection)[source]#
Get the filename of the listing file that must be created
- Parameters:
intersection (sar_coloc.ProductIntersection) – intersection between 2 products
- Returns:
Filename of the listing file that must be created
- Return type:
- property minimal_area#
Get minimal intersection area restricted for a valid co-location. Expressed in square kilometers.
- Returns:
Minimal area intersection in square kilometers
- Return type:
- property product1_start_date#
Get start date of the product1 considering the delta time
- Returns:
Start date of the product1 considering the delta time
- Return type:
- property product1_stop_date#
Get stop date of the product1 considering the delta time
- Returns:
stop date of the product1 considering the delta time
- Return type:
- product_generation(intersection)[source]#
Know if a co-location product must be created
- Returns:
True if a co-location product must be created
- Return type:
- save_results()[source]#
Save the result listing as a text file, and / or the resulting co-location product as a netcdf file. The creation depends on the value of the attributes self.colocated_files and self.product_generation(intersection) for a specific intersection. Paths where files are written is specified in self.listing_filename(intersection) and self.product_generation(intersection).
- class coloc_sat.GetEra5Meta(product_path, product_generation=False)[source]#
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- property dataset#
Getter for the acquisition dataset
- Returns:
Acquisition dataset
- Return type:
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
longitude name
- Return type:
- latitude_name_res(resolution)[source]#
Get the name of the latitude variable in the dataset. For ERA 5, two latitude variable exist : one with a resolution of 0.25; and one with a resolution of 0.5
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- longitude_name_res(resolution)[source]#
Get the name of the longitude variable in the dataset. For ERA 5, two longitude variable exist : one with a resolution of 0.25; and one with a resolution of 0.5
- property mission_name#
Name of the mission (or model)
- Returns:
Mission name (ex: SMOS, S1, RS2, RCM, SMAP, HY2, ERA5)
- Return type:
- property necessary_attrs_in_coloc_product#
Get necessary dataset attributes in co-location product
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- reformat_meta()[source]#
Put both resolution of longitude and latitude at the same resolution. The resolution kept is the biggest one.
- rename_attrs_in_coloc_product(attr)[source]#
Get the new name of an attribute in co-location products from an original attribute
- rename_vars_in_coloc(dataset=None)[source]#
Rename variables from a dataset to homogenize the co-location product. If no dataset is explicit, so it is this of self.dataset which is used.
- Parameters:
dataset (xarray.Dataset | None) – Dataset on which common vars must be renamed
- Returns:
Dataset with homogene variable names
- Return type:
- property start_date#
Start acquisition time
- Returns:
Start time
- Return type:
- property stop_date#
Stop acquisition time
- Returns:
Stop time
- Return type:
- property time_name#
Get the name of the time variable in the dataset
- Returns:
time name
- Return type:
- property unecessary_vars_in_coloc_product#
Get unecessary variables in co-location product
- class coloc_sat.GetHy2Meta(product_path, product_generation=False)[source]#
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- property dataset#
Getter for the acquisition dataset
- Returns:
Acquisition dataset
- Return type:
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
latitude name
- Return type:
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- property mission_name#
Name of the mission (or model)
- Returns:
Mission name (ex: SMOS, S1, RS2, RCM, SMAP, HY2, ERA5)
- Return type:
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- property start_date#
Start acquisition time
- Returns:
Start time
- Return type:
- property stop_date#
Stop acquisition time
- Returns:
Stop time
- Return type:
- class coloc_sat.GetSmosMeta(product_path, product_generation=False)[source]#
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- property dataset#
Getter for the acquisition dataset
- Returns:
Acquisition dataset
- Return type:
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
latitude name
- Return type:
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- property mission_name#
RADARSAT-2, RCM, SENTINEL-1, SMOS, SMAP,…)
- Returns:
Mission name
- Return type:
- Type:
Get the mission name (ex
- property necessary_attrs_in_coloc_product#
Get necessary dataset attributes in co-location product
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- rename_attrs_in_coloc_product(attr)[source]#
Get the new name of an attribute in co-location products from an original attribute
- rename_vars_in_coloc(dataset=None)[source]#
Rename variables from a dataset to homogenize the co-location product. If no dataset is explicit, so it is this of self.dataset which is used.
- Parameters:
dataset (xarray.Dataset | None) – Dataset on which common vars must be renamed
- Returns:
Dataset with homogene variable names
- Return type:
- property start_date#
Start acquisition time
- Returns:
Start time
- Return type:
- property stop_date#
Stop acquisition time
- Returns:
Stop time
- Return type:
- property time_name#
Get the name of the time variable in the dataset
- Returns:
time name
- Return type:
- property unecessary_vars_in_coloc_product#
Get unecessary variables in co-location product
- class coloc_sat.GetSmapMeta(product_path, product_generation=False)[source]#
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- add_source_reference_attribute(ds=None, attr_name='reference')[source]#
Add the source reference attribute in a SMAP dataset. The name given to this attribute is chosen with the argument attr_name
- Parameters:
ds (xarray.Dataset | None) – Dataset that contains the SMAP information, in which the source reference attribute must be added.
attr_name (str) – Name chosen for the reference attribute.
- Returns:
Dataset that contains the source reference attribute
- Return type:
- property dataset#
Getter for the acquisition dataset
- Returns:
Acquisition dataset
- Return type:
- property day_date#
Get day date from the product name as a datetime
- Returns:
datetime.datetime
Day date of the product
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
latitude name
- Return type:
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- property minute_name#
Get name of the minute variable in the dataset
- Returns:
Minute variable name
- Return type:
- property mission_name#
Name of the mission (or model)
- Returns:
Mission name (ex: SMOS, S1, RS2, RCM, SMAP, HY2, ERA5)
- Return type:
- property necessary_attrs_in_coloc_product#
Get necessary dataset attributes in co-location product
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- rename_attrs_in_coloc_product(attr)[source]#
Get the new name of an attribute in co-location products from an original attribute
- rename_vars_in_coloc(dataset=None)[source]#
Rename variables from a dataset to homogenize the co-location product. If no dataset is explicit, so it is this of self.dataset which is used.
- Parameters:
dataset (xarray.Dataset | None) – Dataset on which common vars must be renamed
- Returns:
Dataset with homogene variable names
- Return type:
- property start_date#
Start acquisition time
- Returns:
Start time
- Return type:
- property stop_date#
Stop acquisition time
- Returns:
Stop time
- Return type:
- property time_name#
Get the name of the time variable in the dataset
- Returns:
time name
- Return type:
- property unecessary_vars_in_coloc_product#
Get unecessary variables in co-location product
- class coloc_sat.GetSarMeta(product_path, product_generation=False)[source]#
- exception WrongProductTypeError[source]#
Used for raising Exceptions when a function / property is called whereas it wasn’t created for the specified type (Level 2 / Level 1)
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- property dataset#
Getter for SAR dataset. NOTE: A SAR can be a L2 or a L1. This getter will be used in intersection functions. The choice has been made to use L1 only for listings (so we only need the footprint), and use L2 for co-location product. The dataset is needed only to create co-location product, so it is an alias of self._l2_info.
- Returns:
L2 SAR dataset
- Return type:
- datatree(ds_name)[source]#
For a level 1 product, getter for the datatree located in the metadata. Contains the main useful information
- Parameters:
ds_name (str) – dataset_name (look into OpenSar._l1_info[‘dataset_names’]) for available ones.
- Returns:
Main metadata information
- Return type:
See also
OpenSar._l1_info[‘dataset_names’]
- fill_dataset_names()[source]#
For a level 1 product, if it is a multi dataset, fills in a dictionary (OpenSar._l1_info) the name of the sub-datasets
- fill_footprints()[source]#
For a level 1 product, if it is a multi dataset, fills in a dictionary (OpenSar._l1_info) the footprint of sub-datasets
- fill_submeta()[source]#
For a level 1 product, if it is a multi dataset, fills in a dictionary (OpenSar._l1_info) the metadata of sub-datasets
- fill_times()[source]#
For a level 1 product, if it is a multi dataset, fills in a dictionary (OpenSar._l1_info) the start/stop time of sub-datasets
- property footprint#
Get footprint of the product
- Returns:
Footprint Polygon
- Return type:
shapely.geometry.polygon.Polygon
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property is_safe#
Know if a product is a Level 1 or Level 2. True if Level one
- Returns:
True if SAR product is a level 1
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
latitude name
- Return type:
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- property mission_name#
RADARSAT-2, RCM, SENTINEL-1)
- Returns:
Mission name
- Return type:
See also
- Type:
From the product_name, get the mission name (ex
- property multidataset#
Express if a product is a multi dataset or not.
- Returns:
Express if it is a multi dataset
- Return type:
- property necessary_attrs_in_coloc_product#
Get necessary dataset attributes in co-location product
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- rename_attrs_in_coloc_product(attr)[source]#
Get the new name of an attribute in co-location products from an original attribute
- property start_date#
Start acquisition date
- Returns:
Start date
- Return type:
- property stop_date#
Stop acquisition date
- Returns:
Stop date
- Return type:
- property time_name#
Get the name of the time variable in the dataset
- Returns:
time name
- Return type:
- property unecessary_vars_in_coloc_product#
Get unecessary variables in co-location product
- class coloc_sat.GetWindSatMeta(product_path, product_generation=False)[source]#
- property acquisition_type#
Gives the acquisition type (swath, truncated_swath,daily_regular_grid, model_regular_grid)
- Returns:
acquisition type
- Return type:
- property dataset#
Getter for the acquisition dataset
- Returns:
Acquisition dataset
- Return type:
- property day_date#
Get day date from the product name as a datetime
- Returns:
datetime.datetime
Day date of the product
- property has_orbited_segmentation#
True if there is orbit segmentation in the dataset
- Returns:
Presence or not of an orbit segmentation
- Return type:
- property latitude_name#
Get the name of the latitude variable in the dataset
- Returns:
latitude name
- Return type:
- property longitude_name#
Get the name of the longitude variable in the dataset
- Returns:
longitude name
- Return type:
- property minute_name#
Get name of the minute variable in the dataset
- Returns:
Minute variable name
- Return type:
- property mission_name#
RADARSAT-2, RCM, SENTINEL-1, SMOS, SMAP,…)
- Returns:
Mission name
- Return type:
- Type:
Get the mission name (ex
- property necessary_attrs_in_coloc_product#
Get necessary dataset attributes in co-location product
- property orbit_segment_name#
Gives the name of the variable for orbit segmentation in dataset (Ascending / Descending). If value is None, so the orbit hasn’t orbited segmentation
- Returns:
Orbit segmentation variable name in the dataset. None if there isn’t one.
- Return type:
str | None
- rename_attrs_in_coloc_product(attr)[source]#
Get the new name of an attribute in co-location products from an original attribute
- rename_vars_in_coloc(dataset=None)[source]#
Rename variables from a dataset to homogenize the co-location product. If no dataset is explicit, so it is this of self.dataset which is used.
- Parameters:
dataset (xarray.Dataset | None) – Dataset on which common vars must be renamed
- Returns:
Dataset with homogene variable names
- Return type:
- property start_date#
Start acquisition time
- Returns:
Start time
- Return type:
- property stop_date#
Stop acquisition time
- Returns:
Stop time
- Return type:
- property time_name#
Get the name of the time variable in the dataset
- Returns:
time name
- Return type:
- property unecessary_vars_in_coloc_product#
Get unecessary variables in co-location product
- class coloc_sat.ProductIntersection(meta1, meta2, delta_time=60, minimal_area=1600, product_generation=True)[source]#
- property coloc_product_datasets#
Get the final co-located product dataset.
- Notes:
This method also populates the common zone datasets in the self.common_zone_datasets attribute when they do not exist yet.
It also populates the resampled datasets in the self.resampled_datasets attribute when they do not exist yet.
It also formats the datasets (variable and attribute names + adds new attributes).
Finally, it stores the result in self.colocation_product.
Returns:#
- Dict[str, xarray.Dataset]
Final co-located product datasets.
- property coloc_resample#
Resample 2 satellite datasets from self.meta1`and `self.meta2. If a dataset exists in self._datasets (it means that a meta dataset has been intersected temporally and spatially), so this one is chosen. Notes : it uses rasterio.reproject_match with a bi-linear resampling.
- Returns:
Two first values of the dictionary are resampled datasets from meta1 and meta 2. Last value is a string that precise which dataset of both has been reprojected.
- Return type:
Dict[str, Union[xarray.Dataset, str]]
- fill_common_zone_datasets()[source]#
Fills common zone datasets in the attribute self.common_zone_datasets
- fill_resampled_datasets()[source]#
Fills resampled datasets in the attribute self.resampled_datasets
- format_datasets()[source]#
Apply vars and attributes renaming to prepare common zone datasets for the co-location product and add missing attributes
- Returns:
Formatted common zone datasets
- Return type:
Dict[str, xarray.Dataset]
- property get_common_zone#
Search for common zone between two resampled datasets (located in self.resampled_datasets); and put these two dataset in this common zone.
- Returns:
Resampled datasets located in a common zone (longitude and latitude).
- Return type:
- property has_intersection#
Property that verifies if there is an intersection between 2 products.
- Returns:
True if 2 products are co-located.
- Return type:
- intersection_drg_drg()[source]#
Method that verifies if there is an intersection between 2 daily regular grid products. This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- intersection_drg_non_truncated_swath()[source]#
Method that verifies if there is an intersection between a daily regular grid product and a non-truncated swath. This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- intersection_drg_truncated_swath()[source]#
Method that verifies if there is an intersection between a daily regular grid product and a truncated swath. This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- intersection_non_truncated_swath_non_truncated_swath()[source]#
Method that verifies if there is an intersection between 2 non-truncated swath products. This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- intersection_swath_truncated_swath()[source]#
Method that verifies if there is an intersection between a truncated swath product and a non-truncated swath. This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- intersection_with_model()[source]#
Method that verifies if there is an intersection between a product and a model (ERA 5 for example). This method can fill attributes like self._datasets (with the datasets after temporal and spatial intersection) and self._common_footprint.
- Returns:
True if there is an intersection (so if the products are co-located)
- Return type:
- property merge_datasets#
Merge 2 formatted common zones datasets in an only dataset
- Returns:
2 formatted common zones datasets merged
- Return type:
xr.Dataset
- property meta1#
Getter of the first metaobject.
- property meta2#
Getter of the second metaobject.