Bulk upload of adjustments

Adjustments can be bulk uploaded into the platform through a request here. The data schema below must be followed for the upload to occur. Adjustments can either be uploaded as a CSV file or as a zipped (.zip) shapefile of polygons. CSV files and shapefiles use different methods to connect adjustments to blocks, see below for details on the methods available:

Note

The ability to bulk upload adjustments is not yet available in the user interface. If you would like to upload your adjustments, please format them to fit the data schema and send the data with a request here.

Connecting adjustments to blocks

Three methods are available to connect your adjustments to specific blocks. The set of adjustments to upload should be formatted to only utilize one method:

  1. CSV: use a block_id column to directly associate the adjustment with the Census FIPS code of block polygons. This is the preferred and most accurate method of association. For adjustments that are associated with more than one block ID, denote multiple blocks using a semicolon ; as a delimiter, for example: 060014001001000; 060014001001001

  2. CSV: use columns x (longitude) and y (latitude) to hold coordinates of the adjustment address or centroid to associate with the intersecting block ID FIPS code. Coordinates must be in the World Geodetic System 1984 (WGS84) coordinate system.

  3. Shapefile: use polygons denoting the adjustment area to associate the adjustment with intersecting block polygons block ID FIPS code. Adjustment polygon intersection occurs using a within block polygon centroid method.

Each method requires a different data schema for specific columns to include in your file to upload, see below:

Adjustments as CSV Method 1: block_id columns

Column Name

Data Type

Required

Description

block_id

String

Yes

block_id must be a properly formatted Census FIPS code.
For adjustments that are associated with more than one block id,
denote multiple blocks using a semicolon ; as a
delimiter, for example: 060014001001000; 060014001001001
Adjustments as CSV Method 2: xy coordinate columns

Column Name

Data Type

Required

Description

x

Float

Yes

Longitude coordinate of adjustment address or centroid.

y

Float

Yes

Latitude coordinate of adjustment address or centroid.

Adjustment attribute data schema

A basic set of columns are required to upload adjustments and are identical to those required in the user interface adjustments. An adjustment record requires at a minimum one of the following filter columns: ‘residential_filter’, ‘household_filter’, ‘employment_filter’, ‘job_spaces_filter’, ‘non_residential_space_filter’, however multiple filters can be specified on a single adjustment record.

Each filter column must contain either:

a) only a targetValue with a numeric value specified that will override the attribute that corresponds to the filter column. Example: targetValue: 22; or

b) must have all four elements listed below delimited by a comma ,:

  1. a filter with the name of filter to use.

  2. an operator to denote the filter logic.

  3. a value with a numeric value specified to filter by.

  4. a targetValue with a numeric value specified that will override values that match the filter.

Example: filter: sector_id, operator: =, value: 2, targetValue: 22

Each filter column type has its own set of valid operators and filters listed in the table below. Values must correspond to the filter type attribute values used in your base data tables, for example, if using a building_type filter the values specified must correspond to the building_type_ids in your base data building types table.

Required and optional columns and their data schema are described below:

Adjustments as CSV:

Column Name

Data Type

Required

Filters

Operators

Description

Example value

name

String

Yes

Name of adjustment

start_year

Float

Yes

The year in which the adjustments
begin in the simulation.

end_year

Float

Yes

The year in which the adjustments
end in the simulation. Adjustment will persist
until the specified end year or
until overridden by another adjustment.

tags

String

Yes

Tags to use to link with scenarios. For setting
more than one tag on a adjustment, list the tags and
separate each one using a semicolon ; as
a delimiter, for example: Baseline; High growth

notes

String

No

Notes can be added to include any other pertinent
information for context.

residential_filter

String

No

building_type

=

Residential unit filter (residential units)

filter: building_type, operator: =, value: 1, targetValue: 22 or targetValue: 22

household_filter

String

No

persons, cars, income, age_of_head, workers, children

>, >, =, >=, <=

Household attribute filter (selected attribute unit)

filter: tenure, operator: =, value: 2, targetValue: 22 or targetValue: 22

employment_filter

String

No

sector_id

=

Jobs filter (number of jobs)

filter: sector_id, operator: =, value: 2, targetValue: 22 or targetValue: 22

job_spaces_filter

String

No

building_type

=

Job spaces filter (number of job spaces)

filter: sector_id, operator: =, value: 2, targetValue: 22 or targetValue: 22

non_residential_space_filter

String

No

building_type

=

Non-residential space filter (square feet or meters)

filter: building_type, operator: =, value: 10, targetValue: 22 or targetValue: 22

Note

If your model is using the default synthesized base year data provided by UrbanSim see the variables and codes available to use for attribute filtering in the respective tables in the base year data schema section. Some attributes may not be available or compatible with your specific model or base data. Contact us here for questions related to what attributes are supported by your specific model system.