API reference

dataprocessing basics

geobricks

Loading/exporting & initializing datasets

• load_any
• main_vars
• main_space_dims
• main_time_dims
• get_filelist
• export

Georeferencing

• georef
• standardize_time_coord
• standardize_grid_mapping
• standardize_fill_value

File management

• merge_data

Transforming, converting, clipping, rasterizing

• transform

Other aliases

• reproject
• convert

Derived partial functions

• clip
• rasterize

Secondary tools

Under progress…

Section to be completed

Compress & uncompress

• unzip
• gzip
• pack

Units operations

• hourly_to_daily()

• to_instant()

• convert_unit()

Extractions

• timeseries

Under progress…

Section to be completed

download_fr

• download_fr.bnpe
• download_fr.hydrometry
• download_fr.sim2

download_wl

• download_wl.ERA5StandardizerWL

Secondary tools

• download_fr.valid_request

data-specific workflows

standardize_fr

• standardize_fr.bdalti
• standardize_fr.sim2

Under progress…

Section to be completed

model-specific workflows

cwatm

• cwatm.dem
• cwatm.meteo

Under progress…

Section to be completed

graphics

ncplot

• ncplot.plot_time_series
• ncplot.netcdf_to_animation

trajplot

class trajplot.Figure(var: str, root_folder, scenario: str = 'RCP 8.5', epsg_data=None, coords='all', epsg_coords=None, rolling_days: int = 1, period_years: int = 10, annuality='calendar', plot_type: str = None, repres: None | str = 'area', cumul: bool = False, relative: bool = False, language: str = 'fr', color='scale', plotsize='wide', name: str = '', credit: None | str = 'auto', showlegend: bool = True, shadow: None | str = None, verbose: bool = False)

Bases: object

Main data available as Figure attributes

Main variables	Description
self.model_names_list	List of model names. For example in EXPLORE2 it corresponds to the identifier of the climatic experiment: ‘Model1’, ‘Model2’, ‘Model3’…, ‘Model17’.
self.original_data	List of the pandas.Dataframes retrieved from the NetCDF data, for each model (climatic experiments). NetCDF data are converted into time series by considering the spatial average over the coords argument (mask).
self.relative_ref	Equivalent to self.original_data, but contains the time series used as reference (historic) to compute relative values (if user-chosen).
self.rea_data	Equivalent to self.original_data, but contains the reanalysis time series, which are added to the plots in order to provide a historic reference.
self.all_res	List of pd.Dataframes for each period (according to period_years argument), containing timeseries averaged over a year (365 days) for each model (climatic experiments) (one column per model). The year starts on the month defined by annuality argument.
self.graph_res	Results formated for the plots. Either in the form of a list of pd.Dataframes, one for each period, each pd.Dataframe containing the aggregated result (min, mean, sum…) from self.all_res [in case of plot_type = 'temporality']. Or in the form of a single pd.Dataframe containing the aggregated values for each day [in case of plot_type is a metric].

---

Examples

from watertrajectories_pytools.src.graphics import trajplot as tjp

mask = r"D:- Postdoc- Travaux
- Veille- Donnees- Territoire Annecy\masque_zone_etude.shp"

F = tjp.Figure(
    var = 'T',
    root_folder = r"E:\Inputs\Climat",
    scenario = 'rcp8.5',
    coords = mask,
    rolling_days = 30,
    period_years = 10,
    annuality = 3,
    name = 'Annecy',
    )

for m in mask_dict:
    for scenario in ['SIM2', 'rcp8.5']:
        figweb, _, _ = tjp.temporality(
            var = 'PRETOT', scenario = scenario, root_folder = r"E:\Inputs\Climat",
            coords = mask_dict[m], name = m,
            period_years = 10, rolling_days = 30, cumul = False, 
            plot_type = 'temporality', annuality = 3, relative = False, 
            language = 'fr', plotsize = 'wide', verbose = True)
        figweb, _, _ = tjp.temporality(
            var = 'DRAIN', scenario = scenario, root_folder = r"E:\Inputs\Climat",
            coords = mask_dict[m], name = m,
            period_years = 10, rolling_days = 30, cumul = False, 
            plot_type = 'temporality', annuality = 10, relative = False, 
            language = 'fr', plotsize = 'wide', verbose = True)
        figweb, _, _ = tjp.temporality(
            var = 'SWI', scenario = scenario, root_folder = r"E:\Inputs\Climat",
            coords = mask_dict[m], name = m,
            period_years = 10, rolling_days = 30, cumul = False, 
            plot_type = 'temporality', annuality = 3, relative = False, 
            language = 'fr', plotsize = 'wide', verbose = True)
        figweb, _, _ = tjp.temporality(
            var = 'T', scenario = scenario, root_folder = r"E:\Inputs\Climat",
            coords = mask_dict[m], name = m,
            period_years = 10, rolling_days = 30, cumul = False, 
            plot_type = 'temporality', annuality = 10, relative = False, 
            language = 'fr', plotsize = 'wide', verbose = True)

Parameters

varstr

‘PRETOT’ | ‘PRENEI’ | ‘ETP’ | ‘EVAPC’ | ‘RUNOFFC’ | ‘DRAINC’ | ‘T’ | ‘SWI’ | …

scenariostr

‘SIM2’ | ‘historical’ | ‘RCP 4.5’ | ‘RCP 8.5’

root_folderstr, path

Path to the folder containing climatic data.

r”D:- Postdoc- Travaux
- Veille- Donnees8- Meteo” (on my PC) r”E:InputsClimat” (on the external harddrive)

epsg_dataTYPE, optional

DESCRIPTION. The default is None.

coordsTYPE, optional

DESCRIPTION. The default is ‘all’.

epsg_coordsTYPE, optional

DESCRIPTION. The default is None.

languageTYPE, optional

DESCRIPTION. The default is ‘fr’.

plotsizeTYPE, optional

DESCRIPTION. The default is ‘wide’.

rolling_daysTYPE, optional

DESCRIPTION. The default is 1.

period_yearsTYPE, optional

DESCRIPTION. The default is 10.

cumulTYPE, optional

DESCRIPTION. The default is False.

plot_typeTYPE

DESCRIPTION.

repres{None, “area” or “bar”}, optional, default None

Only used when plot_type is a metric. Defines the type of graphical representation of the metric plot.

• "area": curves representing rolling averages

• "bar": rectangles representing period averages

nameint

Suffix to add in the filename. Especially usefull to indicate the name of the site.

creditstr, optional, default ‘auto’

To display the acknowledgement for data and conception. If 'auto', the standard info about data source and conception author will be displayed. To remove all mention of credits, pass credit=''.

color‘scale’, ‘discrete’, <colormap> (str) or list of colors, optional, default ‘scale’

Colors for the plots (for now, only for temporality plots)

relativebool

Whether the values should be computed as absolute or relatively to the reference period.

showlegendbool, optional, default True

Whether to display the legend or not.

shadow{None, ‘last’, ‘first’, ‘firstlast’, ‘lastfirst’, ‘all’}, optional, default = None

Whether to display dialy values in grey shadows, and for which period.

annualityint or str

Type of year

‘calendar’ | ‘meteorological’ | ‘meteo’ | ‘hydrological’ | ‘hydro’ 1 | 9 | 10

verbose: bool

Whether or not to display memory diagnotics.

agg_labels = {'decrease': ['decrease', 'diminution'], 'increase': ['increase', 'augmentation'], 'max': ['maximum', 'maximum'], 'mean': ['mean', 'moyenne'], 'min': ['minimum', 'minimum'], 'range': ['range', 'amplitude'], 'sum': ['sum', 'somme']}

classmethod get_plot_mode(plot_type)

layout(*, plotsize=None, name=None, credit=None, color=None, language=None, showlegend=None, shadow=None, repres=None, cumul=None)

load()

Results

This method also update the instance attributes all_res and graph_res, which respectively store the whole results and the final results used for the plot.

Warning

This method can lead to memory size issues. It seems to appear when the garbage collector is not doing its job fast enough in the xarray variable data from C:ProgramDataMiniconda3envscwatenvLibsite-packagesxarraycodingvariables.py.

To solve this, you might just need to open this folder on Windows.

Examples (pipeline)

import os mask_folder = r”D:2- Postdoc2- Travaux1- Veille4- Donnees15- Territoire Pays Basque” mask_dict = dict() mask_dict[‘cotier’] = os.path.join(mask_folder, r”Sage-cotier-basque.shp”) mask_dict[‘CAPB’] = os.path.join(mask_folder, r”zone_etude_fusion.shp”) mask_dict[‘Nive-Nivelle’] = os.path.join(mask_folder, r”Nive-Nivelle.shp”) for var in [‘PRETOT’, ‘DRAIN’, ‘SWI’, ‘T’]:

for scenario in [‘SIM2’, ‘rcp8.5’]:

for m in mask_dict:

F = tjp.Figure(

var = var, root_folder = r”E:InputsClimat”, scenario = scenario, coords = mask_dict[m], name = m, rolling_days = 30, period_years = 10, )

F.plot(plot_type = ‘annual_sum’) F.plot(plot_type = ‘annual_sum’, period_years = 30) F.plot(plot_type = ‘annual_sum’, period_years = 1) F.plot(plot_type = ‘annual_scatter’, agg_rule = ‘sum’) F.plot(plot_type = ‘15/11’, period_years = 10) F.plot(plot_type = ‘15/05’, period_years = 10) if var == ‘DRAIN’:

F.plot(plot_type = ‘> 1.5’)

classmethod metric(merge_res, startdate, plot_type)

metric_labels = {'annual': ['annual {}', '{} annuelle'], 'date': ['date of {}', 'date de {}']}

metric_list = ['annual', 'date']

plot(*, rolling_days=None, period_years=None, annuality=None, plot_type=None, plotsize=None, name=None, credit=None, color=None, language=None, showlegend=None, shadow=None, repres=None, cumul=None)

F = tjp.Figure(

var = ‘DRAINC’, root_folder = r”E:InputsClimat”, scenario = ‘rcp8.5’, coords = r”C:

ile.shp”,

rolling_days = 30, annuality = 10, name = ‘myCatchment’, )

F.plot(plot_type = ‘> 1.5’, period_years = 10) F.plot(plot_type = ‘annual_sum’) F.plot(plot_type = ‘annual_sum’, period_years = 30) F.plot(plot_type = ‘annual_scatter’, period_years = 1) F.plot(plot_type = ‘15/11’, period_years = 10)

plot_typestr

‘temporality’ | ‘annual_sum’

None.

static timeseries(*, data_type, var, scenario, season, domain='Pays-Basque', epsg_data=None, coords='all', epsg_coords=None, language='fr', plotsize='wide', rolling_window=1, plot_type='2series')

Examples

import climatic_plot as tjp

tjp.timeseries(data_type = “Indicateurs DRIAS-Eau 2024 SWIAV”,

scenario = ‘historical’, season = ‘JJA’, domain = ‘Pays Basque’, rolling_window = 10, plot_type = ‘2series’)

# —- Original and rolled series for SWIAV for season in [‘JJA’, ‘SON’, ‘DJF’, ‘MAM’]:

for scenario in [‘historical’, ‘rcp45’, ‘rcp85’]:

for domain in [‘Pays Basque’, ‘Annecy’]:

tjp.timeseries(data_type = “Indicateurs DRIAS-Eau 2024”,

var = ‘SWIAV’, scenario = scenario, season = season, domain = domain, rolling_window = 10, plot_type = ‘2series’)

# —- Same for SSWI for season in [‘JJA’, ‘SON’, ‘DJF’, ‘MAM’]:

for scenario in [‘rcp45’, ‘rcp85’]:

for domain in [‘Pays Basque’, ‘Annecy’]:

tjp.timeseries(data_type = “Indicateurs DRIAS-Eau 2024”,

var = ‘SSWI’, scenario = scenario, season = season, domain = domain, rolling_window = 10, plot_type = ‘2series’)

# —- All different colors with SIM2 tjp.timeseries(data_type = “Indicateurs DRIAS-Eau 2024”,

var = ‘SWIAV’, scenario = ‘historical’, season = ‘JJA’, domain = ‘Pays Basque’, rolling_window = 10, plot_type = ‘all with sim2’)

# —- Narratifs for season in [‘JJA’, ‘SON’, ‘DJF’, ‘MAM’]:

for domain in [‘Pays Basque’, ‘Annecy’]:

tjp.timeseries(data_type = “Indicateurs DRIAS-Eau 2024”,

var = ‘SWIAV’, scenario = ‘rcp85’, season = season, domain = domain, rolling_window = 10, plot_type = ‘narratifs’)

Parameters

• : TYPE

  DESCRIPTION.

root_folderTYPE

DESCRIPTION.

scenariostr

‘historical’ | ‘rcp45’ | ‘rcp85’

seasonstr

‘DJF’ | ‘MAM’ | ‘JJA’ | ‘SON’ | ‘NDJFMA’ | ‘MAMJJASO’ | ‘JJASO’ | ‘SONDJFM’

data_typeTYPE

DESCRIPTION.

epsg_dataTYPE, optional

DESCRIPTION. The default is None.

coordsTYPE, optional

DESCRIPTION. The default is ‘all’.

epsg_coordsTYPE, optional

DESCRIPTION. The default is None.

languageTYPE, optional

DESCRIPTION. The default is ‘fr’.

plotsizeTYPE, optional

DESCRIPTION. The default is ‘wide’.

rolling_windowTYPE, optional

DESCRIPTION. The default is 10.

plot_typeTYPE, optional

DESCRIPTION. The default is ‘2series’.

: TYPE

DESCRIPTION.

Returns

None.

update(*, var=None, root_folder=None, scenario=None, epsg_data=None, coords=None, epsg_coords=None, relative=None, rolling_days=None, period_years=None, annuality=None, plot_type=None, repres=None, cumul=None, language=None, plotsize=None, color=None, name=None, credit=None, showlegend=None, shadow=None, verbose=None)

classmethod update_verbose(verbose: bool)

verbose: bool = False

cmapgenerator

Created on Thu Sep 5 15:55:24 2024

@author: Alexandre Kenshilik Coche

cmapgenerator.custom(n_steps, *args)

args:

color1, color2, color3… en format [Rouge Vert Bleu Alpha] (valeurs entre 0 et 1)

cmapgenerator.custom_2_colors(n_steps, first_color, last_color)

cmapgenerator.discrete(sequence_name='ibm', alpha=1, black=True, alternate=True, color_format='float')

Generate a standardized colorscale, based on predefined color maps.

Parameters

sequence_name{“trio”, “duo”, “uno”, “ibm”, “wong”}, optional, default “ibm”

A flag to choose the colorscale among the available ones.

• "trio": a 3x9-color scale (+ grays) based on 9 distinct hues.

  • Two other colorscales can be derived from this one:

  • "duo": only the dark and light variations of each hue are returned.

  • "uno": only the middle variation of each hue is returned.

• "wong": a 9-color scale (+ black) extended from Wong, adapted for colorblindness.

• "ibm": a 6-color scale (+ black) extended from IBM colorscale, adapted for colorblindness.

alphaNone or float, optional, default 1

Transparency (from 0 to 1). If None, colors are returned without the 4th value.

blackbool, optional, default True

If False, the black color (and related gray variations) are not included in the colorscale.

alternatebool, optional, default True

If True, the colorscale is not in rainbow order.

color_format{“float”, “rbg_str”, “rgba_tuple”}, optional, default “float”

The way to define colors:

• "float": [0.22, 0.5, 0.99, 0.85]

• "rgba_str": "rgba(56.1, 127.5, 252.45, 0.82)"

• "rgba_tuple": (56.1, 127.5, 252.45, 0.82)

Returns

Return a numpy.array where each row is a 1D-array [red, green, blue, alpha], with values between 0 and 1, or corresponding list with values converted to rgba tuples or strings.

cmapgenerator.to_rgba_str(color)

This function can convert a color variable of any format ('float', 'rgba_tuple', 'rgba_str') and any shape (one color or several colors) into a color variable in the 'rgba_str' format, for example:

'rgb(239.95, 227.97, 66.045)'

or:

['rgb(239.95, 227.97, 66.045)',
 'rgb(135.92, 33.915, 84.915)',
 'rgb(188.95, 133.11, 254.49)',
 'rgb(212.92, 94.095, 0.51)',
 'rgb(120.105, 195.08, 236.895)']

Parameters

colorlist, numpy.array, tuple or str

Input color variable to convert.

Returns

A color variable similar to the input, but in the 'rgba_str' format.

SIM2_tools

Created on Fri Apr 5 18:08:57 2024

@author: Alexandre Kenshilik Coche @contact: alexandre.co@hotmail.fr

Based on the work of Ronan Abhervé and Loic Duffar (loicduffar)

SIM2_tools.clip(filepath, maskpath)

SIM2_tools.clip_folder(folder, maskpath)

SIM2_tools.compress(filepath)

SIM2_tools.compress_folder(folder)

SIM2_tools.folder_to_netcdf(folder)

Parameters

folderstr

Folder containing the .csv files.

Returns

None. Creates the .nc files in the folder ‘netcdf’

SIM2_tools.merge(filelist)

SIM2_tools.merge_folder(folder)

SIM2_tools.plot_map(var, *, file_folder=None, mode='sum', timemode='annual')

Generates interactive maps from SIM2 data (html).

Example

import SIM2_tools as smt

smt.plot_map(‘PRETOT’, mode = “sum”, timemode = ‘annual’)

for timemode in [‘JJA’, ‘SON’, ‘DJF’, ‘MAM’]:

smt.plot_map(‘SWI’, mode = “mean”, timemode = timemode, file_folder = folder)

Parameters

varstr

SIM2 variables:

‘ETP’ | ‘EVAP’ | ‘PRELIQ’ | ‘PRENEI’ | ‘PRETOT’ | ‘DRAINC’ | ‘RUNC’ | ‘T’ | ‘TINF_H’ | ‘TSUP_H’ | ‘WG_RACINE’ | ‘WGI_RACINE’ | ‘SWI’ …

modestr, optional

‘sum’ | ‘min’ | ‘max’ | ‘mean’ | ‘ratio’ | ‘ratio_precip’ | ‘mean_cumdiff’ | ‘sum_cumdiff’ | ‘min_cumdiff’ | ‘max_cumdiff’ ‘mean_cumdiff_ratio’ | ‘sum_cumdiff_ratio’ ‘mean_deficit’ | ‘sum_deficit’ The default is “sum”.

timemodestr, optional

‘annual’ | ‘ONDJFM’ | ‘AMJJAS’ | ‘DJF’ | ‘MAM’ | ‘JJA’ | ‘SON’. The default is ‘annual’.

Returns

None. Creates the html maps.

SIM2_tools.to_netcdf(csv_file_path)