یک فرهنگ لغت داده رایگان با R ایجاد کنید

آیا مجموعه داده ها در همه جا پراکنده شده اند؟ در اینجا نحوه قرار دادن آنها در یک کاتالوگ منفرد و قوی با بسته نقطه خالی R و یک سند Quarto آورده شده است.

• یک گزارش فرهنگ لغت داده با R و pointblank ایجاد کنید
• گزارش خود را براساس لایه‌ها ایجاد کنید
• مقادیر محاسبه شده را به گزارش خود اضافه کنید
• مجموعه‌های داده پویاتر
• ایجاد کاتالوگ فرهنگ لغت داده واحد
• فرهنگ داده‌های خود را در وب منتشر کنید

آیا مجموعه داده‌هایی دارید که در همه جا پراکنده شده‌اند: چندین پوشه محلی، مخازن Git، سرویس‌های ابری، پایگاه‌های داده؟ آیا گاهی اوقات سخت است که به خاطر بسپارید کدام مجموعه داده حاوی چه چیزی است و همه آنها در کجا ذخیره شده اند؟

با تشکر از پکیج pointblank R، می‌توانید مجموعه داده‌های خود را از طریق اسکریپت‌های R در گزارشی مستند کنید که نه تنها انواع ستون‌ها و منشأ داده‌ها را توصیف می‌کند، بلکه شامل محل ذخیره مجموعه داده‌ها، نحوه به‌روزرسانی، اگر پروژه‌های کلیدی از آن استفاده می‌کنند و هر چیز دیگری را نیز شامل می‌شود. دیگری که می خواهید اضافه کنید از آنجایی که هر گزارش فرهنگ لغت داده توسط یک اسکریپت R تولید می‌شود، می‌توانید فیلدهای فراداده‌ای را که برایتان مهم هستند، اضافه کنید، سپس از همان ساختار برای هر مجموعه داده استفاده کنید.

هنگامی که گزارش‌ها را ایجاد کردید، می‌توانید اسکریپت دیگری را در یک فایل Quarto یا R Markdown بنویسید تا همه آن فایل‌ها را به فهرست فرهنگ لغت داده‌ای قابل جستجو اضافه کنید—بدون توجه به اینکه هر مجموعه داده کجاست. ذخیره شده است.

در اینجا نحوه کار همه اینها آمده است.

یک گزارش فرهنگ لغت داده با R و pointblank ایجاد کنید

برای مستندسازی یک مجموعه داده با pointblank در R، با ایجاد یک شی pointblank informant با تابع create_informant() شروع می‌کنید.< /p>

بیایید از یک مجموعه داده ساده از داده های جمعیت ایالت ایالات متحده استفاده کنیم تا آن را در عمل ببینیم.

کد موجود در فهرست ۱ بسته‌های pointblank و dplyr را بارگیری می‌کند و از بسته rio برای خواندن فایل در R استفاده می‌کند. از هر تابع وارداتی که دوست دارید برای وارد کردن فایل‌های CSV استفاده کنید—readr::read_csv()، vroom::vroom()، data.table::fread( )، read.csv() پایه R، و غیره

library(pointblank) # install with install.packages if needed
library(rio)
library(dplyr)
state_pops <- import("https://raw.githubusercontent.com/smach/SampleData/main/states.csv")

این خط بعدی کد یک اطلاع دهنده پایه و بدون محدودیت ایجاد می کند. create_informant() یک چارچوب داده یا چندین نوع جداول پایگاه داده را به عنوان اولین آرگومان اجباری خود می گیرد:

my_informant <- create_informant(state_pops)

شیء اطلاع دهنده مجهز به روش چاپ نسبتاً خوبی است که می توانید با اجرای print(my_informant) یا به سادگی my_informant آن را مشاهده کنید. در کنسول R شما.

شما باید چیزی شبیه آنچه در شکل ۱ نشان داده شده است ببینید.

شکل ۱. یک گزارش داده نقطه خالی مطلق.

افزودن آرگومان‌های مخبر اختیاری

تا کنون، این اطلاعات بیشتر از پایه R به شما اطلاعاتی در مورد قاب داده شما نداده است. قالب بنابراین، بیایید شروع به اضافه کردن اطلاعات کنیم.

create_informant() می‌تواند چند آرگومان اختیاری برای ابرداده بگیرد، از جمله tbl_name، label و lang . آرگومان lang زبان مورد استفاده برای متن جدول خلاصه را نشان می دهد – به طور پیش فرض انگلیسی است اما شامل گزینه هایی برای اسپانیایی، چینی، آلمانی، فرانسوی، پرتغالی و چندین گزینه دیگر است. برای مثال، create_informant(states, lang = "es") را امتحان کنید تا ببینید مثلاً گزارشی به زبان اسپانیایی چگونه است.

من معمولاً از آرگومان tbl_name برای نام فایلی که مجموعه داده‌ها را در آن ذخیره می‌کنم استفاده می‌کنم. من فلسفه ای برای برچسب ندارم که با چاپ ریز زیر عنوان ظاهر می شود. در اینجا یک مثال ساده آورده شده است:

my_informant <- create_informant(state_pops, 
                  tbl_name = "states.csv", label = "US Census data")
my_informant

شکل ۲ اطلاع دهنده را با tbl_name و label اضافه شده نشان می دهد.

شکل ۲. یک خبرچین با نام و برچسب جدول اضافه شده است.

tbl_name و برچسب اکنون زیر عنوان هستند.

گزارش خود را بر اساس لایه ها ایجاد کنید

تا حدودی مانند یک گرافیک ggplot2، می توانید اطلاع دهنده اصلی را با لایه های اضافی تقویت و سفارشی کنید. اما به‌جای افزودن توابع geom_ و theme_ به ggplot2، می‌توانید از خانواده‌ای از توابع pointblank info_ استفاده کنید. من اغلب از این سه استفاده می کنم:

• info_tabular() ابرداده‌های مفیدی را در بالای گزارش فرهنگ لغت داده اضافه می‌کند – مواردی مانند شرح مجموعه داده‌ها، اطلاعات نحوه به‌روزرسانی آن، و اگر فرهنگ لغت شما بیش از یک پلتفرم را پوشش دهد، کجا ذخیره می‌شود. . شما می توانید این را هر طور که می خواهید سفارشی کنید.
• info_columns() به شما امکان می دهد توضیحات متنی را به ستون های داده به همراه نام ستون و نوع داده که به طور پیش فرض ظاهر می شوند اضافه کنید. این توصیف می تواند متن ایستا باشد، مانند “منطقه اداره سرشماری ایالات متحده”. یا می‌تواند شامل مقادیر تولید شده به صورت پویا از مجموعه داده‌ها باشد، مانند “تاریخ‌های روزانه از {starting_date} تا {ending_date}.”
• برای گنجاندن مقادیر پویا، از تابع info_snippet() استفاده می‌کنید تا آنچه را pointblank فراخوانی می‌کند (نباید با قطعه کد RStudio اشتباه گرفته شود). ما کمی به info_snippet() نگاهی خواهیم انداخت.

اما اکنون، با افزودن فراداده‌های بیشتر به بالای گزارش خود با info_tabular() شروع می‌کنم. من انتخاب کرده ام که فیلدهای شرح، به روز رسانی، منبع، ذخیره شده و استفاده شده توسط ، اما می توانید هر فیلدی را که می خواهید در اینجا اضافه کنید.

my_informant <- my_informant %>%
  info_tabular(
    Description = "Table of US state populations from decennial censuses, with data from 2000, 2010, and 2020 as well as columns for percent changes and Census Bureau regions and divisions.",
    Updates = "Does not update (except once every 10 years)",
    Source = "US Census Bureau and the R tidycensus package",
    Stored = "[Sample Data GitHub repository](https://github.com/smach/SampleData)",
    `Used by` = "Do More with R"
  )
  

من پیشنهاد می‌کنم با فیلدهای info_tabular() که می‌خواهید در فرهنگ لغت داده خود، یک فایل الگو را کپی و پر کنید، یا یک قطعه کد RStudio ایجاد کنید. به این ترتیب، می توانید ابرداده خود را استاندارد کنید.

بسیاری از آرگومان‌های pointblank از نحو Markdown مانند [text to hyperlink](https://url.com) استفاده می‌کنند. به عنوان مثال، ذخیره شده در فهرست ۲ یک ابرپیوند به مخزن من ایجاد می کند.

اگر قطعه کد info_tabular() بالا یا چیزی مشابه را اجرا کنید و اطلاع دهنده را چاپ کنید، باید خروجی مشابه آنچه در شکل ۳ در بالای صفحه نشان داده شده است ببینید. گزارش شما.

جزئیات ستون را اضافه کنید

در مرحله بعد، جزئیات مربوط به ستون های مجموعه داده را اضافه می کنم. من همیشه هر ستون را در یک مجموعه داده توصیف نمی‌کنم وقتی نام ستون‌ها واضح به نظر می‌رسند، اگرچه مسلماً این بهترین عمل نیست. برای مثال، «Pop_2020» در مجموعه داده‌ای از اطلاعات جمعیت سرشماری کاملاً توضیحی به نظر می‌رسد.

شما می‌توانید به تعداد ستون‌هایی که می‌خواهید در یک اطلاع‌دهنده توصیف کنید. این جزئیات مورد نیاز نیست.

برای افزودن یک توضیح متن ایستا به یک ستون، از تابع info_columns() استفاده می‌کنید که دستور زیر را دارد:

  my_informant <- my_informant %>%
    info_columns(
      columns = "column_name",
      info = "My description of the column"
  )

هر توضیح info_columns() لایه جدیدی است که از طریق %>% یا |>اطلاع دهنده اضافه شده است. کد> لوله. به عنوان مثال، این توضیحات

   my_informant <- my_informant %>%
    info_columns(
      columns = "State",
      info = "Full text name of the state such as Hawaii or Alaska."
  )  %>%
  info_columns(
    columns = "State Code",
    info = "Two-letter state abbreviation such as HI or AK."
  )
  

نتیجه با اضافه کردن موارد زیر به بخش ستون‌های اطلاع دهنده، نشان داده شده در شکل ۴ می‌شود.

شکل ۴. مخبر نقطه خالی با اطلاعات ستون اضافه شده است.

می‌توانید شرح یکسانی را به چندین ستون اضافه کنید، مانند:

my_informant <- my_informant %>%
  info_columns(
    columns = c("PctChange_2000", "PctChange_2010", "PctChange_2020"),
    info = c("Percent population change from prior decennial census. Format already multiplies the decimal by 100, so, for example, a 10.1% change is represented as the number 10.1.")
  )

قطعه زیر، توضیحات متنی یکسانی را به هر سه ستون PctChange اضافه می‌کند.

آگومان columns همچنین می‌تواند از کمک‌های انتخاب dplyr “tidy select” مانند starts_with() استفاده کند، در این صورت می‌توانید موارد بالا را بازنویسی کنید. به عنوان

my_informant <- my_informant %>%
  info_columns(
    columns = starts_with("PctChange"),
    info = "Percent population change from prior decennial census. Format already multiplies the decimal by 100, so, for example, a 10.1% change is represented as the number 10.1."
  )

سایر راهنماهای انتخاب ستون موجود عبارتند از: ends_with()، contains()، match() برای مطابقت با یک عبارت معمولی، و همه چیز () برای همه ستون ها.

می‌توانید بیش از یک توصیف info_columns() به یک ستون اضافه کنید. این بدان معناست که شما می‌توانید متن boilerplate برای چندین ستون مانند بالا و متن خاص فقط برای یکی از آن ستون‌ها داشته باشید، مانند مثال زیر برای ستون PctChange_2020:

my_informant <- my_informant %>%
  info_columns(
    columns = "PctChange_2020",
    info = " This column shows the percent change from the 2020 Census compared with 2010."
  )
  

اجرای هر دو قطعه کد info_columns() موارد زیر را برای ستون های درصد تغییر ایجاد می کند. هر سه ستون دارای متن توضیحی یکسانی هستند، اما PctChange_2020 دارای متن اضافی اضافه شده است:

شکل ۵. نتیجه اجرای info_columns() روی سه ستون و دومین info_columns() روی یکی از آنها

مقادیر محاسبه شده را به گزارش خود اضافه کنید

ممکن است برای شما مفید باشد که مقادیر محاسبه شده را به توضیحات مجموعه داده های خود اضافه کنید. به عنوان مثال، تمام مقادیر ممکن منطقه و بخش اداره سرشماری چیست؟ بیشترین و کمترین درصد تغییرات در مجموعه داده Pop_2020 چه بوده است؟

شما می توانید آن ها را به صورت دستی به متن ثابت اضافه کنید. اما علاوه بر بی‌حجم بودن، ممکن است برای مقادیر مجموعه داده‌ای که اغلب به‌روزرسانی می‌شوند، به خوبی کار نکند. در عوض، می‌توانید از قطعه‌های pointblank برای اضافه کردن محاسبات از داده‌های خود به توضیحات اطلاع‌دهنده استفاده کنید. این یک مثال است:

my_informant <- my_informant %>%
  info_snippet(
    snippet_name = "name_of_my_snippet",
    fn = ~ R CODE GOES HERE 
  )
  

info_snippet() یک مقدار محاسبه شده را در name_of_my_snippet ذخیره می کند. سپس می‌توانید از آن مقدار قطعه در داخل آرگومان info_column() info با قرار دادن نام قطعه در پرانتز استفاده کنید. دیدن آن در کد آسان تر از توضیح دادن آن است:

my_informant <- my_informant %>%
  info_columns(
    columns = "the_column_name",
    info = "Info about the column and {name_of_my_snippet} interesting data value"
  )
  

نحو کد R برای محاسبات قطعه به طور کلی چیزی شبیه به این است:

fn = ~ . %>% .$column_name %>% more R code here

~ می گوید، “این فرمولی است که در حال حاضر ارزیابی نمی شود.” . مجموعه داده ای را نشان می دهد که توسط اطلاع دهنده استفاده می شود.

برای اجرا قطعه‌ها به گونه‌ای که مقادیر محاسبه شوند، باید تابع incorporate() pointblank را در یک اطلاع‌دهنده فراخوانی کنید. . به عنوان مثال، برای به دست آوردن مقدار میانه برای ستون Pop_2020 مجموعه داده‌ام، می‌توانم کد موجود در فهرست ۳ را به اطلاع دهنده خود اضافه کنم:

my_informant <- my_informant %>%
  info_snippet(
    snippet_name = "median_2020",
    fn = ~ . %>% .$Pop_2020 %>% median()
  ) %>%
  info_columns(
    columns = "Pop_2020",
    info = "State population from the 2020 Census. Median value is {median_2020}"
  )

# View results:
my_informant %>%
  incorporate()
  

در بالا من یک قطعه به نام median_2020 ایجاد کردم و سپس از آن مقدار با قرار دادن نام آن در پرانتز هنگام افزودن توضیحات به یک ستون استفاده کردم.

متأسفانه، تا آنجا که من می دانم، هیچ راهی برای استفاده از یک فراخوانی تابع info_snippet() روی چندین ستون به طور همزمان وجود ندارد. بنابراین اگر مقادیر میانه را برای چندین ستون می خواستید، باید چندین info_snippet

ایجاد کنید.

از آنجایی که قطعه‌ها تا زمان اجرای incorporate() محاسبه نمی‌شوند، ترتیب لایه‌های اطلاع‌دهنده مهم نیست. info_columns() با استفاده از یک قطعه می‌تواند قبل از کد info_snippet()  باشد که قطعه را ایجاد می‌کند. بنابراین، این نیز کار می کند:

my_informant <- my_informant %>%
  info_columns(
    columns = "Pop_2020",
    info = "State population from the 2020 Census. Median value is {median_2020}"
  ) %>%
  info_snippet(
    snippet_name = "median_2020",
    fn = ~ . %>% .$Pop_2020 %>% median()
  )
  

این کد این را برای اطلاعات Pop_2020 ایجاد می کند: “جمعیت ایالت از سرشماری ۲۰۲۰. مقدار متوسط ​​۴,۳۷۱,۵۴۶.۰۰ است.”

عملکردهای راحت قطعه داخلی

علاوه بر ایجاد کد R قطعه برای خود، چندین عملکرد راحت قطعه داخلی وجود دارد. من اغلب از سه مورد از آنها استفاده می کنم: snip_highest() برای حداکثر مقدار یک ستون، snip_lowest() برای حداقل مقدار، و snip_list() برای مقادیر منحصر به فرد یک ستون همچنین snip_stats() برای خلاصه آماری ستون وجود دارد. من اغلب از آن استفاده نمی کنم اما شما ممکن است.

برای استفاده از آنها، تابع راحتی را به آرگومان fn اضافه کنید. به عنوان مثال، برای افزودن همه مقادیر Division موجود به ستون Division مجموعه داده‌ام، می‌توانم از snip_list() استفاده کنم:

my_informant <- my_informant %>%
  info_snippet(
    "census_divisions",
    fn = snip_list("Division", limit = 10, sorting = "inseq")
  ) %>%
  info_columns(
    "Division",
    info = "Census Bureau divisions. Possible values: {census_divisions}"
  ) %>%
  incorporate()
  

شکل ۶ نگاهی جزئی به اطلاع دهنده به روز شده با تمام مقادیر ممکن در ستون Division است.

شکل ۶. توضیحات ستون برای خبرچین.

چند فرمان دیگر که ارزش دانستن دارد:

• snip_list() حداکثر پنج مقدار را به طور پیش فرض نمایش می دهد. بنابراین، اگر می‌خواهید همه مقادیر نمایش داده شوند و بیش از پنج عدد وجود دارد، آرگومان محدود جدیدی را همانطور که در بالا انجام دادم تنظیم کنید.

مرتب‌سازی

• snip_list() سه گزینه دارد: پیش‌فرض، که موارد ترتیب در مجموعه داده ظاهر می‌شوند. infreq، با کاهش فراوانی موارد. یا inseq که بر اساس حروف الفبا است.
• زمانی که ایجاد یک اطلاع دهنده را به پایان رساندید، می توانید آن را با get_informant_report() به یک گزارش HTML تبدیل کنید و با export_report در یک فایل HTML ذخیره کنید. ().
• get_informant_report() به شما امکان می دهد عنوان گزارش را تنظیم کنید. export_report() گزینه هایی برای نام فایل گزارش و مسیر دایرکتوری دارد، در صورت تمایل، مانند این مثال:

  
  myreport <- get_informant_report(my_informant,
              عنوان = "جمعیت ایالت ایالات متحده (اطلاعات سرشماری ده ساله)")
  export_report (myreport، نام فایل = "state_pops.html"، مسیر = "www")
  

myreport <- get_informant_report(my_informant, 
            title = "US State Populations (decennial census data)")
export_report(myreport, filename = "state_pops.html", path = "www")

مجموعه داده های پویاتر

این گزارش نمونه مجموعه داده‌ای را مستند می‌کند که به‌روزرسانی نمی‌شود، مگر شاید هر ۱۰ سال یک بار. برای مجموعه داده هایی که اغلب از طریق اسکریپت های R به روز می شوند، می توانید کد pointblank را به آن اسکریپت ها اضافه کنید تا در یک نگاه یک گزارش پویا با اطلاعات مفید و به روز ایجاد کنید.

به عنوان مثال، من فایل CSV دمای بوستون را به‌روزرسانی خودکار دارم. می توانم از مقادیر قطعه برای گنجاندن آخرین تاریخ در مجموعه داده استفاده کنم. مقادیر قطعه را می توان در قسمت بالای info_tabular() یک گزارش و همچنین در توضیحات ستون جداگانه استفاده کرد، بنابراین می توانم مقادیر قطعه را به قسمت توضیحات در بالای گزارش خود اضافه کنم. برای مثال، کد موجود در فهرست ۴ مجموعه داده‌های دمای روزانه من را دانلود می‌کند، یک اطلاع‌دهنده اولیه ایجاد می‌کند، و سپس قطعه‌هایی را برای start_date و end_date اضافه می‌کند:

bos_temps <- rio::import("https://raw.githubusercontent.com/smach/SampleData/main/BOS_temperatures.csv")

temp_informant <- create_informant(bos_temps, tbl_name = "BOS_temperatures.csv", 
                  label = "Weather data") %>%
  info_tabular(
    Description = "Table of daily Boston high and low temperatures as well as min, max, 
       and average 'feels like' temps starting {start_date} through {end_date}. 
      _Not_ official National Weather Service data.",
    Updates = "Auto updates daily from script on my cloud server",
    Source = "[Iowa State University's Iowa Environmental Mesonet METAR database](https://mesonet.agron.iastate.edu/request/download.phtml?network=MA_ASOS)",
    Stored = "[Sample Data GitHub repository](https://github.com/smach/SampleData)",
    `Used by` = "Do More with R"
  ) %>%
  info_snippet(
    snippet_name = "start_date",
    fn = snip_lowest("day")
  ) %>%
  info_snippet(
    snippet_name = "end_date",
    fn = snip_highest("day")
  ) %>%
  incorporate()
  

در اینجا نمایی از بالای این مخبر است:

ایجاد کاتالوگ فرهنگ لغت داده واحد

تاکنون، ما هر بار یک مجموعه داده را مستند کرده ایم. بسته pointblank دارای عملکردهای داخلی برای ایجاد یک فهرست فرهنگ لغت داده از چندین گزارش مجموعه داده نیست. با این حال، می توانید خودتان یکی بسازید.

روش ترجیحی من در حال حاضر با یک سند R Markdown یا Quarto است که شامل کدی برای ایجاد یک جدول قابل جستجو از همه گزارش‌های pointblank من است. من یک اسکریپت جداگانه دارم که داده‌های جدول را از تمام فایل‌های گزارش HTML جمع‌آوری می‌کند و سپس آن‌ها را برای استفاده در سندی که جدول قابل جستجوی من را تولید می‌کند، ذخیره می‌کند. یکی از کلیدهای سازماندهی گزارش های من به این روش این است که مطمئن شوم یک کپی از هر گزارش را در یک مکان، صرف نظر از اینکه داده ها در کجا ذخیره می شوند دارم.

من با "خراش دادن" فایل HTML هر گزارش، داده هایی را برای جدول خود تولید می کنم. در زیر دو اسکریپت مورد استفاده من وجود دارد.

عملکرد extract_report_info()

اولین اسکریپت که در فهرست ۵ نشان داده شده است، تمام اطلاعات مورد نیاز من را از یک گزارش pointblank HTML استخراج می‌کند، جایی که report_file نام یک pointblank است. /code> فایل HTML و report_path پوشه گزارش است. کد از توابع بسته rvest برای استخراج اطلاعات متنی مختلف بر اساس انتخابگرهای HTML CSS استفاده می کند. می‌توانید در وب‌سایت بسته rvest اطلاعات بیشتری در مورد این موضوع بخوانید.

extract_report_info <- function(report_file, report_path = "www") {
  report_file <- paste0(report_path, "/", report_file)
  my_html <- read_html(report_file)
  Title <- html_element(my_html, ".gt_title") %>%
    html_text2()
  metadata <- html_elements(my_html, ".gt_from_md") %>%
    html_text2()
  Description <- get_table_metadata_fields("DESCRIPTION", metadata)
  Source <- get_table_metadata_fields("SOURCE", metadata)  
  Updates <- get_table_metadata_fields("UPDATES", metadata)
  UsedBy <- get_table_metadata_fields("USED BY", metadata)
  Columns <- html_elements(my_html, "code:nth-child(1)") %>%
    html_text2() %>%
    paste(. , collapse = ", ")
  
  Title = glue("<a title='{Title}' href='{report_file}'>{Title}</a>")
  report_info <- data.frame(Title = Title, Description = Description, Source = Source, Updates = Updates, UsedBy = UsedBy, Columns = Columns)
  return(report_info)
  
}

get_table_metadata_fields <- function(field, char_vector) {
  mytext <- char_vector[grepl(field, char_vector)]
  mytext <- gsub(field, "", mytext, fixed = TRUE)
  mytext <- gsub("\n", "", mytext, fixed = TRUE)
  return(mytext)
}

table_data <- purrr::map_df(dir("www"), extract_report_info) %>%
  arrange(Title)

---
title: "Sample Data Dictionary"
format: 
  html:
    page-layout: full
editor: source
---

```{r}
#| echo: false

table_data <- readRDS("data_dictionary_table_data.Rds")
library(DT)
datatable(table_data, escape = FALSE, filter = 'top', rownames = FALSE)

```

project:
  type: website
    output-dir: docs

quarto render
git add *
git commit -m "Updating data dictionary"
git push

system('quarto render')
system('git add *')
system('git commit -m "Updating data dictionary"')
system('git push')

system('quarto render')
system('cp -r www docs')
system('git add www/*')
system('git add docs/www/*')
system('git add *')
system('git commit -m "Updating data dictionary"')
system('git push')