Merge pull request #258 from EHDEN/imp/some_documentation_improvements

Imp/some documentation improvements

dashboard_viewer/dashboard_viewer/settings.py

@@ -203,7 +203,7 @@
 
 
 # Redis
-REDIS_HOST = os.environ.get("REDIS_HOST", "redis")
+REDIS_HOST = os.environ.get("REDIS_HOST", "localhost")
 REDIS_PORT = os.environ.get("REDIS_PORT", 6379)
 REDIS_CACHE_DB = os.environ.get("REDIS_CACHE_DB", 0)
 REDIS_CELERY_DB = os.environ.get("REDIS_CELERY_DB", 1)

docs/02-installation.md

@@ -20,7 +20,7 @@ Currently, we use docker to deploy our environment
 
 1. If you wish to expose the dashboard viewer app through a specific domain(s) you must add it/them to the `ALLOWED_HOSTS` list on file `dashboard_viewer/dashboard_viewer/settings.py` and remove the `'*'` entry.
 
-2. Build containers' images: `docker-compose build`. This might take several minutes.
+2. In production, all of our docker services use prebuilt images present in DockerHub, however, if you are in development mode and are using the `docker-compose-dev.yml`, you should build the images for the dashboard containers with `docker-compose build`.
 
 3. Set up the database and create an admin account for the dashboard viewer app: `docker-compose run --rm dashboard ./docker-init.sh`.
 
@@ -114,6 +114,7 @@ The concepts table is not in the repository due to its dimension, therefore we u
    - can read on Chart
    - can read on CssTemplate
    - can read on Dashboard
+   - can time range on Api
 
 6. For each dashboard you want anonymous users to be able to access, on the dashboard list page click edit (the pencil on the right) and add the "Admin" and "Public" roles to the "Roles with acess" field.
 

docs/11-network-dashboard.md

@@ -24,10 +24,13 @@ add the following JSON entry to the JSON object of the `JSON Metadata` field on
 
 ### CSS {-}
 
-To hide the dashboard header insert the following css code to the `CSS` field on the edit page:
+Whenever a user types some texts on superset's filters the avaiable options on it are filtered.
+Whenever no option matches the text inserted a 'Create option "[inserted text]"'.
+Since Superset filters do exact match, this option will for sure return no results.
+Because of that, this option is being hidden with the following CSS:
 
 ```css
-.dashboard > div:not(.dashboard-content) {  /* dashboard header */
+.css-0.Select__option {
   display: none;
 }
 ```
@@ -37,6 +40,31 @@ or remove it so the "Edit Dashboard" button can show again.
 
 ### Filters {-}
 
+#### Mappings {-}
+
+This defines which charts specific filters will affect.
+This can be edited by entering in edit mode, click the three dots near the "Save" and then go to "Set filter mappings".
+To apply a mapping you have to select a set of filters on the left, choose on the right which charts it affects and finally hit save.
+You have to do this procedure for the different sets of filters that have different mappings.
+
+This is done mainly to not confuse the user.
+Let's say you choose "Portugal" on the country filter and that databases from Portugal only have records of the Dug domain.
+After this, if the user clicks on the domain filter dropdown, only the Drug domain option will appear.
+With this, the user might get the idea that the system only has records of the Drug domain.
+If all options appear on the domain filter, the charts will show "No results" and with this, the users should conclude that for the set of filters defined there is no data.
+
+Global filters: note that it does not affect the other filters mentioned below.  
+![](images/11-network-dashboard/01-filters/filter-mappings/global-filters.png)
+
+Domain Filter  
+![](images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png)
+
+Concept Filter: Note that it does not affect the Domain filter  
+![](images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png)
+
+Number of patitents in observation period time range  
+![](images/11-network-dashboard/01-filters/filter-mappings/number-of-patients-in-obs-period-time-range.png)
+
 #### Country Filter {-}
 
 Dataset: Materialized View [meta_data_table](materialized-views-1.html#meta_data_table)

docs/404.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/DataNetworkDashboards.tex

@@ -120,7 +120,7 @@
 
 \title{Data Network Dashboards}
 \author{This document is currently under construction}
-\date{2022-06-18}
+\date{2022-07-06}
 
 \begin{document}
 \maketitle
@@ -258,7 +258,7 @@ \subsection*{Dashboard Viewer setup}\label{dashboard-viewer-setup}}
 \item
   If you wish to expose the dashboard viewer app through a specific domain(s) you must add it/them to the \texttt{ALLOWED\_HOSTS} list on file \texttt{dashboard\_viewer/dashboard\_viewer/settings.py} and remove the \texttt{\textquotesingle{}*\textquotesingle{}} entry.
 \item
-  Build containers' images: \texttt{docker-compose\ build}. This might take several minutes.
+  In production, all of our docker services use prebuilt images present in DockerHub, however, if you are in development mode and are using the \texttt{docker-compose-dev.yml}, you should build the images for the dashboard containers with \texttt{docker-compose\ build}.
 \item
   Set up the database and create an admin account for the dashboard viewer app: \texttt{docker-compose\ run\ -\/-rm\ dashboard\ ./docker-init.sh}.
 \end{enumerate}
@@ -388,6 +388,8 @@ \subsection*{Superset setup}\label{superset-setup}}
     can read on CssTemplate
   \item
     can read on Dashboard
+  \item
+    can time range on Api
   \end{itemize}
 \item
   For each dashboard you want anonymous users to be able to access, on the dashboard list page click edit (the pencil on the right) and add the ``Admin'' and ``Public'' roles to the ``Roles with acess'' field.
@@ -1050,18 +1052,24 @@ \subsection*{Github Actions}\label{github-actions}}
 Sometimes prospector can be a pain in the boot, complaining about too much stuff.
 You can make prospector ignore some bad stuff by adding the comment, \texttt{\#\ noqa}, to the end of the specific line where it is complaining.
 
+To run only a single tool with tox you have to set the \texttt{TOX\_ENV} enviroment variable. For example, to run just black with tox you can run \texttt{TOX\_ENV=black\ tox}.
+
 \hypertarget{tests}{%
 \subsection*{Tests}\label{tests}}
 \addcontentsline{toc}{subsection}{Tests}
 
 Our tests use Django's building testing features, which uses unittest under the hood.
 Not all featured have tests associated, however, there are already \href{https://github.com/EHDEN/NetworkDashboards/issues?q=is\%3Aissue+is\%3Aopen+label\%3A\%22Test+Use+Case\%22}{some tests scenarios} in mind written as issues on the repository, which have the tag \textbf{Test Use Case}.
 
-To run the tests we set up a docker-compose stack, under the \href{https://github.com/EHDEN/NetworkDashboards/tree/master/tests}{test} directory which has just the necessary data containers (Redis and Postgres) to avoid having to make changes on the development/production docker-compose stack.
-Once the stack is up it only necessary to run \texttt{SECRET\_KEY=secret\ python\ manage.py\ test} to execute the tests.
+To run the tests we set up a docker-compose stack, under the \href{https://github.com/EHDEN/NetworkDashboards/tree/master/tests}{test} directory which has just the necessary data containers (Redis and Postgres) with open ports and with no volumes, to avoid having to make changes on the development/production docker-compose stack to run the tests.
+Once the stack is up it only necessary to run \texttt{python\ manage.py\ test} to execute the tests.
 If you are developing any tests that involve \href{https://github.com/celery/celery}{celery}, there is no need to have a celery process running, since on Django's settings.py we \href{https://github.com/EHDEN/NetworkDashboards/blob/master/dashboard_viewer/dashboard_viewer/settings.py\#L316}{set the test runner} to the celery one.
 This way the \texttt{python\ manage.py\ test} is enough to test the whole application.
 
+tox is an alternative and a good way to run all test commands without having to install the test requirements for each test case (code style checks, unit tests, \ldots). tox will create a tox environment, install the necessary dependencies run the test command.
+
+tox and its dependencies are in the file \texttt{requirements-dev/requirements-dev.txt}. After installing them you just need to execute \texttt{TOX\_ENV=tests\ tox} or \texttt{TOX\_ENV=tests-third-party\ tox} to run all the test cases.
+
 \hypertarget{python-requirements}{%
 \subsection*{Python Requirements}\label{python-requirements}}
 \addcontentsline{toc}{subsection}{Python Requirements}
@@ -1403,11 +1411,14 @@ \subsection*{Label Colors}\label{label-colors}}
 \subsection*{CSS}\label{css}}
 \addcontentsline{toc}{subsection}{CSS}
 
-To hide the dashboard header insert the following css code to the \texttt{CSS} field on the edit page:
+Whenever a user types some texts on superset's filters the avaiable options on it are filtered.
+Whenever no option matches the text inserted a `Create option ``{[}inserted text{]}''\,'.
+Since Superset filters do exact match, this option will for sure return no results.
+Because of that, this option is being hidden with the following CSS:
 
 \begin{Shaded}
 \begin{Highlighting}[]
-\FunctionTok{.dashboard} \OperatorTok{\textgreater{}}\NormalTok{ div}\InformationTok{:not(}\FunctionTok{.dashboard{-}content}\InformationTok{)}\NormalTok{ \{  }\CommentTok{/* dashboard header */}
+\FunctionTok{.css{-}0.Select\_\_option}\NormalTok{ \{}
   \KeywordTok{display}\NormalTok{: }\DecValTok{none}\OperatorTok{;}
 \NormalTok{\}}
 \end{Highlighting}
@@ -1420,6 +1431,33 @@ \subsection*{CSS}\label{css}}
 \subsection*{Filters}\label{filters}}
 \addcontentsline{toc}{subsection}{Filters}
 
+\hypertarget{mappings}{%
+\subsubsection*{Mappings}\label{mappings}}
+\addcontentsline{toc}{subsubsection}{Mappings}
+
+This defines which charts specific filters will affect.
+This can be edited by entering in edit mode, click the three dots near the ``Save'' and then go to ``Set filter mappings''.
+To apply a mapping you have to select a set of filters on the left, choose on the right which charts it affects and finally hit save.
+You have to do this procedure for the different sets of filters that have different mappings.
+
+This is done mainly to not confuse the user.
+Let's say you choose ``Portugal'' on the country filter and that databases from Portugal only have records of the Dug domain.
+After this, if the user clicks on the domain filter dropdown, only the Drug domain option will appear.
+With this, the user might get the idea that the system only has records of the Drug domain.
+If all options appear on the domain filter, the charts will show ``No results'' and with this, the users should conclude that for the set of filters defined there is no data.
+
+Global filters: note that it does not affect the other filters mentioned below.\\
+\includegraphics{images/11-network-dashboard/01-filters/filter-mappings/global-filters.png}
+
+Domain Filter\\
+\includegraphics{images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png}
+
+Concept Filter: Note that it does not affect the Domain filter\\
+\includegraphics{images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png}
+
+Number of patitents in observation period time range\\
+\includegraphics{images/11-network-dashboard/01-filters/filter-mappings/number-of-patients-in-obs-period-time-range.png}
+
 \hypertarget{country-filter}{%
 \subsubsection*{Country Filter}\label{country-filter}}
 \addcontentsline{toc}{subsubsection}{Country Filter}

docs/PerDatabaseDashboard.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />
@@ -337,15 +337,38 @@ <h3>Label Colors</h3>
 </div>
 <div id="css" class="section level3 unnumbered" number="">
 <h3>CSS</h3>
-<p>To hide the dashboard header insert the following css code to the <code>CSS</code> field on the edit page:</p>
-<div class="sourceCode" id="cb13"><pre class="sourceCode css"><code class="sourceCode css"><span id="cb13-1"><a href="PerDatabaseDashboard.html#cb13-1" aria-hidden="true"></a><span class="fu">.dashboard</span> <span class="op">&gt;</span> div<span class="in">:not(</span><span class="fu">.dashboard-content</span><span class="in">)</span> {  <span class="co">/* dashboard header */</span></span>
+<p>Whenever a user types some texts on superset’s filters the avaiable options on it are filtered.
+Whenever no option matches the text inserted a ‘Create option “[inserted text]”’.
+Since Superset filters do exact match, this option will for sure return no results.
+Because of that, this option is being hidden with the following CSS:</p>
+<div class="sourceCode" id="cb13"><pre class="sourceCode css"><code class="sourceCode css"><span id="cb13-1"><a href="PerDatabaseDashboard.html#cb13-1" aria-hidden="true"></a><span class="fu">.css-0.Select__option</span> {</span>
 <span id="cb13-2"><a href="PerDatabaseDashboard.html#cb13-2" aria-hidden="true"></a>  <span class="kw">display</span>: <span class="dv">none</span><span class="op">;</span></span>
 <span id="cb13-3"><a href="PerDatabaseDashboard.html#cb13-3" aria-hidden="true"></a>}</span></code></pre></div>
 <p>With this every time you want to edit the dashboard layout you have to either comment the CSS inserted
 or remove it so the “Edit Dashboard” button can show again.</p>
 </div>
 <div id="filters" class="section level3 unnumbered" number="">
 <h3>Filters</h3>
+<div id="mappings" class="section level4 unnumbered" number="">
+<h4>Mappings</h4>
+<p>This defines which charts specific filters will affect.
+This can be edited by entering in edit mode, click the three dots near the “Save” and then go to “Set filter mappings”.
+To apply a mapping you have to select a set of filters on the left, choose on the right which charts it affects and finally hit save.
+You have to do this procedure for the different sets of filters that have different mappings.</p>
+<p>This is done mainly to not confuse the user.
+Let’s say you choose “Portugal” on the country filter and that databases from Portugal only have records of the Dug domain.
+After this, if the user clicks on the domain filter dropdown, only the Drug domain option will appear.
+With this, the user might get the idea that the system only has records of the Drug domain.
+If all options appear on the domain filter, the charts will show “No results” and with this, the users should conclude that for the set of filters defined there is no data.</p>
+<p>Global filters: note that it does not affect the other filters mentioned below.<br />
+<img src="images/11-network-dashboard/01-filters/filter-mappings/global-filters.png" /></p>
+<p>Domain Filter<br />
+<img src="images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png" /></p>
+<p>Concept Filter: Note that it does not affect the Domain filter<br />
+<img src="images/11-network-dashboard/01-filters/filter-mappings/domain-filter.png" /></p>
+<p>Number of patitents in observation period time range<br />
+<img src="images/11-network-dashboard/01-filters/filter-mappings/number-of-patients-in-obs-period-time-range.png" /></p>
+</div>
 <div id="country-filter" class="section level4 unnumbered" number="">
 <h4>Country Filter</h4>
 <p>Dataset: Materialized View <a href="materialized-views-1.html#meta_data_table">meta_data_table</a></p>

docs/backups.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/code-documentation.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/concepts-browser-deprecated.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/customizations.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/dashboards.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/data-domains-deprecated.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/database-level-dashboard.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />

docs/death-deprecated.html

@@ -24,7 +24,7 @@
 <meta name="author" content="This document is currently under construction" />
 
 
-<meta name="date" content="2022-06-18" />
+<meta name="date" content="2022-07-06" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="apple-mobile-web-app-capable" content="yes" />