class_docstr: Implements DPQuery for adding correlated noise through tree structure.
  
  Clips and sums records in current sample x_i = sum_{j=0}^{n-1} x_{i,j};
  returns the current sample adding the noise residual from tree aggregation.
  The returned value is conceptually equivalent to the following: calculates
  cumulative sum of samples over time s_i = sum_{k=0}^i x_i (instead of only
  current sample) with added noise by tree aggregation protocol that is
  proportional to log(T), T being the number of times the query is called; r
  eturns the residual between the current noised cumsum noised(s_i) and the
  previous one noised(s_{i-1}) when the query is called.
  
  This can be used as a drop-in replacement for `GaussianSumQuery`, and can
  offer stronger utility/privacy tradeoffs when aplification-via-sampling is not
  possible, or when privacy epsilon is relativly large.  This may result in
  more noise by a log(T) factor in each individual estimate of x_i, but if the
  x_i are used in the underlying code to compute cumulative sums, the noise in
  those sums can be less. That is, this allows us to adapt code that was written
  to use a regular `SumQuery` to benefit from the tree aggregation protocol.
  
  Combining this query with a SGD optimizer can be used to implement the
  DP-FTRL algorithm in
  "Practical and Private (Deep) Learning without Sampling or Shuffling".
  
  Example usage:
    query = TreeResidualSumQuery(...)
    global_state = query.initial_global_state()
    params = query.derive_sample_params(global_state)
    for i, samples in enumerate(streaming_samples):
      sample_state = query.initial_sample_state(samples[0])
      # Compute  x_i = sum_{j=0}^{n-1} x_{i,j}
      for j,sample in enumerate(samples):
        sample_state = query.accumulate_record(params, sample_state, sample)
      # noised_sum is privatized estimate of x_i by conceptually postprocessing
      # noised cumulative sum s_i
      noised_sum, global_state, event = query.get_noised_result(
        sample_state, global_state)
  
  Attributes:
    clip_fn: Callable that specifies clipping function. `clip_fn` receives two
      arguments: a flat list of vars in a record and a `clip_value` to clip the
        corresponding record, e.g. clip_fn(flat_record, clip_value).
    clip_value: float indicating the value at which to clip the record.
    record_specs: A nested structure of `tf.TensorSpec`s specifying structure
      and shapes of records.
    tree_aggregator: `tree_aggregation.TreeAggregator` initialized with user
      defined `noise_generator`. `noise_generator` is a
      `tree_aggregation.ValueGenerator` to generate the noise value for a tree
      node. Noise stdandard deviation is specified outside the `dp_query` by the
      user when defining `noise_fn` and should have order
      O(clip_norm*log(T)/eps) to guarantee eps-DP.
class_docstr_tok: ["Implements","DPQuery","for","adding","correlated","noise","through","tree","structure",".","Clips","and","sums","records","in","current","sample","x_i","=","sum_","{","j=0","}","^","{","n-1","}","x_","{","i",",","j","}",";","returns","the","current","sample","adding","the","noise","residual","from","tree","aggregation",".","The","returned","value","is","conceptually","equivalent","to","the","following",":","calculates","cumulative","sum","of","samples","over","time","s_i","=","sum_","{","k=0","}","^i","x_i","(","instead","of","only","current","sample",")","with","added","noise","by","tree","aggregation","protocol","that","is","proportional","to","log","(","T",")",",","T","being","the","number","of","times","the","query","is","called",";","r","eturns","the","residual","between","the","current","noised","cumsum","noised","(","s_i",")","and","the","previous","one","noised","(","s_","{","i-1","}",")","when","the","query","is","called",".","This","can","be","used","as","a","drop-in","replacement","for","`","GaussianSumQuery","`",",","and","can","offer","stronger","utility\/privacy","tradeoffs","when","aplification-via-sampling","is","not","possible",",","or","when","privacy","epsilon","is","relativly","large",".","This","may","result","in","more","noise","by","a","log","(","T",")","factor","in","each","individual","estimate","of","x_i",",","but","if","the","x_i","are","used","in","the","underlying","code","to","compute","cumulative","sums",",","the","noise","in","those","sums","can","be","less",".","That","is",",","this","allows","us","to","adapt","code","that","was","written","to","use","a","regular","`","SumQuery","`","to","benefit","from","the","tree","aggregation","protocol",".","Combining","this","query","with","a","SGD","optimizer","can","be","used","to","implement","the","DP-FTRL","algorithm","in","''","Practical","and","Private","(","Deep",")","Learning","without","Sampling","or","Shuffling","''",".","Example","usage",":","query","=","TreeResidualSumQuery","(","...",")","global_state","=","query.initial_global_state","(",")","params","=","query.derive_sample_params","(","global_state",")","for","i",",","samples","in","enumerate","(","streaming_samples",")",":","sample_state","=","query.initial_sample_state","(","samples","[","0","]",")","#","Compute","x_i","=","sum_","{","j=0","}","^","{","n-1","}","x_","{","i",",","j","}","for","j",",","sample","in","enumerate","(","samples",")",":","sample_state","=","query.accumulate_record","(","params",",","sample_state",",","sample",")","#","noised_sum","is","privatized","estimate","of","x_i","by","conceptually","postprocessing","#","noised","cumulative","sum","s_i","noised_sum",",","global_state",",","event","=","query.get_noised_result","(","sample_state",",","global_state",")","Attributes",":","clip_fn",":","Callable","that","specifies","clipping","function",".","`","clip_fn","`","receives","two","arguments",":","a","flat","list","of","vars","in","a","record","and","a","`","clip_value","`","to","clip","the","corresponding","record",",","e.g",".","clip_fn","(","flat_record",",","clip_value",")",".","clip_value",":","float","indicating","the","value","at","which","to","clip","the","record",".","record_specs",":","A","nested","structure","of","`","tf.TensorSpec","`","s","specifying","structure","and","shapes","of","records",".","tree_aggregator",":","`","tree_aggregation.TreeAggregator","`","initialized","with","user","defined","`","noise_generator","`",".","`","noise_generator","`","is","a","`","tree_aggregation.ValueGenerator","`","to","generate","the","noise","value","for","a","tree","node",".","Noise","stdandard","deviation","is","specified","outside","the","`","dp_query","`","by","the","user","when","defining","`","noise_fn","`","and","should","have","order","O","(","clip_norm","*","log","(","T",")","\/eps",")","to","guarantee","eps-DP","."]
docstr: Clips the l2 norm, returning the clipped record and the l2 norm.
  
  Args:
    params: The parameters for the sample.
    record: The record to be processed.
  
  Returns:
    A tuple (preprocessed_records, l2_norm) where `preprocessed_records` is
      the structure of preprocessed tensors, and l2_norm is the total l2 norm
      before clipping.
docstr_tok: ["Clips","the","l2","norm",",","returning","the","clipped","record","and","the","l2","norm",".","Args",":","params",":","The","parameters","for","the","sample",".","record",":","The","record","to","be","processed",".","Returns",":","A","tuple","(","preprocessed_records",",","l2_norm",")","where","`","preprocessed_records","`","is","the","structure","of","preprocessed","tensors",",","and","l2_norm","is","the","total","l2","norm","before","clipping","."]
code: def preprocess_record_l2_impl(self, params, record):
      """Clips the l2 norm, returning the clipped record and the l2 norm.
  
      Args:
        params: The parameters for the sample.
        record: The record to be processed.
  
      Returns:
        A tuple (preprocessed_records, l2_norm) where `preprocessed_records` is
          the structure of preprocessed tensors, and l2_norm is the total l2 norm
          before clipping.
      """
      l2_norm_clip = params
      record_as_list = tf.nest.flatten(record)
      clipped_as_list, norm = tf.clip_by_global_norm(
          record_as_list, l2_norm_clip
      )
      return tf.nest.pack_sequence_as(record, clipped_as_list), norm
  
imports: import collections
  from typing import Any, NamedTuple
  import dp_accounting
  import tensorflow
  from tensorflow_privacy.privacy.dp_query import dp_query
  from tensorflow_privacy.privacy.dp_query import tree_aggregation
label_desc: Use image node_id 5 for calling the TreeResidualSumQuery obj's underlying member method code with example usage: obj.preprocess_record_l2_impl(params, record) and returns: tf,  norm