generate

This module contains all functions needed to setup a network simulation

Functions

check(df)	Checks and corrects input geo/pandas dataframe.
create_network_generator(df)	Generates network generator.
network_layout(df, iteration, iter_num[, …])	Creates a dataframe with information for each path in network.

NSAMPLES = 100

maximum number of samples to be drawn from any group.

MAX_PERMUTATION_NUM = 7

maximum number of points below which permulations are possible

MIN_NUM_SAMPLE = 3

minimum number of points above which samples can be drawn

MAX_ITERATIONS = 5000

maximum total number of iterations allowed in the simulation

check(df)

Checks and corrects input geo/pandas dataframe.

Parameters:df (geo/dataframe) – contains locations used in the simulation Returns:c_df – corrected geo/dataframe ready for netsim Return type:dataframe

Notes

This function checks for the existence columns needed in the netsim simulation. Columns must have the appropriate header (as shown below). Columns that do not exist will be generated and populated with default values. The validity of values in existing columns is also checked. Minor errors and corrections are notified. Major errors raise an exception error.

The following columns need to be present:

• id: exclusive identifier for each location.
• group: identifies a location as being part of a specific group. Groups can be of any size. Groups of size 1 will automatically mixed with the following group. A column with a single group affiliation will be created in case this column does not exist (default value is 1).
• seq: identifies rank/ordering of a location within a group. There are two possible scenarios:
  • No ordering/ ranking (default). Within each group a single value is used for all sites in that group. Depending on the number of locations in the group the simulation with either generate all possible permutations or num_samples of randomized samples (with repetition).
  • Ordering /ranking. Identify all sites in a group with a increasing monotonic sequence of numbers (no repetitions).

create_network_generator(df)

Generates network generator.

Parameters:df (geo/dataframe) – contains locations, group membership and parameters used in netsim Yields:netgentor (generator) – network generator Returns:

• df_net_info (dataframe) – contains information about each network (see Notes below)
• total_num_iter (int) – total number of iterations

Notes

This function returns three different outputs:

1. It primarily returns a network generator that results from the cartesian product of separate generators (one per group of locations as identified thru the group column). Each, group, generator may be of one of these three types:
   • single: returns always the same combination of locations.
   • sample: returns a shuffled version of the locations. n.b. repetition can occur.
   • permutation: returns permutation of the locations (no repetition).
2. Generates a dataframe, df_net_info, containing generator information for each group (number of locations, total number of iterations, generator type).
3. Total number of iterations that results from the combination of all group generators.

network_layout(df, iteration, iter_num, df_net=None, twoway=False, opt='close')

Creates a dataframe with information for each path in network.

Parameters:

• df (dataframe) – contains list of locations, group membership used to generate a network
• iteration (tuple of tuples) – a tuple containing one or several tuples, one per group, representing a single network iteration
• iter_num (int) – iteration identifier
• df_net (dataframe, optional) – contains the identifiers of the origin and destination of each path plus the iteration identifier
• twoway (boolean) – if True two-way paths are generated for each pair of locations in a network. Default: False.
• opt (string) –

  type of network to generate. The options are as follows:

  • close: This option defines an independent close network of paths for each group. In this network, the locations are connected in order so that the first location is connected to the second one and so one until the last location is conected to the first. No network is defined if the first group is made of a single location.
  • central: This option defines a network of that consists of centralized set of paths from the locations of the first group to all of the locations in the remaining groups.
  • decentral: This option defines a network of paths so that the locations of each group are connected to the locations of the following (lower level) group.
  • distributed: This option defines a network of paths similar to decentral, where the locations of each group are connected to the locations of the following (lower level) group, and in addition, locations within each group are interconnected.
  • all: This option defines a network of paths from amongst all locations.

Returns:

df_net – contains the identifiers of the origin and destination of each path plus the iteration identifier

Return type:

dataframe, optional

Notes

This function takes a dataframe with locations, a list of lists containing an ordering of these locations obtained after running create_network_generator() function and a iteration identifier number. It generates, or updates, the df_net dataframe with the identifiers of the origin and destination of each path that make up the path network for this specific iteration.