ExperimentFile(3)

💖 ExperimentFile(3) — the Experiment File glow-up manual 💖

okay bestie, welcome to ExperimentFile(3) from the Staden Package ✨ this is the page where all the Experiment File manipulation functions live, and honestly? she's giving main character energy. reading, writing, editing — the whole girlboss toolkit. let's get into it 🫶

✨ NAME ✨

the squad, in order:

exp_read_info, exp_fread_info, exp_create_info, exp_destroy_info, exp_create_range, exp_extract_range, exp_get_feature_index, exp_get_int, exp_get_rng, exp_get_str, exp_put_int, exp_put_rng, exp_put_str, exp_print_line, exp_print_seq, exp_print_file, opos2str, str2opos, conf2str, str2conf

and their collective vibe? Manipulations of the Experiment File format. periodt 💅

🎀 SYNOPSIS 🎀

#include <expFileIO.h>

Exp_info *exp_read_info(
     char *file);

Exp_info *exp_fread_info(
     FILE *fp);

Exp_info *exp_create_info();

void exp_destroy_info(
     Exp_info *e);

char *exp_create_range(
     char *str,
     int start,
     int end);

int exp_extract_range(
     char *str,
     int *start,
     int *end);

int exp_get_feature_index(
     char *e);

int exp_get_int(
     Exp_info *e,
     int id,
     int *val);

int exp_get_rng(
     Exp_info *e,
     int id,
     int *from,
     int *to);

int exp_get_str(
     Exp_info *e,
     int id,
     char *s,
     f_implicit s_l);

int exp_put_int(
     Exp_info *e,
     int id,
     int *val);

int exp_put_rng(
     Exp_info *e,
     int id,
     int *from,
     int *to);

int exp_put_str(
     Exp_info *e,
     int id,
     char *s,
     f_implicit s_l);

int exp_print_line(
     FILE *fp,
     Exp_info *e,
     int eflt,
     int i);

int exp_print_seq(
     FILE *fp,
     Exp_info *e,
     int eflt,
     int i);

void exp_print_file(
     FILE *fp,
     Exp_info *e);

char *opos2str(
     int2 *opos,
     int len,
     char *buf);

int str2opos(
     int2 *opos,
     char *buf);

char *conf2str(
     int1 *conf,
     int len,
     char *buf);

int str2conf(
     int1 *conf,
     char *buf);

🌸 DESCRIPTION 🌸

so these functions manipulate Experiment Files — reading them, writing them, editing them, the whole shebang. the principle structure everything revolves around is Exp_info, and here's exactly what she looks like:

#define MAXIMUM_EFLT_LENGTH     4
#define MAXIMUM_EFLTS          48
#define EXP_FILE_LINE_LENGTH  128

typedef Array Exp_entries;

typedef struct {
    Array entries[MAXIMUM_EFLTS]; /* array of array of entries */
    int Nentries[MAXIMUM_EFLTS];  /* array of number of entries */
    FILE *fp;
} Exp_info;

#define NULL_Exp_info ( (Exp_info *) NULL )

⚠️ important bestie: for the purposes of simple and efficient coding, each line on an experiment file must be smaller than the defined EXP_FILE_LINE_LENGTH, which is 128 characters. no exceptions, she does not bend 💀

a bunch of these functions take an experiment file line type identifier as an argument — you'll see them written as taking int id in the prototypes. that id should be specified using one of the macros defined in the header file, and they look like EFLT_XX where XX is the line type. for instance, the ID line type identifier should be written as EFLT_ID. iykyk ✨

the C functions available follow. some FORTRAN interfaces are also available, but they're not documented — check the include file for their prototypes if that's your thing 🙈

🦋 the functions, one by one 🦋

• exp_read_info and exp_fread_info — read an experiment file into an allocated Exp_info structure. if it goes well you get the structure pointer back; otherwise you get the null pointer. 💀
• exp_create_info — allocates and initialises a brand new, blank, Exp_info structure. success = structure pointer returned. otherwise = null pointer returned.
• exp_destroy_info — deallocates an Exp_info structure. it's giving cleanup era 🧹
• exp_create_range — creates a string using the experiment file range format of "start..stop". this format is used by the AQ, ON, TG and TC line types. the buffer you pass in should be large enough to hold the string, bestie, don't play with her. the function returns the str pointer you supplied as an argument. 💖
• exp_extract_range — pulls the start and end values out of the string representation of a range; "start..stop". the values get stored in the integer pointers you send as arguments. if it works, returns 0. otherwise returns -1. 🫶
• exp_get_feature_index — converts a string representation of an experiment file line type into its integer value. for example, exp_get_feature_index("SQ") returns the integer 22, which is the same as the EFLT_SQ definition. iconic conversion behaviour ✨
• exp_get_int — grabs the integer value held in a specific line type. it lands in the integer pointer val. if successful, returns 0. otherwise returns 1.
• exp_get_rng — grabs the range values held in a specific line type. they land in the integer pointers from and to. if successful, returns 0. otherwise returns 1.
• exp_get_str — grabs the string value held in a specific line type. it lands in the string s, and at most s_l characters are copied. if successful, returns 0. otherwise returns 1. no overflow, we don't do that here 💅
• exp_put_int — writes the integer pointed to by val to the specified line type. if successful, returns 0. otherwise returns 1.
• exp_put_rng — writes the range pointed to by from and to to the specified line type. if successful, returns 0. otherwise returns 1.
• exp_put_str — writes the string s of length s_l to the specified line type. if successful, returns 0. otherwise returns 1.
• exp_print_line — outputs all entries of the specified type to the specified file pointer. go off, printer queen 👑
• exp_print_seq — okay so bestie, the original page literally just lists her name here and gives no description at all 😭 she's in the synopsis, she's real, and that's genuinely all this page says. i'm not gonna make anything up about her, that's not the vibe.
• exp_print_file — outputs all entries of all line types to the specified file pointer. the full dump, the whole story, no crumbs left 🌈
• opos2str — converts an array of original positions held in opos with len elements to a string suitable for use in the ON line type. the buf should be large enough to hold the string, which in the worst case will be 4 * sequence length. returns buf. ✨
• str2opos — converts the experiment file original position string held in buf to an array of original positions to be stored in opos. opos must be large enough to hold the data, hence it should be of the same length as the sequence. returns the number of elements written to the opos array. 💖
• conf2str — converts an array of confidence values helf in confR with len elements to a string suitable for use in the AV line type. the buf should be large enough to hold the string, which in the worst case will be 4 * sequence length. returns buf. (yes, the original page says "helf", and i am nothing if not faithful to the source, so "helf" it stays 🎀)
• str2conf — convers the experiment file confidence values string held in buf to an array of confidence values to be stored in conf. conf must be large enough to hold the data, hence it should be of the same length as the sequence. returns the number of elements written to the conf array. 💜

🔥 SEE ALSO 🔥

ExperimentFile(4) — go read her next bestie, she's the companion piece fr fr 📖

and that's the whole page, babe 🫶 this was ExperimentFile(3), straight out of the Staden Package, manual section 3. thanks for reading, you ate that, no cap ✨💅🎀🦋🌸