PCRaster Python Framework

pcraster.framework

The pcraster.framework package contains classes for various model types, and framework types.

Model types are meant to be overriden by the user. By implementing these types, the user is certain that his model fulfills the requirements of the framework type used to execute the model. The goal is to enable the model to be as small as possible, containing hardly more than the statements making up the actual model.

Supported model types are:

  • Static model

  • Dynamic model

  • Monte Carlo model

  • Particle filter model

  • Kalman filter model

Framework types are provided by the package to execute the model created by the user. They contain the boilerplate logic to call certain model methods in the right order. Apart from that, they contain some additional goodies, like a progress indicator.

Supported framework types are:

  • Static model framework

  • Dynamic model framework

  • Monte Carlo framework

  • Particle filter framework

  • Kalman filter framework

Please find more detailed information in these next sections:

Static models

Static model concept

To use the static framework the user must implement:

  • either a run or an initial method

Classes

class pcraster.framework.staticBase.StaticBase

Bases: object

Base class for StaticModel framework class.

initial()
setDebug()
class pcraster.framework.staticPCRasterBase.StaticModel

Bases: StaticBase

initial()

Reimplemented from StaticBase.

readmap(name, style=1)

Read map data from disk.

name

name used as filename. Use filename without extension. File extension for deterministic static models is “.map” and will be appended automatically.

report(variable, name, style=1)

Store map data to disk

variable

object containing the PCRaster map data

name

name used as filename. Use filename without extension. File extension for deterministic static models is “.map” and will be appended automatically.

class pcraster.framework.staticFramework.StaticFramework(userModel)

Bases: FrameworkBase

Framework class for static models.

userModel

Instance that models the Static Model Concept.

run()

Re-implemented from ShellScript.

Run the execute or initial section of the user model.

Dynamic models

Dynamic model concept

To use the dynamic framework the user must implement the following methods in this class:

  • either “run” or “initial” and “dynamic”

Classes

class pcraster.framework.dynamicBase.DynamicBase

Bases: object

Base class for DynamicModel framework class.

currentTimeStep()
dynamic()
firstTimeStep()

Return the first timestep that is executed.

initial()
nrTimeSteps()
setDebug()
setQuiet(quiet=True)

Disables the progress display of timesteps.

timeSteps()
class pcraster.framework.dynamicPCRasterBase.DynamicModel

Bases: DynamicBase

currentTimeStep()

Return the current time step in the range from firstTimeStep to nrTimeSteps.

dynamic()
firstTimeStep()

Return first timestep of a model.

initial()
nrTimeSteps()

Return the number of time steps

readmap(name, style=1)

Read map data from disk.

name

Name used as filename. Use filename with less than eight characters and without extension. File extension for dynamic models is “.map” in initial section and the 8.3 style format name in the dynamic section. File extensions will be appended automatically.

report(variable, name)

Storing map data to disk

variable

Variable containing the PCRaster map data

name

Name used as filename. Use a filename with less than eight characters and without extension. File extension for dynamic models is “.map” in the initial section and the 8.3 style format name in the dynamic section. File extensions will be appended automatically.

timeSteps()

Return a list of time steps configured

class pcraster.framework.dynamicFramework.DynamicFramework(userModel, lastTimeStep=0, firstTimestep=1)

Bases: FrameworkBase

Framework class for dynamic models.

userModel

Instance that models the Dynamic Model Concept.

lastTimeStep

Last timestep to run.

firstTimestep

Sets the starting timestep of the model (optional, default is 1).

run()

Run the dynamic user model.

setQuiet(quiet=True)

Disables the progress display of timesteps.

Monte Carlo method

Monte Carlo model concept

  • premcloop

  • postmcloop

Classes

class pcraster.framework.mcBase.MonteCarloBase

Bases: object

currentSampleNumber()

Returns the current sample number

nrSamples()

Return the number of samples

postmcloop()
premcloop()
sampleNumbers()

Returns a list of sample numbers configured

class pcraster.framework.mcPCRasterBase.MonteCarloModel

Bases: MonteCarloBase

postmcloop()
premcloop()
readDeterministic(name)

Read deterministic data from disk.

Returns the map of the file with current time step, from the current working directory.

readmap(name)

Read sample data from disk.

Returns the map of the current time step from the current sample directory.

report(variable, name)

Report map data to disk.

Standard extension is “map” in initial and timestep in the dynamic section. Output directory will be sample directory.

class pcraster.framework.mcFramework.MonteCarloFramework(userModel, nrSamples=0, remove_dirs=True)

Bases: FrameworkBase, ForkScript

Framework class for the Monte Carlo method.

userModel

Instance that models the Monte Carlo Model Concept.

nrSamples

Number of realisations to run.

remove_dirs

Flag whether sample directories should be removed

run(premc=True, postmc=True)
setForkSamples(fork, nrCPUs=1)

Set the forking of samples on or off.

fork

True or False.

nrCPUs

Number of CPU’s to use. If not provided, this is autodectected.

When forking is on EVERY sample will be forked to its own process. This is mainly useful on a cluster with automatic process migration or on SMP machines.

Warning

setrandomseed does not work when forking is enabled

Note

Support for forking samples is not available on Windows

setQuiet(quiet=True)

Disables the progress display of sample numbers.

Particle filter method

Particle filter model concept

Classes

class pcraster.framework.pfBase.ParticleFilterBase

Bases: object

filterPeriod()

Return the current filter period.

filterTimesteps()
particleWeight()
readState()
reportState()
setDebug()
class pcraster.framework.pfPCRasterBase.ParticleFilterModel

Bases: ParticleFilterBase

readState(variableName)

Read a state variable map.

reportState(variable, variableName)

Report a map into the state variable directory.

class pcraster.framework.particleFilterFramework.ParticleFilterFramework(userModel)

Bases: FrameworkBase

Framework class for the particle filter method.

userModel

Instance that models the Particle Filter Model Concept.

filterTimesteps()

Return a list of filter moments.

particleWeight(sample)

Return the weight of a particle.

readDeterministic(name)

Read deterministic data from disk.

Returns the map of the current time step from the current working directory.

readmap(name)

Read sample data from disk.

Returns the map of the current time step from the current sample directory.

run()

Run the user model in the filter mode.

Re-implemented from ShellScript.

setFilterTimesteps(filterTimesteps)

Set the filter moments.

class pcraster.framework.particleFilterFramework.ResidualResamplingFramework(userModel)

Bases: ParticleFilterFramework

class pcraster.framework.particleFilterFramework.SequentialImportanceResamplingFramework(userModel)

Bases: ParticleFilterFramework

optimalSampleNumber(filterTimestep)

Kalman filter method

Classes

class pcraster.framework.kfBase.EnKfBase

Bases: object

initial()
setDebug()
setObservations()
setState()
class pcraster.framework.kfPCRasterBase.EnKfModel

Bases: EnKfBase

readmap(name, style=1)
report(variable, name, style=1)
class pcraster.framework.kalmanFilterFramework.EnsKalmanFilterFramework(userModel)

Bases: FrameworkBase

filterTimesteps()
getStateVector(sampleNumber)
readDeterministic(name)
readmap(name)
run()
setFilterTimesteps(filterTimesteps)
setMeasurementOperator(matrix)
setObservedMatrices(observations, covariance)

Stuff

class pcraster.framework.frameworkBase.FrameworkBase

Bases: ShellScript

Base class for frameworks.

Basically contains things for logging…

generateNameS(name, sample)
setDebug(debug)
setQuiet(quiet)

Enable/disable all framework output to stdout.

quiet

True/False. Default is set to False

setTrace(trace)

Trace framework output to stdout.

trace

True/False. Default is set to False.

If tracing is enabled the user will get a detailed framework output in an XML style.

exception pcraster.framework.frameworkBase.FrameworkError(msg)

Bases: Exception

class pcraster.framework.frameworkBase.WeakCallback(mcallback)

Bases: object

A Weak Callback object that will keep a reference to the connecting object with weakref semantics.

This allows object A to pass a callback method to object S, without object S keeping A alive.

default_callback(*args, **kwargs)

Called instead of callback when expired

object_deleted(wref)

Called when callback expires

pcraster.framework.frameworkBase.generateNameS(name, sample)

Return a filename based on the name and sample number passed in.

The resulting name contains a directory and a filename part. The sample number is used as the directory name and the name is used as the filename.

The sample number normally ranges from [1, nrSamples].

See also: generateNameT(), generateNameST()

pcraster.framework.frameworkBase.generateNameST(name, sample, timestep)

Return a filename based on the name, sample number and time step.

See also: generateNameT(), generateNameS()

pcraster.framework.frameworkBase.generateNameT(name, time)

Return a filename based on the name and time step passed in.

The resulting name obeys the 8.3 DOS style format. The time step will be added to the end of the filename and be prepended by 0’s if needed.

The time step normally ranges from [1, nrTimeSteps]. The length of the name should be max 8 characters to leave room for the time step.

The name passed in may contain a directory name.

See also: generateNameS(), generateNameST()

pcraster.framework.generalfunctions.createTimeSeriesList(timeSeriesFile)
pcraster.framework.generalfunctions.distancetodownstreamcell(Ldd)
pcraster.framework.generalfunctions.getCellValue(Map, Row, Column)
pcraster.framework.generalfunctions.getCellValueAtBooleanLocation(location, map)
pcraster.framework.generalfunctions.mapeq(mapOne, mapTwo)
pcraster.framework.generalfunctions.normalcorrelated(normalX, normalY, correlation)
pcraster.framework.generalfunctions.onePeriod(self, startTime, endTime, timeStepDuration, currentTimeStep)
pcraster.framework.generalfunctions.printCellValue(self, mapVariable, variableNameToPrint, unit, row, column)
pcraster.framework.generalfunctions.slopeToDownstreamNeighbour(dem, ldd)
pcraster.framework.generalfunctions.slopeToDownstreamNeighbourNotFlat(dem, ldd, minSlope)
pcraster.framework.generalfunctions.timeInputSparse(fileName)
class pcraster.framework.aggregationfunctions.PercentileCalculator(percentiles)

Bases: object

result()
run(arrays)
pcraster.framework.aggregationfunctions.aggregateS(name, sampleNumbers, calculator)
pcraster.framework.aggregationfunctions.aggregateSPerCell(name, sampleNumbers, calculator)
pcraster.framework.aggregationfunctions.average(name, sampleNumbers)

Calculates the average value of each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with average values.

pcraster.framework.aggregationfunctions.correlation(location, independentName, dependentName, locationName, sampleNumbers, timeSteps)
pcraster.framework.aggregationfunctions.createAllGstatRealizations(nameCommandFile, nameOutMapList, nrRealPerGstatCall, sampleNumbers, timeSteps)
pcraster.framework.aggregationfunctions.createGstatRealizations(setOfRealizations, nameCommandFile, nameOutMapList)
pcraster.framework.aggregationfunctions.createtimeseries(names, nameExtension, locations, sampleNumbers, timeSteps)
pcraster.framework.aggregationfunctions.createtimeseriesnewfileformat(names, locations, sampleNumbers, timeSteps, quantiles)
pcraster.framework.aggregationfunctions.deterministicInput(sampleNumbers)
pcraster.framework.aggregationfunctions.mcaveragevariance(names, sampleNumbers, timeSteps)
pcraster.framework.aggregationfunctions.mcpercentiles(names, percentiles, sampleNumbers, timeSteps)
pcraster.framework.aggregationfunctions.percentile(name, sampleNumbers, percentiles)

Calculates a percentile for each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

percentiles

Percentile or list of percentiles to calculate. Percentiles range from [0.0, 1.0].

Returns a raster or a list of rasters with percentiles.

pcraster.framework.aggregationfunctions.probability(name, sampleNumbers)

Calculates the probability that a cell is TRUE.

name

Name of the (boolean) raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with probabilities.

pcraster.framework.aggregationfunctions.sampleMax(name, sampleNumbers)

Calculates the maximum value of each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with maximum values.

pcraster.framework.aggregationfunctions.sampleMin(name, sampleNumbers)

Calculates the minimum value of each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with minimum values.

pcraster.framework.aggregationfunctions.selectSArray(name, sampleNumbers, row, col)

Selects values at row, col from raster name in Monte Carlo samples.

name – Name of raster. sampleNumber – Numbers of MC samples to use. row – Row index of cell to read. col – Col index of cell to read. The returned array does not contain missing values so the size is maximimal sampleNumbers but possibly smaller.

Returned array has elements of type numpy.float32

pcraster.framework.aggregationfunctions.selectSArrays(name, sampleNumbers)
pcraster.framework.aggregationfunctions.staticInput(timeSteps)
pcraster.framework.aggregationfunctions.stddev(name, sampleNumbers)

Calculates the standard deviation of each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with standard deviations.

pcraster.framework.aggregationfunctions.timeseries(name, timeSteps, row, col)
pcraster.framework.aggregationfunctions.uniquesamples(name, sampleNumbers)

Retrieves the unique samples.

name

Name of the raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a list with sets of corresponding loops.

pcraster.framework.aggregationfunctions.variance(name, sampleNumbers)

Calculates the variance of each cell.

name

Name of the scalar raster for which each sample has a realization.

sampleNumbers

List of numbers of samples to aggregate.

Returns a raster with variances.

class pcraster.framework.Timeoutput.TimeoutputTimeseries(tssFilename, model, idMap=None, noHeader=False)

Bases: object

Class to create pcrcalc timeoutput style timeseries

sample(expression)

Sampling the current values of ‘expression’ at the given locations for the current timestep