Theory Documentation Comments

[mbruggs]

Some suggestions but feel free to go with what sounds best to you 🙂 . More than happy to talk through any of the suggestions.

General

A better term for Hs would be nice - it looks strange at the moment how we freely fix Hm0, Hm1 and Hm50. Hm0 is sometimes Hm1 or Hm50 or both.

Quality Control

• "exposed through MHKiT API" -> "exposed through MHKiT."
• "Drop equivalent values found in the data set" -> "Drop values equal to user input from the dataset."
• "The measured data sources.. dropped" -> "Some data sources, such as NDBC, have known corrupt values which are removed before presenting the data in the DLC tool."
• Outlier formula, perhaps write as $\bar{x} = \frac{x - \mu}{\sigma}$, and define $\mu$ and $\sigma$
• Timestamp bullet 4: "Report largest gaps found in the dataset from the results of check_timestamp.

Statistics

• Should we reference Neary et al (2020) JMSE paper near the beginning as a reference for the context and application of the statistics. A common feedback from the Alpha testing was wanting to why we would do the stats and some guidance on univariate vs contour approaches.
• Opening two paragraphs "The Statistics pages use the cleaned site data to determine the wave conditions required for design using the IEC TS 62600-2. Table 7 in the IEC Standard specifies three design conditions corresponding to return periods of 1 and 50 years, and the designer-selected rated condition. These states are typically referred to in terms of the significant wave heights as $H{m1}$, ${H{m50}}$, and $H_{\mathrm{rated}}$ respectively."
• IFORM Contour, "Inverse First Order Reliability Method"

DLC & Sea state realisations

• Random seed - "The Random Seed initialises the random number..."
• "Downloading the updated" -> "downloading the new"

[Graham-EGI]

Thanks @mbruggs , I agreed with it all, so all has been updated!

The one part I didn't do was the $H_{m0}$ to $Hs$ renaming. I recall you mentioned this in your earlier review of the tool too. IEC TS 62600-2 isn't completely consistent, but it's definition section refers to significant wave height as $H{m0}$.

Lets not forget to bring this up with Johannes/ or the rest of the team next time to see if they have any input.

[Graham-EGI]

@mbruggs one more point on docs:

One of the bits of feedback was being unclear on how to evaluate the univariate methods. I cannot find any papers that reference it. Characterization of Extreme Wave Conditions for Wave Energy Converter Design and Project Risk Assessment (jsme-08-00289) Section 3.1 talks about comparison of univariate methods but not in a context that applies to what our tool provides.

If you don't mind providing some text on how to compare that would be great! My understanding comes from predictive analytics (train/ test), so I'm not sure if my attempted description would apply here.

[mbruggs]

General

• Should the link for disclaimers be on the front page rather than hidden in the tool section?

Theory

QC

• "data's" -> "data has"
• "much more vulnerable to inconsistencies."

Documentation

• Better name for this? "Web Interface"?
• Prefer the word "irregular" rather than "stochastic" to describe the seas states. Perhaps check with JS as both are used in the standards.

  Page 1

• "The Design Load Case (DLC) Generator tool supports the development of marine energy applications. The tool provides the data and the analysis to allow developers to obtain design load conditions, including 1- and 50- year sea states."
• The tool 1. -> The 7.9 million unique sources sounds a bit strange, do we mean 7.9 individual data points? We don't have 7.9 million buoys and hindcast locations?
• The tool 2. -> delete "different" (approaches is plural so there must be many)
• The tool 3. -> Generates irregular surface elevation time series data from spectral representations of a sea state for use in numerical modelling or wave tanke testing.

Data sources

CDIP

• Remove first sentence "Data courtesy..."
• Second paragraph "CDIP (Coastal Data Information Program)..."
• Point 2 "indexed by Hz" -> this seems to be a pandas specific implementation detail, perhaps remove?
• Point 2 - do we define these terms anywhere?
• Point 3 "null", is "invalid" better? Null feels a more computing term.
• Point 3 "duplicate time indexes" -> "duplicate timestamps", the term "index" feels like a pandas implementation detail

NDBC

• "The stdmet data provides $H_{m0}$, $T_p$ directly, after the same basic quality assurance.....
• T_e -> $T_e$

Modelled Data sources

Hindcast

• Move the link that is in "here" to "hosted publicly", remove "See the docs here".

Tool workflow

• Opening paragraph: "Technical Specifications"
• Point 1 "met-ocean" -> "metocean"
• Point 2 "from the sea state parameters for use..."
• Point 3 Full stop at end of sentence

Raw data review

• 2nd paragraph - "The 10 year limitiation..." not sure I understand this sentence. Perhaps "A maximum of 10 years of data can be displayed on the graph to avoid delays in rendering the data".

Data selection and quality control

Data quality tests

• First paragraph - "The theory documentation describes the data quality tests and the required inputs".
• null -> "null"
• "For example if null were selected for the Delta Lower Bound, checks for the mimumum delta across the rolling windows would not be performed."

Re-cleaning

• "Re-cleaning data wil replace the original data and necessitates the re-running of any statistics computed in later stages of the workflow"
• Are the second and third paragraphs necessary, they just seem to say the same thing as the first paragraph as makes it a bit confusing as we haven't discussed contours or QQ plots at this stage. The last paragraph "The tool guides..." looks good and can be combined with the first paragraph.

Cleaned data review

• "Review" -> "review"
• 2nd paragraph -> Datapoints with the same timestamp are removed from all datastets if one of the cleaning thresholds is exceeded. For example, if a point in the $H_{m0}$ dataset exceeds the respective range bound, the same point will be removed from the $T_p$ and $T_e$ datasets.

Statistics

• "numerical modelling or tank testing. The 1 and 50 year periods are chosen to satisfy the requirements for IEC TS...."
• "If the resulting..." -> I'd be tempted te do delete this paragraph. The sea states are what they are, chosing another location should be clear to the user.

Design Load Cases

• "The tool allows..." - I tihnk we have already said this a few times, not sure we need to say it again
• "It's up to the developer...", Perhaps combine with the first paragraph as "It is the developers responsibility to ensure the correct wave conditions are used to assess the DLC testing requrirements". I'm not sure I've fully understood what is meant by this paragraph so perhaps the sentence above doesn't properly capture the intent.
• "When generating the time series..." -> "The spectral parameters can be re-selected, and the time series re-generated, if required.

Device repsonse analysis

• I would remove the sentence "However, some WEC devices and control strategies..." as this potentially gives away propritary information about one of the projects that we happen to work on.
• "The tool performs ... being assesed, for example motions or pressures."
• "Use your best judgement" -> "Judgement, alongside the IEC TS 62600-2, is required in order to determine how to use the results of the response analysis".

Response analysis upload

Data structure

• "python" -> "Python"

Example NetCDF Scripts

• "python" -> "Python"

MATLAB

• "matlab" -> "MATLAB" for consistency
• "assumes" -> "requires"

CSV

• "can have as many..." -> delete it is already covered by the "at least".

[Graham-EGI]

@mbruggs thanks!

[Graham-EGI]

All finished, thanks for review @mbruggs