class_docstr: Returns private cumulative sums by clipping and adding correlated noise.
  
  Consider calling `get_noised_result` T times, and each (x_i, i=0,2,...,T-1) is
  the private value returned by `accumulate_record`, i.e. x_i = sum_{j=0}^{n-1}
  x_{i,j} where each x_{i,j} is a private record in the database. This class is
  intended to make multiple queries, which release privatized values of the
  cumulative sums s_i = sum_{k=0}^{i} x_k, for i=0,...,T-1.
  Each call to `get_noised_result` releases the next cumulative sum s_i, which
  is in contrast to the GaussianSumQuery that releases x_i. Noise for the
  cumulative sums is accomplished using the tree aggregation logic in
  `tree_aggregation`, which is proportional to log(T).
  
  Example usage:
    query = TreeCumulativeSumQuery(...)
    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_cumsum is privatized estimate of s_i
      noised_cumsum, 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: `Collection[tf.TensorSpec]` specifying 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: ["Returns","private","cumulative","sums","by","clipping","and","adding","correlated","noise",".","Consider","calling","`","get_noised_result","`","T","times",",","and","each","(","x_i",",","i=0,2",",","...",",","T-1",")","is","the","private","value","returned","by","`","accumulate_record","`",",","i.e",".","x_i","=","sum_","{","j=0","}","^","{","n-1","}","x_","{","i",",","j","}","where","each","x_","{","i",",","j","}","is","a","private","record","in","the","database",".","This","class","is","intended","to","make","multiple","queries",",","which","release","privatized","values","of","the","cumulative","sums","s_i","=","sum_","{","k=0","}","^","{","i","}","x_k",",","for","i=0",",","...",",","T-1",".","Each","call","to","`","get_noised_result","`","releases","the","next","cumulative","sum","s_i",",","which","is","in","contrast","to","the","GaussianSumQuery","that","releases","x_i",".","Noise","for","the","cumulative","sums","is","accomplished","using","the","tree","aggregation","logic","in","`","tree_aggregation","`",",","which","is","proportional","to","log","(","T",")",".","Example","usage",":","query","=","TreeCumulativeSumQuery","(","...",")","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_cumsum","is","privatized","estimate","of","s_i","noised_cumsum",",","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",":","`","Collection","[","tf.TensorSpec","]","`","specifying","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: Initializes the `TreeCumulativeSumQuery`.
  
  Consider using `build_l2_gaussian_query` for the construction of a
  `TreeCumulativeSumQuery` with L2 norm clipping and Gaussian noise.
  
  Args:
    record_specs: A nested structure of `tf.TensorSpec`s specifying structure
      and shapes of records.
    noise_generator: `tree_aggregation.ValueGenerator` to generate the noise
      value for a tree node. Should be coupled with clipping norm to guarantee
      privacy.
    clip_fn: Callable that specifies clipping function. Input to clip is a
      flat list of vars in a record.
    clip_value: Float indicating the value at which to clip the record.
    use_efficient: Boolean indicating the usage of the efficient tree
      aggregation algorithm based on the paper "Efficient Use of
      Differentially Private Binary Trees".
docstr_tok: ["Initializes","the","`","TreeCumulativeSumQuery","`",".","Consider","using","`","build_l2_gaussian_query","`","for","the","construction","of","a","`","TreeCumulativeSumQuery","`","with","L2","norm","clipping","and","Gaussian","noise",".","Args",":","record_specs",":","A","nested","structure","of","`","tf.TensorSpec","`","s","specifying","structure","and","shapes","of","records",".","noise_generator",":","`","tree_aggregation.ValueGenerator","`","to","generate","the","noise","value","for","a","tree","node",".","Should","be","coupled","with","clipping","norm","to","guarantee","privacy",".","clip_fn",":","Callable","that","specifies","clipping","function",".","Input","to","clip","is","a","flat","list","of","vars","in","a","record",".","clip_value",":","Float","indicating","the","value","at","which","to","clip","the","record",".","use_efficient",":","Boolean","indicating","the","usage","of","the","efficient","tree","aggregation","algorithm","based","on","the","paper","``","Efficient","Use","of","Differentially","Private","Binary","Trees","''","."]
code: def __init__(
      self,
      record_specs,
      noise_generator,
      clip_fn,
      clip_value,
      use_efficient=True,
  ):
      """Initializes the `TreeCumulativeSumQuery`.
  
      Consider using `build_l2_gaussian_query` for the construction of a
      `TreeCumulativeSumQuery` with L2 norm clipping and Gaussian noise.
  
      Args:
        record_specs: A nested structure of `tf.TensorSpec`s specifying structure
          and shapes of records.
        noise_generator: `tree_aggregation.ValueGenerator` to generate the noise
          value for a tree node. Should be coupled with clipping norm to guarantee
          privacy.
        clip_fn: Callable that specifies clipping function. Input to clip is a
          flat list of vars in a record.
        clip_value: Float indicating the value at which to clip the record.
        use_efficient: Boolean indicating the usage of the efficient tree
          aggregation algorithm based on the paper "Efficient Use of
          Differentially Private Binary Trees".
      """
      self._clip_fn = clip_fn
      self._clip_value = clip_value
      self._record_specs = record_specs
      if use_efficient:
          self._tree_aggregator = (
              tree_aggregation.EfficientTreeAggregator(noise_generator)
          )
      else:
          self._tree_aggregator = tree_aggregation.TreeAggregator(
              noise_generator
          )
  
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 1 to create a new TreeCumulativeSumQuery object from inherited base classes: dp_query with example: obj = TreeCumulativeSumQuery(record_specs, noise_generator, clip_fn, clip_value, use_efficient)