read_reading(3)

🎀 read_reading — bestie, let's read a trace file 💅

okay so this is the read_reading(3) page from the Staden Package manual, and we're about to get a whole Read structure out of a trace file. no cap, it's giving data-structure-glowup. ✨

🌸 NAME 🌸

read_reading, fread_reading — literally just: read a trace file into a Read structure. that's the whole job. iconic. 👑

✨ SYNOPSIS ✨

#include <Read.h>

Read *read_reading(
     char *filename,
     int format);

Read *fread_reading(
     FILE *fp,
     char *filename,
     int format);

💖 DESCRIPTION 💖

so these two functions slurp trace files into a Read structure, and bestie, they are not picky. a whole variety of formats is supported, including ABI, ALF and SCF. (heads up though — the first two, ABI and ALF, are only supported when the library is being used as part of the Staden Package. iykyk.) 🫶

on top of that, there's also support for reading the plain (old) staden format files and Experiment files. obsessed.

compressed trace files? yeah, those work too. 🌈 decompression gets done with either gzip -d or uncompress, and the result is written out to a temporary file for further processing. then that temp file is read, and then it's removed. clean up after yourself, queen. 💅

now, when you're reading an experiment file, the trace file referenced by the LN and LT line types is what actually gets read. the QL, QR (left and right quality clips) plus the SL, SR (left and right vector clips) get pulled out of the Experiment file to produce the cutoff information that lives inside the Read structure. after that, the orig_trace field of the Read structure will hold the pointer to the experiment file structure, and the orig_trace_format field gets set to TT_EXP. periodt. ✨

these functions allocate a Read structure and hand it back to you. to deallocate it, use the read_deallocate() function. (don't ghost your memory, bestie. 😭)

read_reading() reads a trace from the specified filename and format. the formats available are TT_SCF, TT_ABI, TT_ALF, TT_PLN, TT_EXP and TT_ANY. if you specify format TT_ANY, it'll attempt to automatically detect the correct format type by analysing the trace file for magic numbers and composition. 🔍 then you can use the format field of the structure to figure out what the real trace type turned out to be. main character energy fr fr.

fread_reading() reads a trace from the specified file pointer. the filename argument is used for setting the trace_name field of the resulting structure, and for error messages. other than that, the function is identical to the read_reading() function. twinning! 👯

the Read structure itself is as follows. 🦋

typedef uint_2 TRACE;        /* for trace heights */

typedef struct
{
    int         format;      /* Trace file format */
    char       *trace_name;  /* Trace file name   */

    int         NPoints;     /* No. of points of data */
    int         NBases;      /* No. of bases          */

    /* Traces */
    TRACE      *traceA;      /* Array of length `NPoints' */
    TRACE      *traceC;      /* Array of length `NPoints' */
    TRACE      *traceG;      /* Array of length `NPoints' */
    TRACE      *traceT;      /* Array of length `NPoints' */
    TRACE       maxTraceVal; /* The maximal value in any trace */

    /* Bases */
    char       *base;        /* Array of length `NBases' */
    uint_2     *basePos;     /* Array of length `NBases' */

    /* Cutoffs */
    int         leftCutoff;  /* Number of unwanted bases */
    int         rightCutoff; /* Number of unwanted bases */

    /* Miscellaneous Sequence Information */
    char       *info;        /* misc seq info, eg comments */

    /* Probability information */
    char       *prob_A;      /* Array of length 'NBases' */
    char       *prob_C;      /* Array of length 'NBases' */
    char       *prob_G;      /* Array of length 'NBases' */
    char       *prob_T;      /* Array of length 'NBases' */

    /* The original input format data, or NULL if inapplicable */
    int orig_trace_format;
    void *orig_trace;

} Read;

🫶 RETURN VALUES 🫶

on successful completion, the read_reading() and fread_reading() functions return a pointer to a Read structure. otherwise these functions return NULLRead (which is a null pointer). 💀 so yeah, always vibe check your return value.

🌟 SEE ALSO 🌟

• write_reading(3)
• fwrite_reading(3)
• deallocate_reading(3)
• scf(4)
• ExperimentFile(4)

and that's the whole page bestie!! 💖 this was the Staden Package's read_reading(3) manual page — stay hydrated, free your Read structs, and go read some traces. mwah. 🎀✨