Add function to compute value at a given return period

[mbruggs]

This PR adds a function called return_year_value. An example usage can be seen in the extreme_response_full_sea_state_example.ipynb. The example would be adjusted from:

To:

With the return_year_value function defined as follows:

def return_year_value(ppf, return_year, short_term_period_hr):
    """
        Calculate the value from a given distribution corresponding to
        a particular return year.
        Parameters
        ----------
        ppf: callable function of 1 argument
            Percentage Point Function (inverse CDF) of short term distribution.
        return_year: int
            Return period in years.
        short_term_period_hr: int, float
            Short term period the distribution is created from in hours.
        Returns
        -------
        value: float
            The value corresponding to the return period from the distribution.
    """
    assert callable(ppf)
    assert isinstance(return_year, int)
    assert isinstance(short_term_period_hr, (float, int))

    p = 1 / (return_year * 365.25 * 24 / short_term_period_hr)

    return ppf(1 - p)

[mbruggs]

Hello! Added small function to compute the value at a given return period and also updated the example. Please let me know if anything can be tightened up on this.

[ssolson]

Thank you for your interest in MHKiT-python @mbruggs! We will need to add a test for sure and clean up some formatting, and variable names but before we do that I want to check with @cmichelenstrofer for interest in incorporating this function.

@cmichelenstrofer could you quickly comment on your thoughts about incorporating this proposed function into MHKiT and if incorporated would we include it in extreme.py or in the utils module?

[mbruggs]

Thanks for looking @ssolson! Sorry for not adding the test, I completely missed the test directory when I looked. I'll add a test once we have some feedback from Carlos.

I've run autopep8 over the function and pushed the changes but let me know what other formatting changes are needed.

[cmichelenstrofer]

@ssolson Yes this is very useful. I was doing it manually in the examples but having a function is better.

[akeeste]

@mbruggs Carlos approved your changes. Can you add a test for this function? There are several examples in /tests/loads/ for reference. I'm also going to change this PR to go into our Develop branch, per our current workflow. @ssolson or I can do a final review once the test is in.

Adam

[mbruggs]

Thanks for the input everyone, much appreciated. I've added a test but it found it hard to know exactly what the test should be. In the end, the test is against a 'known value', ie computed with the function under test itself. This should, at least, guard against any unexpected changes in the function signature or calculation, assuming that the current calculation is correct.

Sorry for missing that the branch should be merged into Develop. I've rebased my branch against Develop so the merge should be neat.

Thanks again for all the work on MHKiT!