create.experiment {ORFik} | R Documentation

## Create an ORFik `experiment`

### Description

Create a single R object that stores and controls all results relevant to a specific Next generation sequencing experiment. Click the experiment link above in the title if you are not sure what an ORFik experiment is.
By using files in a folder / folders. It will make an experiment table with information per sample, this object allows you to use the extensive API in ORFik that works on experiments.
Information Auto-detection:
There will be several columns you can fill in, when creating the object, if the files have logical names like (RNA-seq_WT_rep1.bam) it will try to auto-detect the most likely values for the columns. Like if it is RNA-seq or Ribo-seq, Wild type or mutant, is this replicate 1 or 2 etc.
You will have to fill in the details that were not auto detected. Easiest way to fill in the blanks are in a csv editor like libre Office or excel. You can also remake the experiment and specify the specific column manually. Remember that each row (sample) must have a unique combination of values. An extra column called "reverse" is made if there are paired data, like +/- strand wig files.

### Usage

    create.experiment(
      dir,
      exper,
      saveDir = "~/Bio_data/ORFik_experiments/",
      txdb = "",
      fa = "",
      organism = "",
      assembly = "",
      pairedEndBam = FALSE,
      viewTemplate = FALSE,
      types = c("bam", "bed", "wig", "ofst"),
      libtype = "auto",
      stage = "auto",
      rep = "auto",
      condition = "auto",
      fraction = "auto",
      author = ""
    )

### Arguments

`dir` | Which directory / directories to create experiment from, must be a directory with NGS data from your experiment. Will include all files of file type specified by "types" argument. So do not mix files from other experiments in the same folder!
`exper` | Short name of experiment. Will be name used to load experiment, and name shown when running `list.experiments`
`saveDir` | Directory to save experiment csv file, default: "~/Bio_data/ORFik_experiments/". Set to NULL if you don't want to save it to disc.
`txdb` | A path to TxDb (prefered) or gff/gtf (not adviced, slower) file with transcriptome annotation for the organism.
`fa` | A path to fasta genome/sequences used for libraries, remember the file must have a fasta index too.
`organism` | character, default: "" (no organism set), scientific name of organism. Homo sapiens, Danio rerio, Rattus norvegicus etc. If you have a SRA metadata csv file, you can set this argument to study$ScientificName[1], where study is the SRA metadata for all files that was aligned.
`assembly` | character, default: "" (no assembly set). The genome assembly name, like GRCh38 etc. Useful to add if you want detailed metadata of experiment analysis.
`pairedEndBam` | logical FALSE, else TRUE, or a logical list of TRUE/FALSE per library you see will be included (run first without and check what order the files will come in) 1 paired end file, then two single will be c(T, F, F). If you have a SRA metadata csv file, you can set this argument to study$LibraryLayout == "PAIRED", where study is the SRA metadata for all files that was aligned.
`viewTemplate` | run View() on template when finished, default (FALSE). Usually gives you a better view of result than using print().
`types` | Default `c("bam", "bed", "wig", "ofst")`, which types of libraries to allow as NGS data.
`libtype` | character, default "auto". Library types, must be length 1 or equal length of number of libraries. "auto" means ORFik will try to guess from file names. Example: RFP (Ribo-seq), RNA (RNA-seq), CAGE, SSU (TCP-seq 40S), LSU (TCP-seq 80S).
`stage` | character, default "auto". Developmental stage, tissue or cell line, must be length 1 or equal length of number of libraries. "auto" means ORFik will try to guess from file names. Example: HEK293 (Cell line), Sphere (zebrafish stage), ovary (Tissue).
`rep` | character, default "auto". Replicate numbering, must be length 1 or equal length of number of libraries. "auto" means ORFik will try to guess from file names. Example: 1 (rep 1), 2 rep(2). Insert only numbers here!
`condition` | character, default "auto". Library conditions, must be length 1 or equal length of number of libraries. "auto" means ORFik will try to guess from file names. Example: WT (wild type), mutant, etc.
`fraction` | character, default "auto". Fractionation of library, must be length 1 or equal length of number of libraries. "auto" means ORFik will try to guess from file names. This columns is used to make experiment unique, if the other columns are not sufficient. Example: cyto (cytosolic fraction), dmso (dmso treated fraction), etc.
`author` | character, default "". Main author of experiment, usually last name is enough. When printing will state "author et al" in info.

### Value

a data.frame, NOTE: this is not a ORFik experiment, only a template for it!

### See Also

Other ORFik_experiment: `ORFik.template.experiment.zf()`, `ORFik.template.experiment()`, `bamVarName()`, `experiment-class`, `filepath()`, `libraryTypes()`, `organism,experiment-method`, `outputLibs()`, `read.experiment()`, `save.experiment()`, `validateExperiments()`

### Examples

    # 1. Pick directory
    dir <- system.file("extdata/Homo_sapiens_sample", "", package = "ORFik")
    # 2. Pick an experiment name
    exper <- "ORFik"
    # 3. Pick .gff/.gtf location
    txdb <- system.file("extdata/Homo_sapiens_sample", "Homo_sapiens_dummy.gtf.db", package = "ORFik")
    # 4. Pick fasta genome of organism
    fa <- system.file("extdata/Homo_sapiens_sample", "Homo_sapiens_dummy.fasta", package = "ORFik")
    # 5. Set organism (optional)
    org <- "Homo sapiens"

    # Create temple not saved on disc yet:
    template <- create.experiment(dir = dir, exper, txdb = txdb,
                                  saveDir = NULL,
                                  fa = fa, organism = org,
                                  viewTemplate = FALSE)
    ## Now fix non-unique rows: either is libre office, microsoft excel, or in R
    template$X5[6] <- "heart"
    # read experiment (if you set correctly)
    df <- read.experiment(template)
    # Save with: save.experiment(df, file = "path/to/save/experiment.csv")

    ## Create and save experiment directly:
    ## Default location: "~/Bio_data/ORFik_experiments/"
    #template <- create.experiment(dir = dir, exper, txdb = txdb,
    #                               fa = fa, organism = org,
    #                               viewTemplate = FALSE)
    ## Custom location (If you work in a team, use a shared folder)
    #template <- create.experiment(dir = dir, exper, txdb = txdb,
    #                               saveDir = "~/MY/CUSTOME/LOCATION",
    #                               fa = fa, organism = org,
    #                               viewTemplate = FALSE)

[Package ORFik version 1.14.7 Index]