29  Quarto biçimleri

29.1 Giriş

Şimdiye kadar Quarto’nun HTML belgeleri üretmek için kullanıldığını gördünüz. Bu bölüm, Quarto ile üretebileceğiniz diğer pek çok çıktı türünden bazılarına kısa bir genel bakış sunar.

Bir belgenin çıktısını belirlemenin iki yolu vardır:

  1. YAML üst bilgisini değiştirerek kalıcı biçimde:

    title: "Elmas boyutları"
format: html

  2. quarto::quarto_render() fonksiyonunu elle çağırarak geçici biçimde:

    quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

    output_format argümanı bir değer listesi de alabildiği için program aracılığıyla birden çok çıktı türü üretmek istediğinizde bu yöntem kullanışlıdır.

    quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

29.2 Çıktı seçenekleri

Quarto çok çeşitli çıktı biçimleri sunar. Tam listeyi https://quarto.org/docs/output-formats/all-formats.html adresinde bulabilirsiniz. Pek çok biçim bazı çıktı seçeneklerini paylaşır (ör. içindekiler tablosu eklemek için toc: true), bazı seçenekler ise belirli bir biçime özgüdür (ör. code-fold: true, HTML çıktısında kod bloklarını bir <details> etiketi içinde daraltarak kullanıcının istediğinde görüntülemesini sağlar; PDF veya Word belgesinde geçerli değildir).

Varsayılan seçenekleri geçersiz kılmak için genişletilmiş bir format alanı kullanmanız gerekir. Örneğin yüzen bir içindekiler tablosuna sahip html çıktısı işlemek isterseniz şunu kullanırsınız:

format:
  html:
    toc: true
    toc_float: true

Bir biçim listesi sağlayarak aynı anda birden çok çıktı bile işleyebilirsiniz:

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

Varsayılan seçeneklerin hiçbirini geçersiz kılmak istemediğinizde kullanılan özel söz dizimine (pdf: default) dikkat edin.

Bir belgenin YAML’ında belirtilen tüm biçimleri işlemek için output_format = "all" kullanabilirsiniz.

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

29.3 Belgeler

Önceki bölüm varsayılan html çıktısına odaklandı. Farklı belge türleri üreten birkaç temel alternatif vardır. Örneğin:

  • pdf, yüklemeniz gereken açık kaynaklı bir belge düzeni sistemi olan LaTeX ile PDF oluşturur. LaTeX henüz yüklü değilse RStudio sizi yönlendirir.

  • Microsoft Word (.docx) belgeleri için docx.

  • OpenDocument Text (.odt) belgeleri için odt.

  • Rich Text Format (.rtf) belgeleri için rtf.

  • GitHub Flavored Markdown (.md) belgesi için gfm.

  • Jupyter Notebooks (.ipynb) için ipynb.

Karar vericilerle paylaşılacak bir belge üretirken belge YAML’ında genel seçenekleri ayarlayarak kodun varsayılan olarak görüntülenmesini kapatabileceğinizi unutmayın:

execute:
  echo: false

html belgeleri için bir başka seçenek, kod bloklarını varsayılan olarak gizlemek ancak tıklandığında görünür kılmaktır:

format:
  html:
    code: true

29.4 Sunumlar

Quarto’yu sunum üretmek için de kullanabilirsiniz. Keynote veya PowerPoint gibi araçlara kıyasla görsel denetiminiz daha azdır; ancak R kodunuzun sonuçlarını sunuma otomatik olarak eklemek çok zaman kazandırabilir. Sunumlar, içeriğinizi slaytlara bölerek çalışır; ikinci düzey (##) her başlıkta yeni bir slayt başlar. Ayrıca birinci düzey (#) başlıklar, başlığı varsayılan olarak ortalanmış bir bölüm başlığı slaydıyla yeni bir bölümün başlangıcını belirtir.

Quarto, aralarında aşağıdakilerin de bulunduğu çeşitli sunum biçimlerini destekler:

  1. revealjs — revealjs ile HTML sunumu

  2. pptx — PowerPoint sunumu

  3. beamer — LaTeX Beamer ile PDF sunumu.

Quarto ile sunum oluşturma hakkında daha fazla bilgiyi https://quarto.org/docs/presentations adresinde bulabilirsiniz.

29.5 Etkileşim

Diğer tüm HTML belgeleri gibi Quarto ile oluşturulan HTML belgeleri de etkileşimli bileşenler içerebilir. Burada Quarto belgelerinize etkileşim eklemek için iki seçeneği tanıtacağız: htmlwidgets ve Shiny.

29.5.1 htmlwidgets

HTML etkileşimli bir biçimdir ve etkileşimli HTML görselleştirmeleri üreten R fonksiyonları olan htmlwidgets ile bu etkileşimden yararlanabilirsiniz. Örneğin aşağıdaki leaflet haritasına bakın. Bu sayfayı web’de görüntülüyorsanız haritayı sürükleyebilir, yakınlaştırıp uzaklaştırabilir ve benzeri işlemler yapabilirsiniz. Bunları bir kitapta yapamayacağınız açıktır; bu nedenle Quarto sizin için otomatik olarak sabit bir ekran görüntüsü ekler.

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |> 
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

htmlwidgets’ın en güzel yanı, bunları kullanmak için HTML veya JavaScript hakkında hiçbir şey bilmenizin gerekmemesidir. Tüm ayrıntılar paketin içine alınmıştır; dolayısıyla bunlarla ilgilenmeniz gerekmez.

htmlwidgets sağlayan pek çok paket vardır; bunlardan bazıları şunlardır:

  • Etkileşimli zaman serisi görselleştirmeleri için dygraphs.

  • Etkileşimli tablolar için DT.

  • Etkileşimli 3B grafikler için threejs.

  • Diyagramlar (akış şemaları ve basit düğüm-bağlantı diyagramları gibi) için DiagrammeR.

htmlwidgets hakkında daha fazla bilgi edinmek ve bunları sağlayan paketlerin tam listesini görmek için https://www.htmlwidgets.org adresini ziyaret edin.

29.5.2 Shiny

htmlwidgets istemci taraflı etkileşim sağlar; tüm etkileşim R’den bağımsız olarak tarayıcıda gerçekleşir. Bir bakıma bu harikadır çünkü HTML dosyasını R bağlantısı olmadan dağıtabilirsiniz. Ancak bu durum yapabileceklerinizi temelde HTML ve JavaScript ile uygulanmış özelliklerle sınırlar. Alternatif bir yaklaşım, JavaScript yerine R koduyla etkileşim oluşturmanıza olanak tanıyan shiny paketini kullanmaktır.

Bir Quarto belgesinden Shiny kodu çağırmak için YAML üst bilgisine server: shiny ekleyin:

title: "Shiny Web Uygulaması"
format: html
server: shiny

Ardından belgeye etkileşimli bileşenler eklemek için “input” fonksiyonlarını kullanabilirsiniz:

library(shiny)

textInput("name", "Adınız nedir?")
numericInput("age", "Kaç yaşındasınız?", NA, min = 0, max = 150)

Üst üste iki giriş kutusu. Üsttekinde "Adınız nedir?", alttakinde "Kaç yaşındasınız?" yazıyor.

Shiny sunucusunda çalışması gereken kodu içeren ve context: server blok seçeneğine sahip bir kod bloğuna da ihtiyacınız vardır.

Ardından değerlere input$name ve input$age ile başvurabilirsiniz; bu değerleri kullanan kod, değerler her değiştiğinde otomatik olarak yeniden çalıştırılır.

Shiny etkileşimleri sunucu tarafında gerçekleştiği için burada çalışan bir Shiny uygulaması gösteremiyoruz. Bu, JavaScript bilmeden etkileşimli uygulamalar yazabileceğiniz ancak bunları çalıştıracak bir sunucuya ihtiyaç duyacağınız anlamına gelir. Bu durum lojistik bir sorun doğurur: Shiny uygulamalarının çevrimiçi çalışması için bir Shiny sunucusu gerekir. Shiny uygulamalarını kendi bilgisayarınızda çalıştırdığınızda Shiny sizin için otomatik olarak bir Shiny sunucusu kurar; ancak bu tür bir etkileşimi çevrimiçi yayımlamak istiyorsanız herkesin erişebileceği bir Shiny sunucusuna ihtiyacınız vardır. Shiny’ın temel ödünleşimi budur: Bir Shiny belgesinde R’de yapabildiğiniz her şeyi yapabilirsiniz ancak birinin R’yi çalıştırıyor olması gerekir.

Shiny hakkında daha fazla bilgi edinmek için Hadley Wickham’ın Mastering Shiny kitabını okumanızı öneririz: https://mastering-shiny.org.

29.6 Web siteleri ve kitaplar

Biraz ek altyapıyla Quarto’yu eksiksiz bir web sitesi veya kitap oluşturmak için kullanabilirsiniz:

  • .qmd dosyalarınızı tek bir dizine koyun. index.qmd ana sayfa olur.

  • Site içinde gezinmeyi tanımlayan _quarto.yml adlı bir YAML dosyası ekleyin. Bu dosyada project türünü book veya website olarak ayarlayın. Örneğin:

    project:
  type: book

Örneğin aşağıdaki _quarto.yml dosyası üç kaynak dosyadan bir web sitesi oluşturur: index.qmd (ana sayfa), viridis-colors.qmd ve terrain-colors.qmd.

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

Bir kitap için gereken _quarto.yml dosyası da çok benzer bir yapıya sahiptir. Aşağıdaki örnek, üç farklı çıktıya (html, pdf ve epub) işlenen dört bölümlük bir kitabı nasıl oluşturabileceğinizi gösterir. Burada da kaynak dosyalar .qmd dosyalarıdır.

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

Web siteleriniz ve kitaplarınız için bir RStudio projesi kullanmanızı öneririz. RStudio, _quarto.yml dosyasına dayanarak üzerinde çalıştığınız projenin türünü tanır ve IDE’ye web sitelerinizi ve kitaplarınızı işleyip önizlemek için kullanabileceğiniz bir Build sekmesi ekler. Hem web siteleri hem de kitaplar quarto::quarto_render() kullanılarak da işlenebilir.

Quarto web siteleri hakkında https://quarto.org/docs/websites, kitaplar hakkında ise https://quarto.org/docs/books adresinde daha fazla bilgi bulabilirsiniz.

29.7 Diğer biçimler

Quarto daha da fazla çıktı biçimi sunar:

Daha fazla biçimin listesi için https://quarto.org/docs/output-formats/all-formats.html adresine bakın.

29.8 Özet

Bu bölümde sonuçlarınızı Quarto ile paylaşmak için sabit ve etkileşimli belgelerden sunumlara, web sitelerine ve kitaplara uzanan çeşitli seçenekler sunduk.

Bu farklı biçimlerde etkili iletişim kurma hakkında daha fazla bilgi edinmek için aşağıdaki kaynakları öneririz: