/** * Class for storing and working with .dat file contents. * This class expects a text string, which will usually be extracted * from a .dat file, or translated from a TimeSeries object from * a .inp file, or translated from a JSON swmm object. */ export declare class SwmmDat { /** * @type {Array} the header of a .dat file. */ header: Array; /** * @type {Map>} a Map keyed with gage names, * which are in turn Maps keyed with unix timestamps, with * values of rainfall. the formatted contents of a .dat file. */ contents: Map>; /** * Constructor for the SwmmDat class. Pass fileType="TS" if the .dat file is a timeSeries * * @param {string} n The contents of a .dat file. * @param {string} fileType "RG" for raingage .dat file, "TS" for TimeSeries .dat file. */ constructor(n: string, fileType?: string); /** * Prepares the contents of a .dat file for processing * @param {string} fileContents the contents of a .dat file. * @returns {Array} An array of non-empty lines from a .dat file */ prepContents(fileContents: string): Array; /** * Evaluates the starting ';' comment lines into an array of strings. * * @param {string} fileContents the contents of a .dat file. * @returns {Array} An array of header comments in a .dat file */ parseHeader(fileContents: string): Array; /** * Returns the object's header string contents. * * @returns {Array} header string contents of a .dat or simulated .dat file. */ getHeader(): Array; /** * When a file contents string is passed to the swmmDat, it creates a * Map containing each line of data from a representative .dat file. * * @param {string} fileContents The string contents of a .dat file. * @param {string} fileType Either "RG" or "TS", the format of the .dat file. * @returns {Map>} The contents of a .dat file in a Map with keys of gage names, * which are in turn Maps with keys of unix times, and values of rainfall. */ createDatGages(fileContents: string, fileType: string): Map>; /** * Finds storms in a set of records for a gage in a SwmmDat object. * Use this to get an array of start and end times for storms. Storms will be added * to the array if they have a minimum total rainfall as stated in MSV, and * seprarated by an inter-event period as stated in IEP. * * To use: * * * @param {Max} dataMap The data for a gage in a .dat file. * @param {number} IEP The inter-event period, maximum time between MSV sums. A unix time in milliseconds. * @param {number} MSV The minimum storm volume, the minimum amount of rainfall during an IEP to classify the event as a storm. * @returns {Array} Returns an array of storms: { start: DateTime, end: DateTime } */ static findStorms(dataMap: Map, IEP: number, MSV: number): Array<{ begin: number; end: number; }>; /** * Gets a group of storms in a human-readable format. This function should probably be * deprecated, but I like how simple it is to use for quick analyses. * * How to use this: To call this function using unix timestamps, you can use the following format: * SwmmDat.maxEvent(.get('127069'), (new Date(Date.UTC(1970, 10, 20, 0, 0, 0))).getTime(), (new Date(Date.UTC(1970, 10, 21, 0, 0, 0))).getTime(), 3600000*24) * * @param {Map} dataMap The data for a gage in a .dat file. * @param {number} IEP The inter-event period, maximum time between MSV sums. A unix time in milliseconds. * @param {number} MSV The minimum storm volume, the minimum amount of rainfall during an IEP to classify the event as a storm. * @returns {Array} Returns an array of storms: { start: DateTime, end: DateTime } */ static findStormsPretty(dataMap: Map, IEP: number, MSV: number): Array<{ begin: number; end: number; }>; /** * Find the rainfall elements that classify as a storm due to having a volume that * meets or exceeds the MSV and has a length of IEP. * The results will exclude values that are exactly * Event Time + IEP, because Events are not considered instantaneous - BUT!! * the results of findSubStorms are end-inclusive, because .dat files do not have * fixed time intervals and if you've picked up an event, it is likely you've already * hit an end-exclusive function before this. You can avoid worrying about this by * creating your dat file in predictably-timed intervals (i.e.: if you want 15-minute * timeseries, you don't need to explicitly state every 15-minute period, but do not * mix times like 10:17 and 8:05. Also, be sure to call these functions based * upon those expected intervals. * @param {Map} dataMap The data for a gage in a .dat file. * @param {number} IEP Inter-event period, minimum time between classified storms * @param {number} MSV Minimum storm volume, the least amount of rain that can classify a storm * @returns */ static findSubStorms(dataMap: Map, IEP: number, MSV: number): Array<{ start: number; end: number; vol: number; }>; /** * Sum rainfall events and group by the periodType given * This is used to create yearly rainfall totals, monthly * statistics, or provide general error checking prior to * utilizing swmmWasm and swmmLink for AI operations. * @param {dataMap} dataArray The data for a gage in a .dat file. * @param {number} startTime The start time (UNIX epoch) of the records to check. * This can be prior to or after the events within dataArray. * @param {number} endTime The end time (UNIX epoch) of the records to check. * This can be prior to or after the events within dataArray. * @param {periodType} string idicator of the summation interval units. Can be 'Hour', 'Day', 'Month', 'Year' * @param {periodValue} number Number of periodTypes that a summation interval will span. To get 6-hour intervals, use periodValue = 6 and periodType = 'Hour' * @returns {} */ static sumEvents(dataMap: Map, startTime: number, endTime: number, periodType: string, periodValue: number): Array; /** * Find the sum of rainfall between two points in time, * Inclusive of the start date and inclusive of the end date. * This can be used to sum storm-specific rainfall. For exclusive * end events, use periodVol, because storms are often identified * by their final rainfall event. * * @param {Map} dataMap The data for a gage in a .dat file. * @param {number} startDate The start date to measure from. * @param {number} endDate The end date to measure to. * @returns {number} */ static stormVol(dataMap: Map, startDate: number, endDate: number): number; /** * Find the sum of rainfall between two points in time, * Inclusive of the start date and exclusive of the end date. * This can be used to sum yearly, monthly, daily, or other rainfall. * For inclusive periods, use stormVol, because storms are usually denoted * by their final rain event. * * @param {Map} dataMap The data for a gage in a .dat file. * @param {number} startDate The start date to measure from. * @param {number} endDate The end date to measure to. * @returns {number} */ static periodVol(dataMap: Map, startDate: number, endDate: number): number; /** * Find the maximum volume and start time, and end time of an n-period * rainfall between two points in time, inclusive of the * start date and inclusive of the end date, due to the fact * that storms are often identified by their first and last * recorded rainfall event. Output of this function will be inclusive of the * start time and exclusive of the end time, because rainfall is not instantaneous. * This can be used to find the maximum 1-hr, 2-hr, 24-hr, 48-hr * rainfall in a storm or in a year/month. * * Example uses: * * @param {Map} records The data for a gage in a .dat file. * @param {number} startDate The start date to measure from (unix timestamp, UTC time). * @param {number} endDate The end date to measure to (unix timestamp, UTC time). * @param {number} nPeriod number of milliseconds that define the period: 1 hour is 3600000 milliseconds. * @returns {Array<{number, number, number}>} Array of objects of the format {start: number, end:number, vol: number}, start and end time of max event and volume of max event. Unlike most rainfall data, this is inclusive */ static maxEvent(records: Map, startDate: number, endDate: number, nPeriod: number): Array<{ start: number; end: number; vol: number; }>; /** * Find the maximum volume and start time, and end time of an n-period * rainfall between two points in time, inclusive of the * start date and inclusive of the end date, due to the fact * that storms are often identified by their first and last * recorded rainfall event. Output of this function will be inclusive of the * start time and exclusive of the end time, because rainfall is not instantaneous. * This can be used to find the maximum 1-hr, 2-hr, 24-hr, 48-hr * rainfall in a storm or in a year/month. The results of this function * can be confusing when charted, as most people will see rainfall within * the bounds of the results of this function that will not be included in * the sum. * For cases when detailing results to people that cannot make this * distinction, use maxEvent and NOT maxEventStrict. * * @param {Map} records The data for a gage in a .dat file. * @param {number} startDate The start date to measure from (unix timestamp, UTC time). * @param {number} endDate The end date to measure to (unix timestamp, UTC time). * @param {number} nPeriod number of milliseconds that define the period: 1 hour is 3600000 milliseconds. * @returns {{number, number, number}} Object of the format {start: number, end:number, vol: number}, start and end time of max event and volume of max event. Unlike most rainfall data, this is inclusive */ static maxEventStrict(records: Map, startDate: number, endDate: number, nPeriod: number): Array<{ start: number; end: number; vol: number; }>; /** * Get a Map of rainfall events keyed by dates, trimmed to the value * between two dates, inclusive of the start date and exclusive of the end date. * Use this function inside of maxEvent to trim down a * passed set of Map records. * * @param {Map} records usually the full Map of unix time keyed rainfall from a gage * @param {number} startDate start time, inclusive, in milliseconds * @param {number} endDate end time, exclusive, in milliseconds * @returns {Map} trimmed set of unix time keyed rainfall */ static trimIDatRecords(records: Map, startDate: number, endDate: number): Map; /** * Returns a human-readable string version of an integer time step. * Use this to make strings that can be written to EPA-SWMM files. * * @param {number} timeStep An integer representing the time step of * the model. Does not need to be within the bounds of the model. * @returns {string} A Javascript string object. */ static unixTime_toDate(unixTime: number): string; /** * Returns a Dat-readable string version of an integer time step. * Use this to make strings that can be written to Dat files. * * @param {number} unixTime Unix time, in milliseconds since January 1st, 1970. * @returns {string} A Javascript string object. */ static unixTime_toDate_Dat(unixTime: number): string; /** * Returns a copy of the current swmmDat object, but with only one gage. * @param {string} gage name of the raingage to separate from the swmmDat object. * @returns {swmmDat} A swmmDat object with just one raingage in it. */ subGage(gage: string): SwmmDat; /** * Creates a new SwmmDat object by copying the calling swmmDat object and then * inserts the records of the passed object (parameter) into the records * of a copy of the calling (this) object. If a key exists in the this object and * also in the passed object, both sets of records will merge. Any records in the * this object that have the same gage and occur at time same time * in the parameter object will be overwritten with the records of the * parameter object. * * @param {SwmmDat} objToInsert Object containing new or updated records and * gages. * @returns {SwmmDat} A new SwmmDat object that combines the records of objToInsert and this object. */ /** * Creates a copy of the current swmmDat object, trimmed down to a specific date range inclusive of start AND end times. * This is used to reduce file sizes and focus on specific storms. * @param {number} startTime a unix time, milliseconds since Jan 1st, 1970 * @param {number} endTime a unix time, milliseconds since Jan 1st, 1970 * @returns {swmmDat} a swmmDat object trimmed down to a specific date range. */ subRange(startTime: number, endTime: number): SwmmDat; /** * Translates the SwmmDat object to a string. * Use this for * - Copying swmmDat objects * - Preparing to save the object to a file. * @param {string} fileType use "RG" if you wish to save all gages, use "TS" if you only * want to strip all gage names. Returns error if you use "TS" with more than one gage. * @returns {string} a string in the format of a raingage.dat file */ stringify(fileType?: string): string; }