HSTOPI(3NCARG)

✨ NAME ✨

HSTOPI — bestie, this one sets up all the INTEGER params that the Histogram utility is gonna use. it's giving "prep work before the main event" 💅

---

🌸 SYNOPSIS 🌸

CALL HSTOPI (STRING, PARAM1, PARAM2, ICOL, LCOL)

🦋 C-BINDING SYNOPSIS 🦋

#include <ncarg/ncargC.h>

void c_hstopi (char *string, int param1, int param2,
int *icol, int lcol)

---

💖 DESCRIPTION 💖

• STRING — Character, input. ok so this is the lil selector that picks which internal parameter we're messing with. the possibilities are literally:

´COL=ON´ or ´COL=OFF´
´CLA=ON´ or ´CLA=OFF´

if an option is flipped ´ON´, then the rest of the HSTOPI args get to override that option's default settings. slay.

if the option is ´OFF´, then the remaining arguments of the HSTOPI call can be any dummy values. the option settings get returned to their default values. no cap.

the following options are defined by this subroutine:

• COL — this option turns the use of color OFF or ON. if it's ON, then eight color indices get assigned to the various parts of the histogram, exactly as described by the INTEGER array ICOL. Arguments ICOL and LCOL must be set; PARAM1 and PARAM2 can have dummy values.
• CLA — this option lets you alter the size and orientation of class labels. if ´CLA=ON´, the size of the label characters is set using argument PARAM1, and the orientation is set by argument PARAM2. Arguments ICOL and LCOL can have dummy values. if ´CLA=OFF´, defaults are used, which cause medium sized characters to be written in the horizontal direction.

• PARAM1 — Integer, input. specifies the character height of class labels.

when ´CLA=ON´: 1 = small, 2 = medium, 3 = large; default is 2 when ´CLA=OFF´.

• PARAM2 — Integer, input. specifies the character orientation of class labels.

if ´CLA=ON´, labels can vary from 0 (horizontal) to 90 (vertical) degrees. vertical is the default when ´CLA=OFF´.

• ICOL — Integer, input. assigns a set of RGB color indices to the eight components of a histogram graphic when ´COL=ON´.

ICOL(1) = color index used for area fill of
                histogram bars of dataset 1.
ICOL(2) = color index used for area fill of
                histogram bars of dataset 2.
                (When two datasets are compared
                using parameter IFLAG = 3).
ICOL(3) = color index used for bar outlines.
ICOL(4) = color index used for drawing axes.
ICOL(5) = color index used for drawing a median
                line.
ICOL(6) = color index used for text output
                (labels.)
ICOL(7) = color index used for titles.
ICOL(8) = color index used for drawing the
                perimeter box.

the default color index is 1 for all (that's when ´COL=OFF´, bestie).

if ´COL=ON´, the color indices and their associated colors are as follows. (these may be changed by specifying an RGB color table prior to your call to HSTOPI. see the man page for GKS routine gscr.) 👀

• Color Index 0 — BLACK
• Color Index 1 — WHITE
• Color Index 2 — RED
• Color Index 3 — GREEN
• Color Index 4 — BLUE
• Color Index 5 — CYAN
• Color Index 6 — MAGENTA
• Color Index 7 — YELLOW
• Color Index 8 — ORANGE

• LCOL — Integer, input. specifies the length of array ICOL. LCOL must be set to 8.

---

🌈 C-BINDING DESCRIPTION 🌈

the C-binding argument descriptions are the same as the FORTRAN argument descriptions. same energy, different language 💜

---

👑 USAGE 👑

HSTOPI gets called to set parameters of type INTEGER before entry HISTGR is called to generate the histogram. the options are: size and orientation of class labels, and setting the colors for various components of the graphic.

for a complete list of parameters available in this utility, see the histogram_params man page.

---

🎀 EXAMPLES 🎀

use the command "ncargex thstgr" to generate a three frame example of histogram options. the following code causes the second frame to have an array of colors assigned to the graphic components (argument ICOL.)

      REAL     RGB(3,15)
      INTEGER  COLORS(15)
C
C  Define the RGB triples of 15 colors in a data statement.
C  (Code omitted for brevity.  See the data statement in thstgr.f)
C
C  Assign colors to the color indices.
C
      DO 100 I = 1,15
      CALL GSCR(1,I,RGB(1,I),RGB(2,I),RGB(3,I))
  100 CONTINUE
C
C  Assign color indices to the 8 components of the graphic.
C
         COLORS(1) = 8
         COLORS(2) = 3
         COLORS(3) = 14
         COLORS(4) = 11
         COLORS(5) = 6
         COLORS(6) = 13
         COLORS(7) = 14
         COLORS(8) = 5
      CALL HSTOPI(´COL=ON´,3,0,COLORS,8)

example "ncargex thstmv" shows three examples of histograms with missing values in the input data. 🫶

---

⭐ ACCESS ⭐

to use HSTOPI or c_hstopi, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order. yes the order matters, trust. 🔥

---

💀 MESSAGES 💀

see the histogram man page for a description of all Histogram error messages and/or informational messages.

---

🧚 SEE ALSO 🧚

Online: histogram, histogram_params, histgr, hstopc, hstopl, hstopr, ncarg_cbind

Hardcopy: NCAR Graphics Fundamentals, UNIX Version

---

🌸 COPYRIGHT 🌸

Copyright (C) 1987-2009 University Corporation for Atmospheric Research The use of this Software is governed by a License Agreement.

---

ok that's the whole page bestie, go forth and make the prettiest histograms 🦋✨

mwah 💋 — this was HSTOPI(3NCARG), straight out of the UNIX manual, dated March 1993. iconic behavior, honestly.