Project File

File extension: prj

This file object supports spatial objects.

File Object

class gsshapy.orm.ProjectFile(name=None, map_type=None)[source]

Bases: sqlalchemy.ext.declarative.api.Base, gsshapy.base.file_base.GsshaPyFileObjectBase

Object interface for the Project File.

The project file is the main configuration file for GSSHA models. As such, the project file object is different than most of the other file objects. In addition to providing read and write methods for the project file, a project file instance also provides methods for reading and writing the GSSHA project as a whole. These methods should be the primary interface for working with GSSHA models.

The project file is composed of a series of cards and values. Each card in the project file is read into a supporting object: ProjectCard.

See: http://www.gsshawiki.com/Project_File:Project_File

tableName = 'prj_project_files'

Database tablename

id

PK

precipFileID

FK

mapTableFileID

FK

channelInputFileID

FK

stormPipeNetworkFileID

FK

hmetFileID

FK

nwsrfsFileID

FK

orographicGageFileID

FK

gridPipeFileID

FK

gridStreamFileID

FK

projectionFileID

FK

replaceParamFileID

FK

replaceValFileID

FK

srid

SRID

projectCards

RELATIONSHIP

mapTableFile

RELATIONSHIP

channelInputFile

RELATIONSHIP

precipFile

RELATIONSHIP

stormPipeNetworkFile

RELATIONSHIP

hmetFile

RELATIONSHIP

nwsrfsFile

RELATIONSHIP

orographicGageFile

RELATIONSHIP

gridPipeFile

RELATIONSHIP

gridStreamFile

RELATIONSHIP

projectionFile

RELATIONSHIP

replaceParamFile

RELATIONSHIP

replaceValFile

RELATIONSHIP

timeSeriesFiles

RELATIONSHIP

outputLocationFiles

RELATIONSHIP

maps

RELATIONSHIP

linkNodeDatasets

RELATIONSHIP

genericFiles

RELATIONSHIP

wmsDatasets

RELATIONSHIP

projectFileEventManager

RELATIONSHIP

fileExtension

STRING

name

STRING

mapType

INTEGER

appendDirectory(directory, projectFilePath)[source]

Append directory to relative paths in project file. By default, the project file paths are read and written as relative paths. Use this method to prepend a directory to all the paths in the project file.

Parameters:
  • directory (str) – Directory path to prepend to file paths in project file.
  • projectFilePath (str) – Path to project file that will be modified.
readProject(directory, projectFileName, session, spatial=False, spatialReferenceID=None)[source]

Read all files for a GSSHA project into the database.

This method will read all the files, both input and output files, that are supported by GsshaPy into a database. To use GsshaPy more efficiently, it is recommended that you use the readInput method when performing pre-processing tasks and readOutput when performing post-processing tasks.

Parameters:
  • directory (str) – Directory containing all GSSHA model files. This method assumes that all files are located in the same directory.
  • projectFileName (str) – Name of the project file for the GSSHA model which will be read (e.g.: ‘example.prj’).
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • spatial (bool, optional) – If True, spatially enabled objects will be read in as PostGIS spatial objects. Defaults to False.
  • spatialReferenceID (int, optional) – Integer id of spatial reference system for the model. If no id is provided GsshaPy will attempt to automatically lookup the spatial reference ID. If this process fails, default srid will be used (4326 for WGS 84).
readInput(directory, projectFileName, session, spatial=False, spatialReferenceID=None)[source]

Read only input files for a GSSHA project into the database.

Use this method to read a project when only pre-processing tasks need to be performed.

Parameters:
  • directory (str) – Directory containing all GSSHA model files. This method assumes that all files are located in the same directory.
  • projectFileName (str) – Name of the project file for the GSSHA model which will be read (e.g.: ‘example.prj’).
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • spatial (bool, optional) – If True, spatially enabled objects will be read in as PostGIS spatial objects. Defaults to False.
  • spatialReferenceID (int, optional) – Integer id of spatial reference system for the model. If no id is provided GsshaPy will attempt to automatically lookup the spatial reference ID. If this process fails, default srid will be used (4326 for WGS 84).
readOutput(directory, projectFileName, session, spatial=False, spatialReferenceID=None)[source]

Read only output files for a GSSHA project to the database.

Use this method to read a project when only post-processing tasks need to be performed.

Parameters:
  • directory (str) – Directory containing all GSSHA model files. This method assumes that all files are located in the same directory.
  • projectFileName (str) – Name of the project file for the GSSHA model which will be read (e.g.: ‘example.prj’).
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • spatial (bool, optional) – If True, spatially enabled objects will be read in as PostGIS spatial objects. Defaults to False.
  • spatialReferenceID (int, optional) – Integer id of spatial reference system for the model. If no id is provided GsshaPy will attempt to automatically lookup the spatial reference ID. If this process fails, default srid will be used (4326 for WGS 84).
readInputFile(card_name, directory, session, spatial=False, spatialReferenceID=None, **kwargs)[source]

Read specific input file for a GSSHA project to the database.

Parameters:
  • card_name (str) – Name of GSSHA project card.
  • directory (str) – Directory containing all GSSHA model files. This method assumes that all files are located in the same directory.
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • spatial (bool, optional) – If True, spatially enabled objects will be read in as PostGIS spatial objects. Defaults to False.
  • spatialReferenceID (int, optional) – Integer id of spatial reference system for the model. If no id is provided GsshaPy will attempt to automatically lookup the spatial reference ID. If this process fails, default srid will be used (4326 for WGS 84).
Returns:

file object

readOutputFile(card_name, directory, session, spatial=False, spatialReferenceID=None, **kwargs)[source]

Read specific input file for a GSSHA project to the database.

Parameters:
  • card_name (str) – Name of GSSHA project card.
  • directory (str) – Directory containing all GSSHA model files. This method assumes that all files are located in the same directory.
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • spatial (bool, optional) – If True, spatially enabled objects will be read in as PostGIS spatial objects. Defaults to False.
  • spatialReferenceID (int, optional) – Integer id of spatial reference system for the model. If no id is provided GsshaPy will attempt to automatically lookup the spatial reference ID. If this process fails, default srid will be used (4326 for WGS 84).
Returns:

file object

writeProject(session, directory, name)[source]

Write all files for a project from the database to file.

Use this method to write all GsshaPy supported files back into their native file formats. If writing to execute the model, increase efficiency by using the writeInput method to write only the file needed to run the model.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • directory (str) – Directory where the files will be written.
  • name (str) – Name that will be given to project when written (e.g.: ‘example’). Files that follow the project naming convention will be given this name with the appropriate extension (e.g.: ‘example.prj’, ‘example.cmt’, and ‘example.gag’). Files that do not follow this convention will retain their original file names.
writeInput(session, directory, name)[source]

Write only input files for a GSSHA project from the database to file.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • directory (str) – Directory where the files will be written.
  • name (str) – Name that will be given to project when written (e.g.: ‘example’). Files that follow the project naming convention will be given this name with the appropriate extension (e.g.: ‘example.prj’, ‘example.cmt’, and ‘example.gag’). Files that do not follow this convention will retain their original file names.
writeOutput(session, directory, name)[source]

Write only output files for a GSSHA project from the database to file.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • directory (str) – Directory where the files will be written.
  • name (str) – Name that will be given to project when written (e.g.: ‘example’). Files that follow the project naming convention will be given this name with the appropriate extension (e.g.: ‘example.prj’, ‘example.cmt’, and ‘example.gag’). Files that do not follow this convention will retain their original file names.
getFileKeys()[source]

Retrieve a list of file keys that have been read into the database.

This is a utility method that can be used to programmatically access the GsshaPy file objects. Use these keys in conjunction with the dictionary returned by the getFileObjects method.

Returns:List of keys representing file objects that have been read into the database.
Return type:list
getFileObjects()[source]

Retrieve a dictionary of file objects.

This is a utility method that can be used to programmatically access the GsshaPy file objects. Use this method in conjunction with the getFileKeys method to access only files that have been read into the database.

Returns:Dictionary with human readable keys and values of GsshaPy file object instances. Files that have not been read into the database will have a value of None.
Return type:dict
getCard(name)[source]

Retrieve card object for given card name.

Parameters:name (str) – Name of card to be retrieved.
Returns:Project card object. Will return None if the card is not available.
Return type:ProjectCard or None
setCard(name, value, add_quotes=False)[source]

Adds/updates card for gssha project file

Parameters:
  • name (str) – Name of card to be updated/added.
  • value (str) – Value to attach to the card.
  • add_quotes (Optional[bool]) – If True, will add quotes around string. Default is False.
deleteCard(card_name, db_session)[source]

Removes card from gssha project file

getModelSummaryAsKml(session, path=None, documentName=None, withStreamNetwork=True, withNodes=False, styles={})[source]

Retrieve a KML representation of the model. Includes polygonized mask map and vector stream network.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • path (str, optional) – Path to file where KML file will be written. Defaults to None.
  • documentName (str, optional) – Name of the KML document. This will be the name that appears in the legend. Defaults to ‘Stream Network’.
  • withStreamNetwork (bool, optional) – Include stream network. Defaults to True.
  • withNodes (bool, optional) – Include nodes. Defaults to False.
  • styles (dict, optional) –

    Custom styles to apply to KML geometry. Defaults to empty dictionary.

    Valid keys (styles) include:
    • streamLineColor: tuple/list of RGBA integers (0-255) e.g.: (255, 0, 0, 128)
    • streamLineWidth: float line width in pixels
    • nodeIconHref: link to icon image (PNG format) to represent nodes (see: http://kml4earth.appspot.com/icons.html)
    • nodeIconScale: scale of the icon image
    • maskLineColor: tuple/list of RGBA integers (0-255) e.g.: (255, 0, 0, 128)
    • maskLineWidth: float line width in pixels
    • maskFillColor: tuple/list of RGBA integers (0-255) e.g.: (255, 0, 0, 128)
Returns:

KML string

Return type:

str

getModelSummaryAsWkt(session, withStreamNetwork=True, withNodes=False)[source]

Retrieve a Well Known Text representation of the model. Includes polygonized mask map and vector stream network.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • withStreamNetwork (bool, optional) – Include stream network. Defaults to True.
  • withNodes (bool, optional) – Include nodes. Defaults to False.
Returns:

Well Known Text string

Return type:

str

getModelSummaryAsGeoJson(session, withStreamNetwork=True, withNodes=False)[source]

Retrieve a GeoJSON representation of the model. Includes vectorized mask map and stream network.

Parameters:
  • session (sqlalchemy.orm.session.Session) – SQLAlchemy session object bound to PostGIS enabled database
  • withStreamNetwork (bool, optional) – Include stream network. Defaults to True.
  • withNodes (bool, optional) – Include nodes. Defaults to False.
Returns:

GeoJSON string

Return type:

str

getGridByCard(gssha_card_name)[source]

Returns GSSHAGrid object of GSSHA grid

Paramters:
gssha_card_name(str): Name of GSSHA project card for grid.
Returns:GSSHAGrid
getGrid(use_mask=True)[source]

Returns GSSHAGrid object of GSSHA model bounds

Paramters:
use_mask(bool): If True, uses watershed mask. Otherwise, it uses the elevaiton grid.
Returns:GSSHAGrid
getIndexGrid(name)[source]

Returns GSSHAGrid object of index map

Paramters:
name(str): Name of index map in ‘cmt’ file.
Returns:GSSHAGrid
getWkt()[source]

Returns GSSHA projection WKT string

getOutlet()[source]

Gets the outlet latitude and longitude.

Returns:Latitude of grid cell center. longitude(float): Longitude of grid cell center.
Return type:latitude(float)
setOutlet(latitude, longitude, outslope=None)[source]

Sets the outlet grid cell information in the project file.

Parameters:
  • latitude (float) – Latitude of grid cell center.
  • longitude (float) – Longitude of grid cell center.
  • outslope (Optional[float]) – River slope at outlet.
calculateOutletSlope(elevation_grid=None, mask_grid=None)[source]

Attempt to determine the slope at the OUTLET

Supporting Objects

class gsshapy.orm.ProjectCard(name, value)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Object containing data for a single card in the project file.

tableName = 'prj_project_cards'

Database tablename

id

PK

projectFileID

FK

projectFile

RELATIONSHIP

name

STRING

value

STRING

write(originalPrefix, newPrefix=None)[source]

Write project card to string.

Parameters:
  • originalPrefix (str) – Original name to give to files that follow the project naming convention (e.g: prefix.gag).
  • newPrefix (str, optional) – If new prefix is desired, pass in this parameter. Defaults to None.
Returns:

Card and value as they would be written to the project file.

Return type:

str