first commit: README files initial setup

.gitignore

@@ -3,5 +3,4 @@
 .RData
 .Ruserdata
 /project/.quarto/
-/project/_book/
-/adm/
+/project/_book/

README.md

@@ -1,6 +1,44 @@
-# Quarto book template for scientific article
+# (UNDER CONSTRUCTION) Quarto-TIER project for scientific article
 
-This repository is a template for you who want to develop an article in [Quarto book](https://quarto.org/docs/books/) structure.
+[![](https://zenodo.org/badge/DOI/10.5281/zenodo.10443127.svg)](https://doi.org/10.5281/zenodo.10443127)
+
+This repository is a template for you who want to develop an project article in [Quarto book](https://quarto.org/docs/books/) and [TIER protocol 4.0](https://www.projecttier.org/tier-protocol/protocol-4-0/) structure. The Quarto book is a tool for reproducible research and scientific writing. It is based on markdown and R language (Python, Julia and Observable), and integrated on RStudio. The TIER protocol 4.0 is a structure for organizing the project files and scripts.
+
+## Why Quarto book project and not manuscript project?
+
+There is a Quarto specific framework for dealing with scientific articles, [Quarto manuscript](https://quarto.org/docs/manuscripts/), and another for books, [Quarto book](https://quarto.org/docs/books/). Both share the same background, and they similar in many aspects, but the Quarto book project is more flexible, allows us to create a more complex structure, greater variability of layouts, and can be adapted to the TIER protocol structure. The Quarto manuscript is still recent and lacks some functionality to make it more interesting.
+
+In addition to the structure, the big difference between the two is that with Quarto manuscript the scripts **are integrated** into the outputs, while in Quarto book **they can be integrated** into the outputs. This is a big difference because it allows us to have a more organized project, with a clear separation between the scripts and the outputs.
+
+## How TIER protocol 4.0 can integrate with Quarto book?
+
+The TIER is a general protocol, aimed at both qualitative and quantitative research, both for those who do not intend to work with documents and for those who wish to make their research as reproducible as possible, with dynamic documents, such as Quarto. This template will make life easier for anyone who has decided to use an organization of folders and files based on TIER Protocol 4.0 and wants to carry out their research through Quarto, via RStudio.
+
+In this sense, the repository is already structured and adapted to handle the organization of TIER protocol 4.0 folders, and files necessary to insert the article narrative into Quarto documents. And not least, the repository is configured for you who will work with projects in RStudio with versioning (Git/GitHub), environment control (`renv`), and want to publish your article on GitHub Pages.
+
+## What advantages does this template offer?
+
+1.  **Organization**: The project is structured according to the TIER protocol 4.0, which facilitates the organization of the research.
+2.  **Flexibility**: The Quarto book allows you to create a more complex structure, with greater variability of layouts.
+3.  **Integration**: The Quarto book allows you to integrate the scripts into the outputs, but it is not mandatory.
+4.  **Versioning**: The project is already configured for versioning with Git/GitHub.
+5.  **Environment control**: The project is already configured with `renv` for environment control.
+6.  **Publication**: The project is already configured for publication on GitHub Pages.
+7.  **Documentation**: The project is already documented with a README file in all subfolders, reinforcing the TIER protocol 4.0 guidelines, and facilitating communication and understanding of the project. The TIER Protocol is highly structured and detailed, and intended to serve as a highly flexible framework that can be adapted to a wide variety of contexts. The high degree of detail serves a pedagogical purpose.
+
+## How to use this template?
+
+The structure of the folders and files is as follows:
+
+-   **project/:** main folder of the project where the narrative, data, scripts and output of analysis files are located. See README inside subfolders.
+
+-   **docs/**: folder for publishing an HTML website. The `docs` folder is commonly used to store the static files of a website, such as HTML, CSS, and JavaScript files. When you want to publish a website in GitHub Pages, you would place all your website’s files into this `docs` folder. It’s default directory that GitHub Pages uses to host websites from a repository, which will be updated when you render your document (Quarto book) in RStudio.
+
+-   **renv/**: `renv` folder that the `renv` package in R creates when you enable environment control. When you initialize `renv` in your project, it creates a new `renv` folder. This folder is crucial for encapsulating the state of your project. By using the `renv` folder, you can ensure that your project is self-contained and reproducible. Anyone else who works on your project will be able to recreate the exact same R environment you used, simply by restoring the project using the `renv.lock` file.
+
+- **adm/**: folder for administrative files, such contain sensitive and confidential data, temporary and work-related documents, backup repository for work in progress, administrative materials related to project management, etc. This folder is not versioned and is not published on GitHub Pages. There is an `.gitignore` file in the root of the project that prevents the `adm` folder from being versioned.
+
+- **all others files**: are the configuration files for the project, from the `.gitignore`, `renv` to the `.Rprofile` file.
 
 Clone this repository to your local PC and change the structure of the \_quarto.yml file as you wish. Maybe ligth and dark [themes](https://quarto.org/docs/output-formats/html-themes.html).
 

adm/README.md

@@ -0,0 +1,13 @@
+The creation of an `adm` (Administration) folder in your research project, which will be excluded from Git version control, is essential for several reasons. This folder is designated to contain sensitive and confidential data, such as personal details of research participants, financial information, contracts, and confidentiality agreements. These documents must be kept private and not shared publicly or with the broader research community.
+
+Additionally, the `adm` folder will house temporary and work-related documents, including notes, drafts, task lists, and meeting notes. These are frequently updated and not pertinent to the main code repository, ensuring that only the most relevant information is tracked and versioned.
+
+Files that are specific to the local work environment will also be stored in the `adm` folder. These might include local software configurations, API keys, and credentials. Such files are not necessary for other collaborators to replicate the project and are better kept out of the version control system to prevent accidental exposure.
+
+The `adm` folder serves as a backup repository for work in progress, allowing you to store interim versions and backups without cluttering the Git history with unnecessary commits. This practice keeps the main repository clean and focused on significant updates and changes.
+
+Moreover, the folder includes administrative materials related to project management, such as schedules, budgets, and resource planning documents. These are crucial for the internal administration of the project but do not need to be part of the version-controlled codebase.
+
+Lastly, by ignoring the `adm` folder in Git, you maintain a clean and organized repository. This approach ensures that only files and code directly relevant to the development and replication of the research are tracked, thus preserving the integrity and clarity of the commit history.
+
+In summary, the `adm` folder could be a vital part of the project setup, providing a secure and organized space for sensitive data, temporary documents, local-specific files, work in progress, and administrative materials, all while keeping the Git repository clean and focused on what truly matters for the research.

docs/index.html

@@ -7,7 +7,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
 
 <meta name="author" content="Your name">
-<meta name="dcterms.date" content="2024-01-01">
+<meta name="dcterms.date" content="2024-07-15">
 
 <title>Your title</title>
 <style>
@@ -202,7 +202,7 @@ <h1 class="title display-7">Your title</h1>
 <p class="subtitle lead">Your subtitle</p>
 <p class="author">Your name</p>
 
-<p class="date">January 1, 2024</p>
+<p class="date">July 15, 2024</p>
 </header>
 
 

docs/sitemap.xml

@@ -2,34 +2,34 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://phdpablo.github.io/article-template/index.html</loc>
-    <lastmod>2024-01-01T22:48:45.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.175Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/01-intro.html</loc>
-    <lastmod>2023-12-29T18:48:58.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.172Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/02-background.html</loc>
-    <lastmod>2023-12-29T18:47:42.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.172Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/03-methods.html</loc>
-    <lastmod>2023-12-29T18:48:04.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.173Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/04-results.html</loc>
-    <lastmod>2023-12-29T18:48:16.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.173Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/05-considerations.html</loc>
-    <lastmod>2023-12-29T18:03:14.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.173Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/references.html</loc>
-    <lastmod>2023-12-29T18:03:14.000Z</lastmod>
+    <lastmod>2024-07-15T17:07:59.175Z</lastmod>
   </url>
   <url>
     <loc>https://phdpablo.github.io/article-template/Your-title.pdf</loc>
-    <lastmod>2024-07-15T16:58:08.785Z</lastmod>
+    <lastmod>2024-07-15T17:35:58.209Z</lastmod>
   </url>
 </urlset>

project/Data/AnalysisData/README.md

@@ -0,0 +1,3 @@
+The AnalysisData folder should include
+
+* One or more analysis data files (possible organized in subfolders) and the Data Appendix (DataAppendix.pdf)

project/Data/InputData/Metadata/README.md

@@ -0,0 +1,3 @@
+The Metadata folder should include
+
+* A guide to data sources (DataSources.pdf) and codebooks for input data (if available)

project/Data/InputData/README.md

@@ -0,0 +1,3 @@
+The InputData folder should include
+
+* One or more input data files (possibly organized in subfolders)

project/Data/IntermediateData/README.md

@@ -0,0 +1,3 @@
+The IntermediateData folder should include
+
+* One or more intermediate data files (possibly organized in subfolders)

project/Output/DataAppendixOutput/README.md

@@ -0,0 +1,10 @@
+The DataAppendixOutput folder should include
+
+* All your Data Appendix Output Files should be stored in the DataAppendixOutput/ folder.
+
+* Data Appendix Output Files can be stored in a wide variety of formats, depending partly on the nature of the output that is saved in the file. For example:
+
+* If the output is a table, it could be exported to a file saved as plain text (.txt), comma separated values (.csv) , or an Excel workbook (.xlsx).
+If the output is a figure, it could be saved as .png, .jpg, or any of a large number of alternative formats for graphics files.
+Many types of output can also be saved as .pdf, .html, and .docx.
+In some cases, it may be convenient to preserve output in log files.

project/Output/README.md

@@ -0,0 +1,3 @@
+The Output folder should include
+
+* Log files, graphics files, text files, etc., that capture results generated by the analysis scripts (typically organized in subfolders)

project/Output/Results/README.md

@@ -0,0 +1,10 @@
+The Results folder should include
+
+* All your results files should be stored in the Results/ folder. If your Results Files can be organized into distinct categories, it might be useful to create subfolders of the Results/ folder for the different categories.
+
+* Results Files can be stored in a wide variety of formats. For example:
+
+* If the Result is a table, it could be exported to a file saved as plain text (.txt), comma separated values (.csv) , or an Excel workbook (.xlsx).
+If the Result is a figure, it could be saved as .png, .jpg, or any of a large number of alternative formats for graphics files.
+Many types of output can also be saved as .pdf, .html, and .docx.
+In some cases, it may be convenient to preserve Results in log files.

project/README.md

@@ -0,0 +1,25 @@
+This is main folder where the primary research documentation is located. Following the [TIER Protocol 4.0](https://www.projecttier.org/tier-protocol/protocol-4-0/root/) this is the folder that contains the research project documents:
+
+**Article**: divided into `.qmd` files, each representing a section of the article's narrative. In this case:
+
+-   `index.qmd`: Article metadata like title, subtitle, abstract, keywords, authors, etc. Do not change the file name as we need to generate the `index.html` file as the main page of the article website.
+
+-   `01-intro.qmd`, `02-background.qmd`, `03-methods.qmd`, `04-results.qmd`, and `05-considerations.qmd` are the traditional sections of a scientific article. Put your narrative inside this files on RStudio/Quarto.
+
+-   `references.qmd`: There is no need to edit this file. It is fed by the `reference.bib` file as you insert citations using Zotero, or a Better BibliTex key, for example.
+
+-   When rendering the document, a PDF file with all sections, that is, the complete article will be generated in the `../docs` folder
+
+**Data/**: Contains various versions of the data used in your project.
+
+**Scripts/**: Contains scripts that execute the data processing and analysis that generate the results of your project.
+
+-   Remember, the dynamic document is used only to report the analysis results. Following this approach, all the analysis steps are defined and managed outside of the dynamic document.
+
+-   Therefore, you must show all the steps to get to where you are in the scripts, although in the body of the article you only document what you consider relevant. Check out how to include the output of an another [Quarto document](https://quarto.org/docs/authoring/notebook-embed.html) to avoid code redundancy.
+
+**Output/**: Contains files that capture figures, tables, and other results generated by your scripts or external sources.
+
+-   Some output are compiled into separate files and found in the `../docs` folder, others are not compiled and it may be interesting to document them all in one place. Even if the outputs are on the article's website (dynamic document), it may be relevant to archive copies with higher resolution quality, for example, or even outputs from external sources.
+
+We following [PascalCase](https://en.wikipedia.org/wiki/Camel_case) convention to encode a name for the project subfolders.

project/Scripts/AnalysisScripts/README.md

@@ -0,0 +1,3 @@
+The AnalysisScripts folder should include
+
+* One or more scripts that conduct the analysis that generates the results that appear in the report

project/Scripts/DataAppendixScripts/README.md

@@ -0,0 +1,3 @@
+The DataAppendixSxripts folder should include
+
+* One or more scripts that generate the descriptive statistics, figures, and tables that appear in the Data Appendix (DataAppendix.pdf)

project/Scripts/ProcessingScripts/README.md

@@ -0,0 +1,3 @@
+The ProcessingScripts folder should include
+
+* One or more scripts that transform the input data files into the analysis data files

project/Scripts/README.md

@@ -0,0 +1,10 @@
+The Scripts folder should include
+
+* ProcessingScripts/: The commands in these scripts transform your Input Data Files into your Analysis Data Files.
+
+* DataAppendixScripts/: The commands in theses scripts produce the figures, tables, and descriptive statistics you present in your Data Appendix.
+
+* AnalysisScripts/: The commands in these scripts generate the results you present in the Report you write for your project.
+Document
+
+* The Master Script: A single script that reproduces the Results of your project by executing all the other scripts, in the correct order.

project/Your-title.tex

@@ -236,7 +236,7 @@
 \makeatother
 \subtitle{Your subtitle}
 \author{Your name}
-\date{January 1, 2024}
+\date{July 15, 2024}
 
 \begin{document}
 \maketitle