TSTool-Vol2-CommandReference - Laserfiche WebLink

-1 AdjustExtremes() Command TSTool Documentation Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards) will be modified. • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble will be modified. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards) will be modified. • SelectedTS – the time series are those selected with the SelectTimeSeries() command. AllTS TSID The time series identifier or alias for the time series to be modified, using the * wildcard character to match multiple time series. Required if TSList= *TSID. EnsembleID The ensemble to be modified, if processing an ensemble. Required if TSList= EnsembleID. AdjustMethod Only the Average adjust method is implemented, in which adjusted data values are set to the average over the adjusted period, necessary to maintain the total/mass of the original values. This method adjusts extreme values by considering neighboring values equally on each side of the point in question. When adjusting minimum values, neighboring values are added until the average is above the allowed extreme value, and all values that make up the sum are then set to the average value. Missing values remain missing and therefore this command should only be applied to filled data. If a satisfactory result cannot be reached within this limit, then the original values are not changed. Changed values are listed in the time series history, which is viewed with the time series properties. Applying the command will result in the time series having periods of constant value, with the length of the period being controlled by the magnitude of the extreme value. None – must be specified. Extreme ToAdjust Indicate whether minimum (AdjustMinimum) or maximum (AdjustMaximum) values to be adjusted. None – must be specified. ExtremeValue The extreme value that is the limit of acceptable values. None – must be specified. MaxIntervals Indicates how many values on each side of a point are allowed to be examined. 0, indicating no limit. AnalysisStart The date/time to start analyzing data. Full period. AnalysisEnd The date/time to end analyzing data. Full period. A sample command file using data from the State of Colorado’s HydroBase is as follows: # 06759000 -BIJOU CREEK NEAR WIGGINS, CO. 06759000.USGS.Streamflow .Day~HydroBase AdjustExtremes(TSList=AllMatchingTSID,TSID="06759000.USGS.Streamflow.Day", AdjustMethod=Average,ExtremeToAdjust=AdjustMinimum,ExtremeValue=0,MaxIntervals=0) Command Reference – AdjustExtremes() -2 46 Command Reference: AnalyzePattern() Determine historical average patterns for monthly time series Version 09.05.01, 2009-10-28 The AnalyzePattern() command creates the pattern file for use with the FillPattern() command (see also SetPatternFile()). Each time series to be processed is analyzed as follows: 1. Create a time series to contain the pattern identifiers for each month (e.g., DRY, AVG, WET). 2. For each month, determine the monthly values for the time series being analyzed (e.g., find all of the January values). 3. Rank the values in ascending order. 4. Evaluate the percentile rank information for non-missing values and assign in the pattern time series an appropriate pattern identifier. For example, if the percentile values are .25 and .75, assign the first pattern identifier to values < 25% of the non-missing count, assign the second pattern identifier to non-missing values >= 25% and < 75%, and assign the third identifier to the non-missing values >= 75%. The resulting pattern time series is then written to a file. This command is enabled for monthly data only. See below for an example of a fill pattern file. One or more patterns can be included in each pattern file, similar to StateMod time series files (see the StateMod Input Type Appendix), and multiple pattern files can be used, if appropriate. # Years Shown = Water Years # Missing monthly data filled by the Mixed Station Method, USGS 1989 # Time series identifier = 09034500.CRDSS_USGS.QME.MONTH.1 # Description = COLORADO RIVER AT HOT SULPHUR SPRINGS, CO. # -e-b----------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb------eb--------e 10/1908 -9/1996 ACFT WYR 1909 09034500 AVG AVG AVG WET WET AVG AVG AVG WET WET WET WET 1910 09034500 WET WET WET WET WET WET AVG AVG AVG AVG AVG AVG 1911 09034500 AVG AVG WET AVG AVG AVG AVG WET WET WET AVG WET 1912 09034500 WET WET WET WET WET AVG AVG WET WET WET WET WET ...ommitted... The pattern file will by default contain all available data for the overlapping period and will be written in calendar year. The output period can be set with the SetOutputPeriod() command and the output year type can be set with the SetOutputYearType() command. 47 Command Reference – AnalyzePattern() -1 AnalyzePattern() Command TSTool Documentation The following dialog is used to edit the AnalyzePattern() command and illustrates the syntax of the command. AnalyzePattern AnalyzePattern() Command Editor The command syntax is as follows: AnalyzePattern(Parameter=Value,…) Command Parameters Parameter Description Default TSList Indicates the list of time series to be processed, one of: • AllMatchingTSID – all time series that match the TSID (single TSID or TSID with wildcards). • AllTS – all time series before the command. • EnsembleID – all time series in the ensemble. • FirstMatchingTSID – the first time series that matches the TSID (single TSID or TSID with wildcards). • LastMatchingTSID – the last time series that matches the TSID (single TSID or TSID with wildcards). None – must be specified. Command Reference – AnalyzePattern() -2 48 TSTool Documentation AnalyzePattern() Command 􀂃 SelectedTS – the time series selected with the SelectTimeSeries() command. TSID The time series identifier or alias for the time series to be processed, using the * wildcard character to match multiple time series. Required if TSList=*TSID. EnsembleID The ensemble to be processed, if processing an ensemble. Required if TSList=EnsembleID. Method Method used to determine the patterns. Currently only Percentile is recognized. Percentile Percentile A comma-separated list of percentiles for cutoffs, used when Method=Percentile. Values should be 0 to 1 (e.g., .25, .75) None – must be specified. PatternID The pattern identifiers to use, corresponding to the percentiles. Specify one more than the number of percentiles (e.g., DRY,AVG,WET). None – must be specified. OutputFile Output file to write, which will contain the pattern information. Currently only the StateMod pattern file format is supported. None – must be specified. TableID The identifier for a new table to be created, containing the sample values for each month adjoining the percentile positions. Each time series will be listed in the first column as per the DataRow parameter. For N percentile values, the first N-1 values in the table will correspond to the last value below a percentile cutoff and the Nth value will be the first value above the Nth percentile value. Optional – table will not be created by default. DataRow The contents of the first column, indicating the time series. Location, data type, and units, if available. Legacy Indicates whether to duplicate legacy behavior (True) or use current behavior (default, False). A bug was fixed in TSTool 9.05.02 to correct a bug where the last value in each bin sometimes should have been in the larger cutoff bin. False – use current behavior. 49 Command Reference – AnalyzePattern() -3 AnalyzePattern() Command TSTool Documentation A sample command file to analyze streamflow data from the State of Colorado’s HydroBase and save statistics in a table is as follows: # 06720500 -SOUTH PLATTE RIVER AT HENDERSON 06720500.DWR.Streamflow.Month~HydroBase # 06754000 -SOUTH PLATTE RIVER NEAR KERSEY 06754000.DWR.Streamflow.Month~HydroBase AnalyzePattern(TSList=AllTS,Method =Percentile, Percentile="0.25,0.75",PatternID="DRY,AVG,WET",OutputFile="Div1.pat", TableID=”Statistics”,DataRow=”%L, %U”) The following figure illustrates the resulting statistics: AnalyzePatter_Tabl e Command Reference – AnalyzePattern() -4 50 Command Reference – AnalyzeNetworkPointFlow () -1 Command Reference: AnalyzeNetworkPointFlow() Analyze a node/link network to calculate “point flow” for nodes Version 10.21.00, 2013-07-13 The AnalyzeNetworkPointFlow() command takes as input information to define a “flow network”, associates input time series with each node in the network, and computes mass balance time series at each node. Although the network is intended to represent a physical network such as a stream system, it also can represent other flow networks such as transportation or other mass/energy conservation systems. This command differs from the functionality of other network analysis tools as follows: • Daily administration tools, such as the State of Colorado’s Colorado Water Rights Administration Tool (CWRAT) perform a point flow analysis for a single day, which only requires knowing one day’s input values, whereas AnalyzeNetworkPointFlow()analyzes time series for a specified period. • More sophisticated models, such as the State of Colorado’s StateMod water allocation model, perform allocation decisions within each time step for the full period, whereas AnalyzeNetworkPointFlow()performs a sequence of basic time series manipulations that can be quickly configured. It may be possible to utilize the network data from tools such as those mentioned above with the AnalyzeNetworkPointFlow() command. 51 AnalyzeNetworkPointFlow() Command TSTool Documentation Command Reference – AnalyzeNetworkPointFlow () -2 The following figure illustrates the network connectivity and mass balance that is performed at each node. Currently “on-channel” reservoirs with storage are not supported and gain/loss can only be computed in non-branching networks – these features and others necessary to model more complex networks will be added in the future; however, this command is not intended to replace more complex models. Consequently the command currently is suitable for analysis of a main stem river with no on-channel reservoirs. AnalyzeNetworkPointFLow AnalyzeNetworkPointFlow() Network and Node Mass Balance 52 TSTool Documentation AnalyzeNetworkPointFlow() Command Command Reference – AnalyzeNetworkPointFlow () -3 The network is defined as a table containing a list of node identifiers with associated properties, as illustrated in the following figure. AnalyzeNetworkPointFLow AnalyzeNetworkPointFlow() Network Input Table In this example the network is defined in an Excel file, the ReadTableFromExcel() command is used to read the table, and the table is used as input to the AnalyzeNetworkPointFlow() command The network definition table columns from the above figure are as follows (note, however, that the column names are user defined and are specified as parameters to the AnalyzeNetworkPointFlow() command: AnalyzeNetworkPointFlow() Network Input Table Column Description Network Table Column Description NodeID The location ID for the network node, typically corresponding to the location ID in time series identifiers. The column is indicated to the command using the NodeIDColumn parameter. NodeName The node name, useful because NodeID is generally terse and nondescriptive, used in messages. The column is indicated to the command using the NodeNameColumn parameter. NodeType The node type, needed to define node behavior (e.g., whether time series values get added, subtracted, reset at node). The node types are userdefined, although types often are defined by modeling conventions. The column is indicated to the command using the NodeTypeColumn parameter. The behavior corresponding to node types is defined by using command parameters (NodeAddTypes, NodeSubtractTypes, NodeOutflowTypes, NodeFlowThroughTypes). NodeDist The node distance along the flow path. Typically the distance is measured relative to the lowest point on the network. The distance is used to estimate gain/loss when GainMethod=Distance is specified as a command 53 AnalyzeNetworkPointFlow() Command TSTool Documentation Command Reference – AnalyzeNetworkPointFlow () -4 Network Table Column Description parameter. NodeWeight Used when GainMethod=Weight. The weights indicate the relative weight of the reach gain/loss to be distributed between nodes on the reach. For example, specify a best estimate of the percentage of reach loss that occurs above each node. Or, specify as a rate of gain/loss when used with GainMethod=DistanceWeight (but in this case the distance*weight product will be normalized to ensure that the reach gain/loss is equalized between known point flows). DownstreamNodeID The location ID for the downstream node, needed to define network connectivity. The AnalyzeNetworkPointFlow() command creates output time series with the data types indicated in the following table. AnalyzeNetworkPointFlow() Network Input Table Column Description Column Description NodeInflow Sum of outflows from upstream nodes, which are consequently inflows to the current node (lagged routing currently is not implemented). NodeAdd Time series added at the node (for example immediately off-channel reservoir release or measured return flow). NodeSubtract Time series subtracted at the node (for example diversion). NodeUpstreamGain Gain (positive) or loss (negative) between immediate upstream node(s) and the current node (missing if gain/loss is not computed). NodeOutflow Outflow from the node, which takes into account inflow and any additions and subtractions at the node. NodeUpstreamReachGain Gain (positive) or loss (negative) between upstream known flow node(s) and the current node (missing if gain/loss is not computed). NodeInflowWithGain NodeInflow + NodeUpstreamReachGain (missing if gain/loss are not computed). NodeOutflowWithGain NodeOutflow + NodeUpstreamReachGain (missing if gain/loss are not computed). NodeStorage Storage at the node after additions and subtractions (currently always zero, will enhance in the future to handle on-channel reservoirs). 54 TSTool Documentation AnalyzeNetworkPointFlow() Command Command Reference – AnalyzeNetworkPointFlow () -5 The following figure illustrates the output time series corresponding to the data types listed in the above table: AnalyzeNetworkPointFLow_OutputTS AnalyzeNetworkPointFlow() Output Time Series Table The following logic is used to analyze the network. Currently this logic is performed by navigating the network from most upstream to downstream and processing all timesteps for a node before moving to the next node. 1. The network is navigated from top to bottom. When a confluence is found (a node with more than one upstream node), each confluence is processed from the top down to the confluence point. Of particular importance is the concept of a “stream reach”, which is the reach between known flow points, because mass balance is enforced at known flow points and gain/loss can be estimated between the known flow points. a. The data type for the node (see *DataType command parameters) is used to retrieve the relevant time series for the node. The first time series that matches the location ID, data type, and interval is used as input for the node. The time series must have been read prior to the AnalyzeNetworkPointFlow() command. For example, use the CopyTable() command to copy a subset of the network table’s NodeID values and then use the ReadTimeSeriesList() command with the list of identifiers. b. Calculate the node’s inflow: i. Node types that set outflow, indicated by the NodeOutflowDataTypes parameter (e.g., StreamGage): • NodeInflow = input time series for node ii. All other node types: • NodeInflow = sum of upstream node outflows c. Calculate the node’s outflow: i. Node types that add, indicated by the NodeAddDataTypes parameter (e.g., Return, Import): • NodeOutflow = NodeInflow + added time series ii. Node types that subtract, indicated by the NodeSubtractDataTypes parameter (e.g., Diversion): • NodeOutflow = NodeInflow -subtracted time series 55 AnalyzeNetworkPointFlow() Command TSTool Documentation Command Reference – AnalyzeNetworkPointFlow () -6 iii. Node types that set outflow, indicated by the NodeOutflowDataTypes parameter (e.g., StreamGage): • NodeOutflow = NodeInflow iv. Node types that let flow through, indicated by the NodeFlowThroughDataTypes parameter (e.g., InstreamFlow): • NodeOutflow = NodeInflow. d. For known flow points (e.g., StreamGage node type), set the reach gain/loss: i. NodeUpstreamReachGain = difference between upstream node outflow and known flow at downstream node in reach e. If gain/loss is being estimated and a known flow node encountered (e.g., StreamGage), gain/loss between this node and the nearest upstream node(s) is compute. This has only been implemented for the case where all intervening nodes are in a non-branching reach. i. First calculate the distribution factor by which the reach gain (see previous step) will be distributed to each node in the reach: • If the GainMethod=None, no adjustment to flows is made and the gain/loss upstream of the know flow node will result in a discontinuous jump because no gain/loss adjustment is made. • If the GainMethod=Distance, use the node distance data from the network table to prorate the gain/loss in the stream reach. The difference in distance between the upstream node and the current node is set to weight for prorating the reach gain/loss. Use this method if the gain/loss rate is the same throughout the reach and therefore only the distance between nodes controls the gain/loss. • If the GainMethod=Weight, the gain/loss is prorated by the weights specified by the NodeWeightColumn parameter (or weight equally if the weights are not specified in the network table). The weight of the upstream known flow node is not used. Use this method if the relative gain/loss for each node within the reach can be specified. • If the GainMethod=DistanceWeight, the gain/loss is prorated by the product of the weights specified by the NodeWeightColumn parameter (or weight equally if the weights are not specified in the network table) and by the values from the NodeDistanceColumn. The weight of the upstream known flow node is not used. Use this method if the relative rate of gain/loss for each node can be specified, but overall gain/loss is also a function of the distance. Even though a rate is specified, the calculated gain/loss may be slightly different because the overall reach gain/loss must be balanced at known flow points for each time step. • Multiply NodeUpstreamReachGain by the gain/loss distribution factor to calculate NodeReadGain for each node. • Compute the cumulative gain/loss for the node by summing NodeUpstreamNodeGain for each upstream node and set to NodeUpstreamReachGain for the current node. 2. Analysis statistics optionally are written to an output table, which contains a row for each network node. Statistics include information such as the number of missing values in the input time series. This information can be used to evaluate the quality of the analysis. This feature has not yet been implemented. 56 TSTool Documentation AnalyzeNetworkPointFlow() Command Command Reference – AnalyzeNetworkPointFlow () -7 Issues that need to be considered include: 1. Missing data in input result in missing data in calculated values. Use TSTool features to fill missing data in time series before using as input to the analysis. Because this may be a major effort, especially for a long analysis period, it may be appropriate to read time series from model data sets. It is envisioned that the output table will provide feedback on how much missing data there is and how it impacts the analysis. 2. TSTool’s graphing tool currently does not allow graphing lines as a step function in the case where no gain/loss is computed. Instead, the line connects the data points. An enhancement to the graphing tool is needed. 3. TSTool does not provide a way to graph a stream reach where the graph values are pulled from each time series for a point in time. Ideally a visualization tool would allow “scrolling” through dates and showing the river reach with flow on the Y axis and node distance on the X axis, although it would be tedious to have to scroll through the period. 4. There may be cases where a subtraction at the node takes all of the flow resulting in a zero or negative value, essentially causing the node to be a known zero point flow. For example, in Colorado, a river call may result in a river drying up during the call. It is possible to estimate when this occurs, but the data quality may be low. Currently TSTool allows negative flows in this case, which indicates that input time series or the simple gain method calculations do not accurately represent the system. One option in this case is to use the TSTool AdjustExtremes() command, which maintains mass balance around the extreme values. It is important to understand that such a point flow analysis represents a snapshot of the system at any point in time, but does not route flows through the network. Known flows at stream gages are used as fixed values from which other data are estimated. Gains and losses are representative of the network system, essentially interpolating over time and distance. This type of analysis introduces errors in cases where the lag time between nodes would result in significant differences if lagging were considered. In the physical system, changing an upstream flow would result in lagged impacts due to routing; however, the point flow analysis shows the impacts to downstream nodes in the same time step. A more sophisticated model with routing would be needed to represent actual conditions. However, the point flow analysis will be reasonably accurate if gains and losses are occurring because of fairly static phenomena (e.g., groundwater interactions that do not change rapidly within the network travel time). One way to work around these limitations is to use a longer interval, for example monthly instead of daily, in input time series or convert the point flow analysis results. 57 AnalyzeNetworkPointFlow() Command TSTool Documentation Command Reference – AnalyzeNetworkPointFlow () -8 The following dialog is used to edit the command and illustrates the syntax of the command: AnalyzeNetworkPointFLow AnalyzeNetworkPointFlow() Command Editor 58 TSTool Documentation AnalyzeNetworkPointFlow() Command Command Reference – AnalyzeNetworkPointFlow () -9 The command syntax is as follows: AnalyzeNetworkPointFlow(Parameter=Value,…) Command Parameters Parameter Description Default TableID The identifier for the table defining the network. None – must be specified. NodeIDColumn The name of the column in the network table containing node identifiers. Node identifiers will be used for the location ID part of time series identifiers. None – must be specified. NodeNameColumn The name of the column in the network table containing node names. NodeTypeColumn The name of the column in the network table containing node types. The node type is used to specify what calculations will occur for the node. None – must be specified. NodeDistanceColumn The name of the column in the network table containing node distance. The distance is the measure from the most downstream node and is used when GainMethod=Distance or GainMethod= DistanceWeight. Must be specified when GainMethod= Distance or GainMethod= DistanceWeight. NodeWeightColumn The name of the column in the network table containing node weights, which is used to distribute gain/loss when GainMethod=Weight or GainMethod= DistanceWeight (in the latter case the weight is the rate to use). If not specified when GainMethod=Weight, gain/loss will be distributed evenly for the nodes. Must be specified when GainMethod= DistanceWeight. DownstreamNodeIDColumn The name of the column in the network table containing downstream node identifiers. This information defines the connectivity of the network. None – must be specified. NodeAddTypes Node types for which time series are added to the node’s inflow to compute outflow, for example the Return node type in the above table example. The NodeTypeColumn table column is checked to determine the type for each node in the network. No additions will occur. NodeAddDataType The time series data type to match for the node. The data type is used with the NodeID as the location ID to match available time series to use as input. This may be enhanced to allow a TSID pattern like %L-DivTotal, to No additions will occur. 59 AnalyzeNetworkPointFlow() Command TSTool Documentation Command Reference – AnalyzeNetworkPointFlow () -10 Parameter Description Default allow more flexibility in matching time series. NodeSubtractTypes Node types for which time series are subtracted from the node’s inflow, for example the Diversion node type in the above table example. The NodeTypeColumn table column is checked to determine the type for each node in the network. No subtractions will occur. NodeSubtractDataType The time series data type to match for the node. The data type is used with the NodeID as the location ID to match available time series to use as input. This may be enhanced to allow to a TSID pattern like %L-DivTotal, to allow more flexibility in matching time series. No subtractions will occur. NodeOutflowTypes Node types for which time series outflows are set to the node’s time input time series, for example the Streamflow node type in the above table example. The NodeTypeColumn table column is checked to determine the type for each node in the network. No known flows will be set – gain/loss cannot be computed. NodeOutflowDataType The time series data type to match for the node. The data type is used with the NodeID as the location ID to match available time series to use as input. This may be enhanced to allow a TSID pattern like %LStreamflow, to allow more flexibility in matching time series. No subtractions will occur. NodeFlowThroughTypes Node types for which time series outflows are set to the node’s inflow, for example the InstreamFlow node type in the above table example. The NodeTypeColumn table column is checked to determine the type for each node in the network. No known flows will be set – gain/loss cannot be computed. Interval The time series interval to process. The interval is used with the node identifier and data type to match input time series. None – must be specified. AnalysisStart The analysis start, which defines the period for output time series. Specify to a precision consistent with Specify to a precision consistent with Interval. Global output period. 60 TSTool Documentation AnalyzeNetworkPointFlow() Command Command Reference – AnalyzeNetworkPointFlow () -11 Parameter Description Default AnalysisEnd The analysis end, which defines the period for output time series. Specify to a precision consistent with Interval. Global output period. Units Units for output time series. Warnings will be generated if input time series for the analysis are not consistent with these units. GainMethod The method used to prorate the gain/loss between known point flow nodes to other nodes in the reach. Currently this can be used only on nonbranching networks. • Distance – prorate the gain/loss using distance between nodes (as a portion of the total distance). Use this method if a constant gain/loss rate applies over each reach in the network. • None – no gain/loss is estimated, resulting in a discontinuity in an outflow jump above each known point flow. • DistanceWeight – prorate the gain/loss using distance*weight as the weight for each node, where the rate is specified in the weight network table column. Use this method when the gain/loss rate varies by location and should be represented as a rate. • Weight – prorate the gain/loss using the weights specified for each node. Use this method if the gain/loss fraction in a reach is explicitly specified. None OutputTable The identifier for the output table to receive analysis results statistics. No output table will be created. The following command files illustrate how to implement a point flow analysis. In this case the first command file prepares daily time series using the network as input. The time series could similarly be provided by other processing procedures,