iucm.main module¶

Main module of the iucm package

This module defines the IUCMOrganizer class that is used to create a command line parser and to manage the configuration of the experiments

Classes

IUCMOrganizer([config]) A class for organizing a model

Functions

main() Call the main() method of the

class iucm.main.IUCMOrganizer(config=None)[source]¶

Bases: model_organization.ModelOrganizer

A class for organizing a model

This class is indended to have hold the basic functions for organizing a model. You can subclass the functions setup, init to fit to your model. When using the model from the command line, you can also use the setup_parser() method to create the argument parsers

Parameters:	config (model_organization.config.Config) – The configuration of the organizer

Attributes

`commands`	Built-in mutable sequence.
`name`	str(object=’‘) -> str
`paths`	Built-in mutable sequence.
`postproc_funcs`	A mapping from postproc commands to the corresponding function
`preproc_funcs`	A mapping from preproc commands to the corresponding function

Methods

`get_population_vname`(ds)
`make_map`(ds[, output, odir, time, diff, t0, …])	Make a movie of the post processing
`make_movie`(ds[, output, odir, diff, t0, …])	Make a movie of the post processing
`plot_evolution`(ds[, output, odir, close, …])	Plot the evolution of DIST, RSS, ENTROP and Energy consumption
`postproc`([no_input])	Postprocess the data
`preproc`(\\kwargs)	Preprocess the data
`preproc_forcing`([development_file, output, …])	Create a forcing file from a predescribed population path
`preproc_mask`(shapefile[, method, ifile, …])	Mask grid cells based on a shape file
`rolling_mean`(ds[, window, output, odir])	Calculate the rolling mean for the energy consumption
`run`([ifile, forcing, vname, steps, …])	Run the model for the given experiment

commands = ['setup', 'init', 'set_value', 'get_value', 'del_value', 'info', 'unarchive', 'configure', 'preproc', 'run', 'postproc', 'archive', 'remove']¶

get_population_vname(ds)[source]¶

make_map(ds, output='map.pdf', odir=None, time=-1, diff=False, t0=0, project_file=None, save_project=None, simple_plot=False, close=True, **kwargs)[source]¶

Make a movie of the post processing

Parameters:

ds (xarray.Dataset) – The dataset for the plot or a list of filenames
output (str) – The name of the output file
odir (str) – The name of the output directory
time (int) – The timestep to plot. By default, the last timestep is used
diff (bool) – If True/set, visualize the difference to the t0 (by default, the first step) is used, instead of the entire data
t0 (int) – If diff is set, the reference step for the difference
project_file (str) – The path to a filename containing a file that can be loaded via the psyplot.project.Project.load_project() method
save_project (str) – The path to a filename where to save the psyplot project
simple_plot (bool) – If True/set, use a non-georeferenced plot. Otherwise, we use the cartopy module to plot it
close (bool) – If True, close the project at the end

Other Parameters:

``**kwargs`` – Any other keyword that is passed to the psyplot.project.Project.export() method

make_movie(ds, output='movie.gif', odir=None, diff=False, t0=None, project_file=None, save_project=None, simple_plot=False, close=True, time=None, **kwargs)[source]¶

Make a movie of the post processing

Parameters:

ds (xarray.Dataset) – The dataset for the plot or a list of filenames
output (str) – The name of the output file
odir (str) – The name of the output directory
diff (bool) – If True/set, visualize the difference to the t0 (by default, the first step) is used, instead of the entire data
t0 (int) – If diff is set, the reference step for the difference
project_file (str) – The path to a filename containing a file that can be loaded via the psyplot.project.Project.load_project() method
save_project (str) – The path to a filename where to save the psyplot project
simple_plot (bool) – If True/set, use a non-georeferenced plot. Otherwise, we use the cartopy module to plot it
close (bool) – If True, close the project at the end
time (list of int) – The time steps to use for the movie

Other Parameters:

``**kwargs`` – Any other keyword for the matplotlib.animation.FuncAnimation class that is used to make the plot

name = 'iucm'¶

paths = ['expdir', 'src', 'data', 'input', 'outdata', 'outdir', 'plot_output', 'project_output', 'forcing', 'indir']¶

plot_evolution(ds, output='plots.pdf', odir=None, close=True, time=None, use_rolling=False)[source]¶

Plot the evolution of DIST, RSS, ENTROP and Energy consumption

Parameters:	ds (xarray.Dataset) – The dataset for the plot or a list of filenames output (str) – The name of the output file odir (str) – The name of the output directory close (bool) – If True, the created figures are closed in the end time (list of int) – The time steps to use for the movie use_rolling (bool) – If True, use the rolling mean for the energy consumption
Returns:	Information on the output
Return type:	dict

postproc(no_input=False, **kwargs)[source]¶

Postprocess the data

Parameters:	no_input (bool) – If True/set, the initial input file is ignored

postproc_funcs¶: A mapping from postproc commands to the corresponding function

preproc(**kwargs)[source]¶

Preprocess the data

Parameters:	**kwargs – Any keyword from the `preproc` attribute with kws for the corresponding function, or any keyword for the `main()` method

preproc_forcing(development_file=None, output=None, date_cols=None, steps=1, movement=0, trans_size=0, population_col=None, no_date_parsing=False)[source]¶

Create a forcing file from a predescribed population path

Parameters:

development_file (str) – The path to a csv file containing (at least) one column with the projected population development
output (str) – The name of the ouput forcing netCDF file. By default: '<expdir>/input/forcing.nc'
date_cols (list of str) – The names of the date columns in the development_file that shall be used to generate the date-time information. If not given, the date will simply be a range from 1 to steps times the length of the projected population development from development_file
steps (int) – The numbers of model steps between on step of the projected development in development_file
movement (float) – The people moving randomly during on model step
trans_size (float) – The forced size of the transformation additionally to the development from development_file
population_col (str) – The name of the column with population data. If not given, the last one is used
no_date_parsing (bool) – If True, then date_cols is simply interpreted as an index and no date-time information is parsed

preproc_funcs¶: A mapping from preproc commands to the corresponding function

preproc_mask(shapefile, method='max-pop', ifile=None, vname=None, overwrite=False, max_pop=None, hr_res=100)[source]¶

Mask grid cells based on a shape file

This command calculates the maximum population for the model based on a masking shape file. The given shape file is rasterized at high resolution (by default, 100 times the resolution of the input file) and the fraction for each grid cell that is covered by that shape file is calculated.

Parameters:

shapefile (str) – The path to a shapefile
method ({'max-pop', 'mask', 'ignore'}) –
Determines how to handle the given shapes.

max-pop

The maximum population per grid cell is lowered by the fraction of the cell that is covered by the given shape. This will adjust the max_pop variable in the input file ifile

mask

The population of the grid cells in the input data that are touched by the given shapes will be kept constant during the simulation. This will adjust the mask variable in the input file ifile

ignore

The grid cells in the input data that are touched by the given grid cells are put to NaN and their population is not considered during the simulation. This will adjust the input population data (i.e. variable vname) directly
ifile (str) – The path of the input file. If not specified, the value of the configuration is used
vname (str) – The variable name to use. If not specified and only one variable exists in the dataset, this one is used. Otherwise, the 'run.vname' key in the experiment configuration is used
overwrite (bool) – If True and the target variable exists already in the input file ifile (and method is not ‘ignore’), this variable is overwritten
max_pop (float) – The maximum population. If not specified, the value in the configuration is used (only necessary if method=='max-pop')
hr_res (int) – The resolution of the high resolution file, relative to the resolution of ifile (only necessary if method=='max-pop')

Notes

Note that the shapefile and the input file have to be defined on the same coordinate system! This function is not super efficient, for large data files we recommend using gdal_rasterize and gdalwarp.

rolling_mean(ds, window=None, output=None, odir=None)[source]¶

Calculate the rolling mean for the energy consumption

This postprocessing function calculates the rolling mean for the energy consumption

Parameters:

ds (xarray.Dataset) – The dataset with the cons and cons_std variables
window (int) – Size of the moving window. This is the number of observations used for calculating the statistic. Each window will be a fixed size. If None, it will be taken from the experiment configuration with a default value of 50.
output (str) – A filename where to save the output. If not given, it is not saved but may be later used by the evolution() method
odir (str) – The name of the output directory

run(ifile=None, forcing=None, vname=None, steps=50, selection_method=None, update_method=None, ncells=None, categories=None, use_pctls=False, no_restart=False, output_step=None, seed=None, stop_en_change=None, agg_stop_steps=100, agg_steps=1, probabilistic=None, max_pop=None, coord_transform=None, copy_from=None, **kwargs)[source]¶

Run the model for the given experiment

Parameters:

ifile (str) – The input file. If not specified, the input key in the experiment configuration is used
forcing (str) – The forcing file (necessary if update_method=='forced'). If not specified, the forcing key in the experiment configuration is used
vname (str) – The variable name to use. If not specified and only one variable exists in the dataset, this one is used. Otherwise, the 'run.vname' key in the experiment configuration is used
steps (int) – The number of time steps
selection_method ({ 'consecutive' | 'random' }) –
The name of the method on how the data is selected. The default is consecutive. Possible selection methods are

consecutive:

Always the ncells consecutive cells are selected.

random:

ncells random cells in the field are updated.
update_method ({ 'categorical' | 'random' | 'forced' }) –
The name of the update method on how the selected cells (see selection_method are updated). The default is categorical. Possible update methods are

categorical:

The selected cells are updated to the lower level of the next category.

random:

The selected cells are updated to a randum number within the next category.

forced:

A forcing file is used (see the forcing parameter).
ncells (int) – The number of cells that shall be changed during 1 step. The default value is 4
categories (list of floats) – The values for the categories to use within the models
use_pctls (bool) – If True, interprete categories as percentiles instead of real population density
no_restart (bool) – If True, and the run has already been conducted, restart it. Otherwise the previous run is continued
output_step (int) – Make an output every output_step. If None, only the final result is written to the output file
seed (int) – The random seed for numpy to use. Specify this parameter for the experiment to guarantee reproducability
stop_en_change (float) – The minimum of required relative energy consumption change. If the mean relative energy consumption change over the last agg_stop_steps steps is below this number, the run is stopped
agg_stop_steps (int) – The number of steps to aggregate over when calculating the mean relative energy consumption change. Does not have an effect if stop_en_change is None
agg_steps (int) – Use only every agg_steps energy consumption for the aggregation when checking the stop_en_change criteria
probabilistic (int) – The number of probabilistic scenarios. For each scenario the energy consumption is calculated and the final population is distributed to the cells with the ideal energy consumption. Set this to 0 to only use the weights by [LeNechet2012]. If this option is None, the value will be taken from the configuration with a default of 0 (i.e. no probabilistic run).
max_pop (float) – The maximum population for each cell. If None, the last value in categories will be used or what is stored in the experiment configuration
coord_transform (float) – The transformation factor to transform the coordinate values into kilometres
copy_from (str) – If not None, copy the run settings from the other given experiment
**kwargs – Any other keyword argument that is passed to the main() method

iucm.main.main()[source]¶: Call the main() method of the IUCMOrganizer class