dsBase/docs/reference/blackBoxDS.html at 69e0bf65a4e7ab6bdeb7a20299972fa62759fafe · datashield/dsBase · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en-GB"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Secure ranking of "V2BR" (vector to be ranked) across all sources — blackBoxDS • dsBase</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js" integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><!-- Bootstrap --><link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/simplex/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Secure ranking of " v2br to be ranked across all sources blackboxds><meta property="og:description" content="The first key serverside function that sets up the V2BR for
ranking in the client."><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body data-spy="scroll" data-target="#toc">


    <div class="container template-reference-topic">
      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">dsBase</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="">7.0.0.9000</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav"><li>
  <a href="../reference/index.html">Reference</a>
</li>
      </ul><ul class="nav navbar-nav navbar-right"></ul></div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->


      </header><div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Secure ranking of "V2BR" (vector to be ranked) across all sources</h1>

    <div class="hidden name"><code>blackBoxDS.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>The first key serverside function that sets up the V2BR for
ranking in the client.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">blackBoxDS</span><span class="op">(</span>input.var.name <span class="op">=</span> <span class="cn">NULL</span>, <span class="va">shared.seedval</span>, <span class="va">synth.real.ratio</span>, <span class="va">NA.manage</span><span class="op">)</span></span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>


<dl><dt id="arg-input-var-name">input.var.name<a class="anchor" aria-label="anchor" href="#arg-input-var-name"></a></dt>
<dd><p>a character string specifying the name of V2BR. This
argument is set by the argument with the same name in the clientside function
ds.ranksSecure</p></dd>


<dt id="arg-shared-seedval">shared.seedval<a class="anchor" aria-label="anchor" href="#arg-shared-seedval"></a></dt>
<dd><p>a pseudorandom number seed that ensures that the
processes generating the order and parameterisation of the encryption
algorithms are the same in each study. This argument is set by the argument
&lt;shared.seed.value&gt; in the clientside function ds.ranksSecure. For more
details, including future plans to share this starting seed in a more secure
way, please see the associated document entitled "secure.global.ranking.docx"
and the header file for ds.ranksSecure.</p></dd>


<dt id="arg-synth-real-ratio">synth.real.ratio<a class="anchor" aria-label="anchor" href="#arg-synth-real-ratio"></a></dt>
<dd><p>an integer value representing
the ratio of synthetic (pseudo-data) values to the real number of
values in V2BR. This argument is set by the argument with the same name
in the clientside function ds.ranksSecure. For more details, please see the
associated document entitled "secure.global.ranking.docx" and the header file
for ds.ranksSecure.</p></dd>


<dt id="arg-na-manage">NA.manage<a class="anchor" aria-label="anchor" href="#arg-na-manage"></a></dt>
<dd><p>character string indicating how missing values (NAs) in
V2BR should be managed. It takes three possible values: "NA.delete",
"NA.low","NA.hi". This argument is set by the argument with the same name
in the clientside function ds.ranksSecure. For more details, please see the
associated document entitled "secure.global.ranking.docx" and the header file
for ds.ranksSecure.</p></dd>

</dl></div>
    <div id="value">
    <h2>Value</h2>
    <p>writes a data frame object entitled blackbox.output.df to the
serverside. In each study this contains the encrypted
"combined real+pseudo data vector" and a range of other key components
from the first stage of the ranking procedure. For more details see the
associated document entitled "secure.global.ranking.docx"</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p>Severside assign function called by ds.ranksSecure.
Creates pseudo-data by using the real distribution of values in V2BR
to create a large number of synthetic data with a similar distribution to
the values in V2BR but with a slightly broader distribution at both ends
to ensure that any extreme values in the "combined real+pseudo data vector"
are all pseudo-data. Also ensures that the number of decimal places of
the values in the V2BR is reflected by the number of decimal places in
the pseudodata. Finally, takes the "combined real+pseudo data vector" through
seven rounds of rank consistent encryption that involves algorithms
themselves generated by a pseudorandom process that selects which
transformation to apply and with what parameters. The encryption algorithms
are the same in each study ensuring that ranks also remain consistent between
studies. After encryption the encrypted "combined real+pseudo data vector" is
written to the serverside as a dataframe also including other key component
vectors from the first stage of the ranking procedure.
For more details about the cluster of functions that
collectively enable secure global ranking and estimation of global quantiles
see the associated document entitled "secure.global.ranking.docx". Also
see the header file for ds.ranksSecure</p>
    </div>
    <div id="author">
    <h2>Author</h2>
    <p>Paul Burton 9th November, 2021</p>
    </div>

  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
    <nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
    </nav></div>
</div>


      <footer><div class="copyright">
  <p></p><p>Developed by Paul Burton, Rebecca Wilson, Olly Butters, Patricia Ryser-Welch, Alex Westerberg, Leire Abarrategui, Roberto Villegas-Diaz, Demetris Avraam, Yannick Marcon, Tom Bishop, Amadou Gaye, Xavier Escribà-Montagut, Stuart Wheater.</p>
</div>

<div class="pkgdown">
  <p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.2.0.</p>
</div>

      </footer></div>


  </body></html>