BlueM.Wave: Difference between revisions

From BlueM
Jump to navigation Jump to search
(→‎Supported formats: added PRMS OUT format)
(→‎link= Import time series: restructure and add HYBNAT)
 
(43 intermediate revisions by the same user not shown)
Line 2: Line 2:
<div style="float:right; margin:0.5em 0 0.5em 0.5em;">__TOC__</div>
<div style="float:right; margin:0.5em 0 0.5em 0.5em;">__TOC__</div>
[[Bild:Wave_screenshot.png|thumb|Screenshot]]
[[Bild:Wave_screenshot.png|thumb|Screenshot]]
[[Bild:Monatsauswertung.png|thumb|Analysis function Monthly statistics]]
 
[[Bild:Doppelsummenanalyse.png|thumb|Analysis function Double mass curve]]
[[Bild:Wave_Statistik.png|thumb|Analysis function Histogram]]
==Description==
==Description==
Wave is a tool for displaying, analyzing and importing and exporting time series.
Wave is a tool for displaying, analyzing and importing and exporting time series.
Line 10: Line 8:
==Features==
==Features==


===Supported formats===
===[[File:Icon_chart_line_add.png|link=]] Import time series===
* [[WEL-Format | WEL]] ([[WEL-Format (BlueM)|BlueM]], [[WEL-Format (GISMO)|GISMO]], [[WEL-Format (TALSIM)|TALSIM]], [[WEL-Format (Hystem-Extran)|Hystem-Extran]])
'''Supported file formats:'''
* [[ZRE-Format | ZRE]]
* [[WEL-Format_(BlueM)|BlueM.Sim result files]]: <code>*.WEL</code>, <code>*.KWL</code>
* [[ASC-Format | ASC]]  
* [[DFS0-Format | DHI MIKE DFS0 format]]: <code>*.DFS0</code>
* [[SMB-Format | SMB]]  
* [[WEL-Format (GISMO)|GISMO result files]]: <code>*.WEL</code>
* [[REG-Format | REG]] ([[SMUSI REG-Format|SMUSI]] and [[Hystem-Extran REG-Format|Hystem-Extran]])
* [[HYBNAT result files]]: <code>*.WEL</code>, <code>*.BCS</code>
* [[OUT-Format | OUT]] ([[SWMM binary output format]] and [[PRMS OUT format]])
* [[HYDRO_AS-2D result files]]: <code>*.DAT</code>
* [[TXT-Format | TXT]] ([[SWMM]] routing interface files)
* [[Hystem-Extran file formats]]: Regendatei (<code>*.REG</code>, <code>*.DAT</code>) and Wellendatei (<code>*.WEL</code>)
* [[UVF-Format | UVF]] (Universelles Variables Format)
* [[JAMS result files]]: JAMS/J2000/J2K/J2000g timeseries results (<code>*.DAT</code>)
* [[DAT-Format | HYDRO_AS-2D]] result files
* [[PRMS result files]]: annual summary, monthly summary, DPOUT (<code>*.OUT</code>) and statistic variables result file (<code>*.DAT</code>)
* [[BIN-Format | BIN]] (SYDRO binary format)
* [[SMUSI file formats]]: <code>*.ASC</code> result files and <code>*.REG</code> input files
* [[ZRXP-Format | ZRXP]] (ZXRP format)
* [[SWMM file formats]]: SWMM5 binary output format (<code>*.OUT</code>), routing interface files (<code>*.TXT</code>), LID report files (<code>*.TXT</code>), SWMM time series files (<code>*.DAT</code>)
* and generic text files (e.g. [[CSV-Format | CSV]])
* [[SMB-Format | SIMBA file format]]: <code>*.SMB</code>
* [[Talsim-NG file formats]]: time series results (<code>*.WEL</code>, <code>*.WBL</code>) and binary input time series (<code>*.BIN</code>)
* [[UVF-Format | UVF format]]: Universelles Variables Format (<code>*.UVF</code>)
* [[ZRE-Format | ZRE format]]: <code>*.ZRE</code>
* [[ZRXP-Format | ZRXP format]]: <code>*.ZRX</code>, <code>*.ZRXP</code>
* and [[CSV-Format|generic text files]] (e.g. <code>*.CSV</code>, <code>*.TXT</code>)


Use a '''[[Wave project file]]''' (<code>*.wvp</code>) to quickly import multiple series from multiple files at once.
[[File:Icon_chart_curve_link.png|link=]] Use a '''[[Wave project file]]''' (<code>*.WVP</code>) to quickly import multiple series from multiple files at once.


'''Drag&Drop''' files onto Wave to import them quickly.
'''Drag&Drop''' files onto Wave to import them quickly.


It is also possible to manually input time series, or use copy & paste from Excel.
It is also possible to manually [[File:Icon_chart_line_edit.png|link=]] '''enter time series''', or [[File:Icon_page_paste.png|link=]] '''paste clipboard data''' from Excel and [http://www.talsim.de Talsim-NG].


===Visualization & Navigation===
===Visualization & Navigation===
Display time series in a highly customizable diagram (provided by [http://www.steema.com/products/teechart/overview.html TeeChart])
Display time series in a highly [[File:Icon_chart_curve_edit.png|link=]] '''customizable chart''' (provided by [http://www.steema.com/products/teechart/overview.html TeeChart])
 
[[Image:TimeSeriesValues.png|thumb|Time series values and markers ([[Media:TimeSeriesValues_animation.gif|animation]])]]
* [[File:Icon_application_split.png|link=]] An '''overview''' chart shows you the full extent of the time series and the period currently displayed in the main chart.
* [[File:Icons_zoom.png|link=]] Use the toolbar buttons or the mouse to '''zoom or pan''' either in the main chart or the overview chart. Use the left mouse button or the mouse scroll wheel to zoom, hold the right mouse button to pan.
* [[File:Icon_controller.png|link=]] Use the '''navigation bar''' to set a custom display period and to navigate by a fixed time period or to the start/end [[File:Icons_navigate.png|link=]].
* [[File:Icon_table.png|link=]] Display tabular '''time series values''' and optionally show markers [[File:Icon_comments.png|link=]] for selected rows in the main chart


* '''Overview''': An overview chart shows you the full extent of the time series and the period currently displayed in the main diagram.
===Series management===
* '''Axes''': When importing time series, series are automatically assigned to different axes depending on their unit.
[[File:Wave TimeSeries Properties.png|thumb|right|Time series properties]]
* '''Zoom & pan''': Use the mouse to zoom or pan.
* [[File:Icon_accept_split.png|link=]] Quickly switch time series on and off using the '''check boxes''' in the legend or activate/deactivate all series at once using the button in the toolbar.
* '''Navigation bar''': Use the navigation bar to set a custom display period and to navigate by a fixed time period.
* [[File:Icon_table_edit.png|link=]] Display and edit '''time series properties''' in a table with optional statistics.
* Quickly switch time series on and off using the '''check boxes''' in the legend.
* [[File:Icon_shape_align_bottom.png|link=]] '''Manage axes''': When importing time series, series are automatically assigned to different axes depending on their unit.


===Save & Export===
===Save & Export===
'''Save diagrams''' to the native TeeChart format (TEN-File) to preserve all data and formatting (for exceptions, see known issues below).
[[File:Icon_chart_curve_link.png|link=]] '''Save [[Wave project file|project files]]''' (<code>*.wvp</code>) with references to time series from file sources.


'''Export diagrams''' as image files (PNG, JPG, BMP)
[[File:Icon_chart_pie.png|link=]] '''Save charts''' to the native TeeChart format (TEN-File) to preserve all data and formatting (for exceptions, see known issues below).


'''Export time series''' to the following formats:
[[File:Icon_chart_pie.png|link=]] '''Export charts''' as image files (PNG, JPG, BMP).
* CSV
 
* [[ZRE-Format | ZRE]]
[[File:Icon page copy.png|link=]] '''Copy''' the chart to the clipboard as a PNG image.
 
'''[[File:Icon_page_white_go.png|link=]] Export time series''' to the following formats:
* [[CSV-Format | CSV]]
* [[BIN-Format | BIN]]
* [[DFS0-Format | DFS0]]
* [[SWMM file formats|SWMM routing interface and time series files]]
* [[SMUSI REG-Format | SMUSI REG]]
* [[SMUSI REG-Format | SMUSI REG]]
* [[SWMM]] DAT
* [[UVF-Format | UVF]]
* [[UVF-Format | UVF]]
* XLS (made available by TeeChart)
* [[ZRE-Format | ZRE]]
* [[ZRXP-Format | ZRXP]]


===Edit & Analyze===
===Edit & Analyze===
Editing functions:
Editing functions:
* '''Cut''' time series to a specified time period or to another series' extent
* [[File:Icon_cut.png|link=]] '''Cut''' time series to a specified time period or to another series' extent
* '''Convert error values''' of a time series
* [[File:Icon_error_convert.png|link=]] '''Convert error values''' of a time series
* '''Merge''' multiple time series into one while respecting priorities
* [[File:Icon_arrow_join_right.png|link=]] '''Merge''' multiple time series into one while respecting priorities


'''Analysis functions:'''
'''[[File:Icon_calculator.png|link=]] Analysis functions:'''
* [[Wave:MonthlyStatistics|Monthly statistics]]
* [[Wave:Accumulate|Accumulate]]: Compute a new time series that contains the cumulative values of the original series
* [[Wave:Doppelsummenanalyse|Double mass curve]]
* [[Wave:Autocorrelation|Autocorrelation]]: Autocorrelation analysis for analyzing time series periodicity
* [[Wave:AnnualRecurrenceProbability|Annual recurrence probability]]: Annual recurrence probability of annual maxima using plotting position
* [[Wave:AnnualStatistics|Annual statistics]]: Compute various statistical parameters (min, max, average) of a time series
* [[Wave:Calculator|Calculator]]: Performs a mathematical operation on one or more time series
* [[Wave:ChangeTimestep|Change timestep]]: Make a time series equidistant with a user-specified timestep
* [[Wave:Comparison|Comparison]]: Plot two time series against each other and compute a linear regression line
* [[Wave:Decumulate|Decumulate]]: Compute a new time series that consists of the decumulated values of the original series
* [[Wave:DoubleSumCurve|Double sum curve]]
* [[Wave:GoodnessOfFit|Goodness of fit]] (volume error, sum of squares error, Nash-Sutcliffe efficiency, etc.)
* [[Wave:GoodnessOfFit|Goodness of fit]] (volume error, sum of squares error, Nash-Sutcliffe efficiency, etc.)
* [[Wave:Histogram|Histogram]]
* [[Wave:Histogram|Histogram]]
* [[Wave:Gegenueberstellung|Comparison]]: Plot two time series against each other and compute a linear regression line
* [[Wave:LinearRegression|Linear regression]]: Fills gaps (NaN values and missing timestamps) in one time series by applying a linear regression relationship with a second time series
* [[Wave:AnnualStatistics|Annual statistics]]: Compute various statistical parameters (min, max, average) of a time series
* [[Wave:MonthlyStatistics|Monthly statistics]]
* [[Wave:Cumulative|Cumulative]]: Compute a new time series that contains the cumulative values of the original series
* [[Wave:TimestepAnalysis|Timestep analysis]]: Calculate the timestep between nodes in a user-specified unit
 
<gallery mode="packed-hover">
File:Wave Cumulative.png|Accumulate|link=Wave:Accumulate
File:Wave Autocorrelation.png|Autocorrelation|link=Wave:Autocorrelation
File:Wave AnnualRecurrenceProbability.png|Annual recurrence probability|link=Wave:AnnualRecurrenceProbability
File:Wave AnnualStatistics BoundingBoxes.png|Annual statistics|link=Wave:AnnualStatistics
File:Wave Calculator.png|Calculator|link=Wave:Calculator
File:Wave ChangeTimestep Instantaneous.png|Change timestep
File:Wave Comparison.png|Comparison|link=Wave:ChangeTimestep
File:Wave Decumulate.png|Decumulate|link=Wave:Decumulate
File:Doppelsummenanalyse.png|Double sum curve|link=Wave:DoubleSumCurve
File:GoodnessOfFit ResultChart.png|Goodness of fit|link=Wave:GoodnessOfFit
File:Wave_Statistik.png|Histogram|link=Wave:Histogram
File:Wave LinearRegression.png|Linear regression|link=Wave:LinearRegression
File:Monatsauswertung.png|Monthly statistics|link=Wave:MonthlyStatistics
</gallery>
 
==Comandline interface==
Wave has a commandline interface for importing and converting time series, see [[Wave:CLI]] for details.


==API==
==API==
The '''API''' is used by [[BlueM.Opt]] and [[BlueM.Win]].
The '''API''' is used e.g. by [[BlueM.Opt]] and [[BlueM.Win]] but allows using Wave from within any .NET project.


See the [[Wave:API|documentation]].
See the API docs here: https://bluemodel.github.io/BlueM.Wave/api/


==Notes==
==Notes==
Line 78: Line 119:
* Unreadable values are converted to NaN during import.
* Unreadable values are converted to NaN during import.
* If a file format has a specified error value (e.g. -777 for [[ZRXP]] and [[UVF]]), then any corresponding entries are also converted to NaN.
* If a file format has a specified error value (e.g. -777 for [[ZRXP]] and [[UVF]]), then any corresponding entries are also converted to NaN.
* NaN values are removed before displaying a series in the chart and when performing analysis functions.
* NaN values are displayed as gaps in the chart and are ignored when performing analysis functions.
* Custom, user-specified values can be converted to NaN after import.
* Custom, user-specified values can be converted to NaN [[File:Icon_error_convert.png|link=]] after import.
* NaN values can be visualized in the chart by pressing a button (see screenshot to the right).
* NaN values can be visualized in the chart by pressing a [[File:Icon_chart_line_error.png|link=]] button (see screenshot).


===Volume property===
===Volume property===
Wave can calculate and display the volume of a time series (e.g. for [[Wave:GoodnessOfFit|GoodnessOfFit]] analysis or in the properties window). The volume is usually calculated by simply computing the sum of all individual values of a time series (in this case it is equal to the "Sum" property). However, if a time series' unit ends with "/s" (e.g. "m³/s"), the volume is calculated by actually integrating the values over time.  
Wave calculates and displays the Volume property of a time series (e.g. for [[Wave:GoodnessOfFit|GoodnessOfFit]] analysis or in the properties window), if a time series' unit ends with "/s", "/min", "/h" or "/d" (e.g. "m³/s", "mm/h", etc.) and its interpretation is either Instantaneous, BlockLeft or BlockRight, by integrating the values over time while respecting the interpretation. Time series with other units or interpretations only have the Sum property. NaN nodes cause the adjacent timesteps to not contribute to the volume (depends on the interpretation).
 
===Supported date range===
Wave supports dates between 01.01.0001 and 31.12.9999.


Which method is used to calculate the volume is always written to the log.
The chart display can only show dates between 01.01.0100 and 31.12.9000. Time series with dates before 01.01.0100 and after 31.12.9000 are cut for display purposes, but all nodes are still available for analysis and export and are shown in the properties and time series values dialogs. (#68)


==Downloads==
==Downloads==
Please refer to the [http://www.bluemodel.org/download/ Download] page.
Download BlueM.Wave from GitHub: https://github.com/bluemodel/BlueM.Wave/releases/latest


==Known Issues==
==Known Issues==
* When saving a chart to the native TEN format of TeeChart, any NaN values contained in the series are lost (i.e. the nodes with the NaN values are omitted from the series).
* When saving a chart to the native TEN format of TeeChart, certain Timeseries properties such as Interpretation, Datasource and sometimes Unit are lost.
* <s>When saving a chart to the native TEN format of TeeChart, any NaN values contained in the series are lost (i.e. the nodes with the NaN values are omitted from the series).</s> ''fixed in v1.9.1''
* more issues: https://github.com/bluemodel/BlueM.Wave/issues


==Development==
==Development==
* [[Wave:Code|Code documentation]]
* [https://github.com/bluemodel/BlueM.Wave/blob/master/source/CHANGELOG.md Changelog]
* [[Wave:Release Notes|Release Notes]]
* [[Wave:Development|Development]]
* [http://bugs.bluemodel.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&content=&product=Wave&query_format=specific&order=bug_severity%2Cpriority%20ASC&query_based_on= Bugzilla:Wave]


[[Category:BlueM.Wave]]
[[Category:BlueM.Wave]]

Latest revision as of 11:10, 11 December 2023

Wave.png Wave | Download | Development

Screenshot

Description

Wave is a tool for displaying, analyzing and importing and exporting time series.

Features

Icon chart line add.png Import time series

Supported file formats:

Icon chart curve link.png Use a Wave project file (*.WVP) to quickly import multiple series from multiple files at once.

Drag&Drop files onto Wave to import them quickly.

It is also possible to manually Icon chart line edit.png enter time series, or Icon page paste.png paste clipboard data from Excel and Talsim-NG.

Visualization & Navigation

Display time series in a highly Icon chart curve edit.png customizable chart (provided by TeeChart)

Time series values and markers (animation)
  • Icon application split.png An overview chart shows you the full extent of the time series and the period currently displayed in the main chart.
  • Icons zoom.png Use the toolbar buttons or the mouse to zoom or pan either in the main chart or the overview chart. Use the left mouse button or the mouse scroll wheel to zoom, hold the right mouse button to pan.
  • Icon controller.png Use the navigation bar to set a custom display period and to navigate by a fixed time period or to the start/end Icons navigate.png.
  • Icon table.png Display tabular time series values and optionally show markers Icon comments.png for selected rows in the main chart

Series management

Time series properties
  • Icon accept split.png Quickly switch time series on and off using the check boxes in the legend or activate/deactivate all series at once using the button in the toolbar.
  • Icon table edit.png Display and edit time series properties in a table with optional statistics.
  • Icon shape align bottom.png Manage axes: When importing time series, series are automatically assigned to different axes depending on their unit.

Save & Export

Icon chart curve link.png Save project files (*.wvp) with references to time series from file sources.

Icon chart pie.png Save charts to the native TeeChart format (TEN-File) to preserve all data and formatting (for exceptions, see known issues below).

Icon chart pie.png Export charts as image files (PNG, JPG, BMP).

Icon page copy.png Copy the chart to the clipboard as a PNG image.

Icon page white go.png Export time series to the following formats:

Edit & Analyze

Editing functions:

  • Icon cut.png Cut time series to a specified time period or to another series' extent
  • Icon error convert.png Convert error values of a time series
  • Icon arrow join right.png Merge multiple time series into one while respecting priorities

Icon calculator.png Analysis functions:

  • Accumulate: Compute a new time series that contains the cumulative values of the original series
  • Autocorrelation: Autocorrelation analysis for analyzing time series periodicity
  • Annual recurrence probability: Annual recurrence probability of annual maxima using plotting position
  • Annual statistics: Compute various statistical parameters (min, max, average) of a time series
  • Calculator: Performs a mathematical operation on one or more time series
  • Change timestep: Make a time series equidistant with a user-specified timestep
  • Comparison: Plot two time series against each other and compute a linear regression line
  • Decumulate: Compute a new time series that consists of the decumulated values of the original series
  • Double sum curve
  • Goodness of fit (volume error, sum of squares error, Nash-Sutcliffe efficiency, etc.)
  • Histogram
  • Linear regression: Fills gaps (NaN values and missing timestamps) in one time series by applying a linear regression relationship with a second time series
  • Monthly statistics
  • Timestep analysis: Calculate the timestep between nodes in a user-specified unit
  • Accumulate

    Accumulate

  • Autocorrelation

    Autocorrelation

  • Annual recurrence probability

    Annual recurrence probability

  • Annual statistics

    Annual statistics

  • Calculator

    Calculator

  • Change timestep

    Change timestep

  • Comparison

    Comparison

  • Decumulate

    Decumulate

  • Double sum curve

    Double sum curve

  • Goodness of fit

    Goodness of fit

  • Histogram

    Histogram

  • Linear regression

    Linear regression

  • Monthly statistics

    Monthly statistics

Comandline interface

Wave has a commandline interface for importing and converting time series, see Wave:CLI for details.

API

The API is used e.g. by BlueM.Opt and BlueM.Win but allows using Wave from within any .NET project.

See the API docs here: https://bluemodel.github.io/BlueM.Wave/api/

Notes

Error values

Visualization of NaN values
  • "NaN", "Infinity" and "-Infinity" in import files are recognized and accepted.
  • Unreadable values are converted to NaN during import.
  • If a file format has a specified error value (e.g. -777 for ZRXP and UVF), then any corresponding entries are also converted to NaN.
  • NaN values are displayed as gaps in the chart and are ignored when performing analysis functions.
  • Custom, user-specified values can be converted to NaN Icon error convert.png after import.
  • NaN values can be visualized in the chart by pressing a Icon chart line error.png button (see screenshot).

Volume property

Wave calculates and displays the Volume property of a time series (e.g. for GoodnessOfFit analysis or in the properties window), if a time series' unit ends with "/s", "/min", "/h" or "/d" (e.g. "m³/s", "mm/h", etc.) and its interpretation is either Instantaneous, BlockLeft or BlockRight, by integrating the values over time while respecting the interpretation. Time series with other units or interpretations only have the Sum property. NaN nodes cause the adjacent timesteps to not contribute to the volume (depends on the interpretation).

Supported date range

Wave supports dates between 01.01.0001 and 31.12.9999.

The chart display can only show dates between 01.01.0100 and 31.12.9000. Time series with dates before 01.01.0100 and after 31.12.9000 are cut for display purposes, but all nodes are still available for analysis and export and are shown in the properties and time series values dialogs. (#68)

Downloads

Download BlueM.Wave from GitHub: https://github.com/bluemodel/BlueM.Wave/releases/latest

Known Issues

  • When saving a chart to the native TEN format of TeeChart, certain Timeseries properties such as Interpretation, Datasource and sometimes Unit are lost.
  • When saving a chart to the native TEN format of TeeChart, any NaN values contained in the series are lost (i.e. the nodes with the NaN values are omitted from the series). fixed in v1.9.1
  • more issues: https://github.com/bluemodel/BlueM.Wave/issues

Development

Retrieved from "https://wiki.bluemodel.org/index.php?title=BlueM.Wave&oldid=7870"