Deployed e036b0c with MkDocs version: 1.5.3

aggregator/index.html

@@ -97,18 +97,20 @@
             <div class="section" itemprop="articleBody">
 
                 <h1 id="aggregator">Aggregator</h1>
-<p>The aggregator obtains the mapped data of a ledger (from <code>output/&lt;project_name&gt;/mapped_data.json</code>), aggregates it
-over the given timeframe(s) and outputs one or more <code>csv</code> files with the distribution of block to entities,
-structured as follows:</p>
-<pre><code>Entity,Resources
-&lt;name of entity&gt;,&lt;(int) number of blocks&gt;
+<p>The aggregator obtains the mapped data of a ledger (from <code>output/&lt;project_name&gt;/mapped_data.json</code>) and aggregates it
+over units of time that are determined based on the given <code>timeframe</code> and <code>aggregate_by</code> parameters.
+It then outputs a <code>csv</code> file with the distribution of blocks to entities for each time unit under consideration.
+This file is saved in the directory <code>output/&lt;project name&gt;/blocks_per_entity/</code> and is named based on the <code>timeframe</code>
+and <code>aggregate_by</code> parameters.
+For example, if the specified timeframe is from June 2023 to September 2023 and the aggregation is by month, then
+the output file would be named <code>monthly_from_2023-06-01_to_2023-09-30.csv</code> and would be structured as follows:</p>
+<pre><code>Entity \ Time period,Jun-2023,Jul-2023,Aug-2023,Sep-2023
+&lt;name of entity 1&gt;,&lt;number of blocks produced by entity 1 in June 2023&gt;,&lt;number of blocks produced by entity 1 in July 2023&gt;,&lt;number of blocks produced by entity 1 in August 2023&gt;,&lt;number of blocks produced by entity 1 in September 2023&gt;
+&lt;name of entity 2&gt;,&lt;number of blocks produced by entity 2 in June 2023&gt;,&lt;number of blocks produced by entity 2 in July 2023&gt;,&lt;number of blocks produced by entity 2 in August 2023&gt;,&lt;number of blocks produced by entity 2 in September 2023&gt;
 </code></pre>
-<p>Specifically, if the <code>timeframe</code> argument is provided during execution, then the mapping outputs a single <code>csv</code> 
-file that corresponds to that timeframe. Otherwise, it outputs a <code>csv</code> file for each month contained in the default 
-time range (as specified in the <a href="https://github.com/Blockchain-Technology-Lab/pooling-analysis/blob/main/config.yaml">config file</a>). 
-It also outputs a <code>csv</code> file for each year contained in the relevant time frames.</p>
-<p>Each <code>csv</code> file is named after the timeframe over which the mapping was executed (e.g., <code>2021-04.csv</code>) and is
-stored in a dedicated folder in the project's output directory (<code>output/&lt;project_name&gt;/blocks_per_entity/</code>).</p>
+<p>Therefore, the file will have as many rows as the number of entities that have produced blocks in the given
+timeframe (+ 1 for the header) and as many columns as the number of time units in the given timeframe (+ 1 for the
+entity names).</p>
 
             </div>
           </div><footer>

index.html

@@ -117,13 +117,15 @@ <h2 id="overview">Overview</h2>
 with all the information that is needed for the mapping.</p>
 <p>The mapping takes the output of the parser, combines it with some other sources of information, and produces a new 
 file that includes attribution data for each block and which mapping method was used to obtain it.</p>
-<p>The aggregator takes as input the output of the mapping, as well as one or more time frames to aggregate over. It then 
-outputs a file for each time frame that reveals the distribution of resources to different entities during that time 
-frame. In this context, "resources" correspond to the number of produced blocks.</p>
+<p>The aggregator takes as input the output of the mapping, as well as a time frame to aggregate over and a unit to 
+divide the time frame by (e.g. week or month).
+It then outputs a file that reveals the distribution of resources to different entities during each time unit under 
+consideration.
+In this context, "resources" correspond to the number of produced blocks.</p>
 <p>These distributions are then the input for the metrics module, which tracks various
 decentralization-related metrics and produces files with the results.</p>
-<p>More details about the different modules can be found in the corresponding <a href="parsers/">Parser</a>, <a href="mappings/">Mapping</a>
-and <a href="metrics/">Metrics</a> pages.</p>
+<p>More details about the different modules can be found in the corresponding <a href="parsers/">Parser</a>, <a href="mappings/">Mapping</a>,
+<a href="aggregator/">Aggregator</a> and <a href="metrics/">Metrics</a> pages.</p>
 <p>Currently, the supported ledgers are:</p>
 <ul>
 <li>Bitcoin</li>
@@ -135,7 +137,7 @@ <h2 id="overview">Overview</h2>
 <li>Tezos</li>
 <li>Zcash</li>
 </ul>
-<p>We intend to add more ledgers to this list in the future. </p>
+<p>We intend to add more ledgers to this list in the future.</p>
 <h2 id="contributing">Contributing</h2>
 <p>This is an open source project licensed under the terms and conditions of the 
 <a href="https://github.com/Blockchain-Technology-Lab/consensus-decentralization/blob/main/LICENSE">MIT license</a> and
@@ -200,5 +202,5 @@ <h2 id="contributing">Contributing</h2>
 
 <!--
 MkDocs version : 1.5.3
-Build Date UTC : 2023-10-05 13:47:03.079361+00:00
+Build Date UTC : 2023-10-06 09:45:12.044458+00:00
 -->

setup/index.html

@@ -121,19 +121,31 @@ <h2 id="execution">Execution</h2>
 in the <code>raw_block_data/</code> directory, each file named as <code>&lt;project_name&gt;_raw_data.json</code> (e.g., <code>bitcoin_raw_data.json</code>).
 By default,
 there is a (very small) sample input file for some supported projects; to use it, remove the prefix <code>sample_</code>.</p>
-<p>Run <code>python run.py --ledgers &lt;ledger_1&gt; &lt;ledger_n&gt; --timeframe &lt;timeframe&gt;</code> to
-analyze the n specified ledgers for the given timeframe.
-Both arguments are optional, so it's possible to omit one or both of them; in this case, the default values
+<p>Run <code>python run.py --ledgers &lt;ledger_1&gt; &lt;ledger_n&gt; --timeframe &lt;timeframe&gt; --aggregate-by &lt;unit to aggregate by&gt;</code> to
+analyze the n specified ledgers for the given timeframe, aggregated using the given granularity.
+All arguments are optional, so it's possible to omit any of them; in this case, the default values
 will be used. Specifically:</p>
 <ul>
-<li><code>ledgers</code> accepts any number of the supported ledgers (case-insensitive). For example, <code>--ledgers bitcoin</code>
-would run the analysis for Bitcoin, while <code>--ledgers Bitcoin Ethereum Cardano</code> would run the analysis for Bitcoin,
-Ethereum and Cardano. If the <code>ledgers</code> argument is omitted, then all supported ledgers are analyzed.</li>
-<li>The <code>timeframe</code> argument should be of the form <code>YYYY-MM-DD</code> (month and day can be omitted). For example,
-<code>--timeframe 2022</code> would run the analysis for the year 2022, while <code>--timeframe 2022-02</code> would do it for the month of
-February 2022 and <code>--timeframe 2022-02-03</code> would do it for a single day (Feburary 3rd 2022). If the <code>timeframe</code> 
-argument is omitted, then a monthly analysis is performed for each month between January 2010 and the current month 
-or the subset of this time period for which relevant data exists.</li>
+<li><code>ledgers</code> accepts any number of the supported ledgers (case-insensitive). For example, <code>--ledgers bitcoin</code> 
+  would run the analysis for Bitcoin, while <code>--ledgers Bitcoin Ethereum Cardano</code> would run the analysis for Bitcoin, 
+  Ethereum and Cardano. If the <code>ledgers</code> argument is omitted, then the analysis is performed for the ledgers 
+  specified in the <code>config.yaml</code> file, which are typically all supported ledgers.</li>
+<li>The <code>timeframe</code> argument accepts one or two values of the form <code>YYYY-MM-DD</code> (month and day can be
+  omitted), which indicate the beginning and end of the time period that will be analyzed. For example, 
+  <code>--timeframe 2022</code> would run the analysis for the year 2022 (so from January 1st 2022 to 
+  December 31st 2022), while we could also get the same result using <code>--timeframe 2022-01 2022-12</code> or 
+  <code>--timeframe 2022-01-01 2022-12-31</code>. Similarly, <code>--timeframe 2022-02</code> or <code>--timeframe 2022-02-01 2022-02-28</code> would 
+  do it for the month of February 2022 (February 1st 2022 to February 28th 2022), while <code>--timeframe 2022-02-03</code> 
+  would do it for a single day (Feburary 3rd 2022). Last, <code>--timeframe 2018 2022</code> would run the analysis for the 
+  entire time period between January 1st 2018 and December 31st 2022. If the <code>timeframe</code> argument is omitted, then 
+  the start date and end dates of the time frame are sourced from the <code>config.yaml</code> file.</li>
+<li><code>aggregate_by</code> corresponds to the unit of time to aggregate the data by, i.e. the granularity of the analysis. 
+  It can be one of: <code>day</code>, <code>week</code>, <code>month</code>, <code>year</code>, <code>all</code> and by default it is <code>month</code>. Note that in the case of 
+  weekly aggregation, we consider a week to be 7 consecutive days, starting from the first day of the time period 
+  under consideration (so not necessarily Monday to Sunday). If "all" is chosen, then no aggregation will be 
+  performed, meaning that the given timeframe will be treated as a single unit of time in the context of our 
+  analysis. In all other cases, the given timeframe will be divided into units of the given granularity and the 
+  result will be a time series.</li>
 </ul>
 <p>Additionally, there are three flags that can be used to customize an execution:</p>
 <ul>