Optional flag and functionality to adjust calculation of spring magnitude metric

[nickrsan]

The way the FFC API calculates spring magnitude finds a date by behavior and then moves the date by four days (I don't recall why). Some of the team members want the ability to disable the date move, but not impact existing calculations from the API. A good option for this is to have the FFC API Client handle the adjustment since it can be turned on and off and doesn't involve deploying an update to a wider audience on the server side.

This involves a few pieces of work:

• A new flag needs to be added to the FFCProcessor class. It could be something like perform_spring_magnitude_adjustment = FALSE, - I'd recommend this go somewhere near line 357 (https://github.com/ceff-tech/ffc_api_client/blob/release/ffcAPIClient/R/ffc_api_client.R#L357)
• Need to add a function that conditionally does the filtering. I'd recommend a few things here:
  • Around this line, add a new variable named something like ffc_results_pre_spring_fix = NA,
  • Then, somewhere like this, add a new code block like the following:

    if(self$perform_spring_magnitude_adjustment){
      self$prefix_ffc_results <- self$ffc_results  # back up the original results
      self$ffc_results <- self$adjust_spring_magnitude(days=4)
    }

• while adding another function to the class (somewhere around line 507 is fine) that looks something like the following:

    adjust_spring_magnitude=function(days){
        # a function that accepts a number of days to adjust the spring magnitude metric
        current_results <- self$ffc_results
        # 
        # ... code that fixes spring magnitude timing based on the number of days specified to adjust in the parameters here ...
        # the thing to note is that this class has access to all the data that went into and came out of the FFC. We can access
        # the input timeseries, the returned metrics, etc.
        new_results <- output_of_the_above_section  # this is pseudocode - we just need a new object named new_results that has everything in self$ffc_results, but with the fixed spring timing info

        return(new_results)
    }

@kristaniguchi it'd be worth knowing a verbal description of what's required to adjust the magnitude value. Is it that once we know the day of year, we go look at input timeseries (of which there can be many years), or do we look at the DOH data and pull the magnitude values for the new day of the year we want to use? Can you describe what data has the values we want to pull data from?

[nickrsan]

And then once we get the question above settled, I can make a few more recommendations and we can talk about workflows to build it into the code and how to edit it, etc.

[kristaniguchi]

Thanks starting this issue thread, @nickrsan. For snowmelt driven systems, the FFC is supposed to take the flow magnitude 4 days prior to the spring timing to ensure that a storm event peak (blip) that occurred during the spring recession isn't getting picked up. For non-snowmelt systems, the FFC should take the magnitude at spring timing but the FFC takes the magnitude 4 days prior in all cases.

So what we want to do is for non-snowmelt systems, we want to take the spring timing each water year and find the flow magnitude corresponding to that day. So we essentially need to pull the data from the flow timeseries with water year column appended. For every water year, find the water year day of the spring timing and get the associated magnitude. That will be our new spring mag value.

[kristaniguchi]

Another thing to update would be the percentiles for the revised spring mag calculations and potentially the alteration assessment (if this is easily done) but priority would be on updating percentiles. Thanks, @nickrsan!