datangraphics

## Class DatanGraphics

- java.lang.Object
- - datangraphics.DatanGraphics

-     public final class DatanGraphics
      extends java.lang.Object

  A final class with methods to produce graphics.
  Author:
    Siegmund Brandt.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DatanGraphics()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `chooseColor(int colorIndex)` Chooses a color index, determining the color of all graphics elements created after this choice until it is changed.
    `static void` | `closeWorkstation()` Finalizes graphics, displays DatanGraphicsFrame (if one was opened), and closes Postscript file (if one was opened).
    `static void` | `drawBoundary()` Draws a frame around the computing coordinates window.
    `static void` | `drawBrokenPolyline(int ntype, double scalef, double[] xpl, double[] ypl)` Draws a broken polyline.
    `static void` | `drawCaption(double scalef, java.lang.String string)` Draws a caption appearing just under the upper edge of the window in world coordinates.
    `static void` | `drawContour(double x0, double y0, double dx, double dy, int nx, int ny, double fcont, DatanUserFunction cuf)` Draws the contour line f(x,y) = c of a function f as a series of line segments in the x,y plane.
    `static void` | `drawCoordinateCross()` Draws the axes of the computing-coordinate system as dashed lines within the window of computing coordiates.
    `static void` | `drawDatapoint(int nmark, double scalef, double x, double y, double sigmax, double sigmay, double rho)` Draws a data point with bars, and covariance ellipse
    `static void` | `drawFrame()` Draws a frame around the window in the world coordinate system.
    `static void` | `drawHistogram(Histogram histogram)` Draws a histogram
    `static void` | `drawMark(int nmark, double scalef, double xpm, double ypm)` Draws a polymarker
    `static void` | `drawPolyline(double[] xpl, double[] ypl)` Draws a polyline.
    `static void` | `drawScaleX(java.lang.String string)` Draws an axis in x-direction.
    `static void` | `drawScaleY(java.lang.String string)` Draws an axis in y-direction.
    `static void` | `drawText(double x, double y, double scalef, java.lang.String string)` Draws a text appearing at a desired position.
    `static void` | `openWorkstation(java.lang.String frametitle)` Creates a new, initially invisible DatanGraphicsFrame with the specified title
    `static void` | `openWorkstation(java.lang.String frameTitle, java.lang.String filename)` Creates a new, initially invisible DatanGraphicsFrame with the specified title.
    `static double` | `roundDown(double x)` Returns a number with the sign of x and somewhat smaller than x with only few significant digits; method is used for automatic determination of window in computing coordinates by some classes in package datangraphics which yield a complete plot.
    `static double` | `roundUp(double x)` Returns a number with the sign of x and somewhat larger than x with only few significant digits; method is used for automatic determination of window in computing coordinates by some classes in package datangraphics which yield a complete plot.
    `static void` | `setBigClippingWindow()` Sets the clipping window to be the frame of the entire plot.
    `static void` | `setFormat(double width, double height)` Determines the Format of the plot.
    `static void` | `setPaperSizeAndBorders(double paperwidth, double paperheight, double borderleft, double borderright, double borderbottom, double bordertop)` Sets paper size and distances of used area from paper edge; if not called A4 format is assumed with 0.5 cm for all boders.
    `static void` | `setParametersForScale(double fix, double del, int ntic, double ticscale, double numberscale, boolean lnum)` Sets user defined properties for the scale drawn by the next call of drawScaleX or drawScaleY.
    `static void` | `setPSColor(int index, java.awt.Color color, float linewidth)` Assigns color and linewidth to a color indesx for Postscript plots plots.
    `static void` | `setScreenBackground(java.awt.Color color)` Assigns a color to the background of screen plots.
    `static void` | `setScreenColor(int index, java.awt.Color color, float linewidth)` Assigns color and linewidth to a color indesx for screen plots.
    `static void` | `setSmallClippingWindow()` Sets the clipping window to be the window of the computing coordinates.
    `static void` | `setStandardPaperSizeAndBorders()` Sets paper size to A4 format and all boders to 0.5 cm.
    `static void` | `setStandardPSColors()` Assigns standard color and linewidth values to all color indices for Postscript plots.
    `static void` | `setStandardPSColorsBlackAndWhite()` Assigns standard color and linewidth values to all color indices for Postscript plots in black-and-white.
    `static void` | `setStandardScreenColors()` Assigns standard color and linewidth values to all color indices for screen plots; also assigns standard color to screen plot background.
    `static void` | `setViewportInWorldCoordinates(double xawc, double xbwc, double yawc, double ybwc)` Establishes a viewport in world coordiates.
    `static void` | `setWindowInComputingCoordinates(double xacc, double xbcc, double yacc, double ybcc)` Establishes a window in computing coordiates.
    `static void` | `setWindowInWorldCoordinates(double xapwc, double xbpwc, double yapwc, double ybpwc)` Establishes a window in world coordiates.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DatanGraphics

          public DatanGraphics()

  - ### Method Detail

    - #### openWorkstation

          public static void openWorkstation(java.lang.String frametitle)

      Creates a new, initially invisible DatanGraphicsFrame with the specified title
      Parameters:
        `frameTitle` - title of DatanGraphicsFrame; if frameTitle is blank the no DatanGraphicsFrame is initialized.

    - #### openWorkstation

          public static void openWorkstation(java.lang.String frameTitle,
                             java.lang.String filename)

      Creates a new, initially invisible DatanGraphicsFrame with the specified title. In addition, a file is initialized into which the graphics is written in Postscript format.
      Parameters:
        `frameTitle` - title of DatanGraphicsFrame; if frameTitle is blank the no DatanGraphicsFrame is initialized.
        `filename` - name of Postscript file - has to end with either ".ps" (for postscript) or ".eps" (for encapsulated postscript). If filename is blank, no file is initialized.

    - #### closeWorkstation

          public static void closeWorkstation()

      Finalizes graphics, displays DatanGraphicsFrame (if one was opened), and closes Postscript file (if one was opened).

    - #### setWindowInComputingCoordinates

          public static void setWindowInComputingCoordinates(double xacc,
                                             double xbcc,
                                             double yacc,
                                             double ybcc)

      Establishes a window in computing coordiates. Remark: Unreasonable input values are replaced by values that are as reasonable as possible. E.g., if xacc == xbcc, then the method takes xbcc to be xacc + 1.
      Parameters:
        `xacc` - lower window edge in x
        `xbcc` - upper window edge in x
        `yacc` - lower window edge in y
        `ybcc` - upper window edge in y

    - #### setWindowInWorldCoordinates

          public static void setWindowInWorldCoordinates(double xapwc,
                                         double xbpwc,
                                         double yapwc,
                                         double ybpwc)

      Establishes a window in world coordiates. Remark: Unreasonable input values are replaced by values that are as reasonable as possible. E.g., if xapwc == xbpwc, then the method takes xbpwc to be xapwc + 1.
      Parameters:
        `xapwc` - lower window edge in x
        `xbpwc` - upper window edge in x
        `yapwc` - lower window edge in y
        `ybpwc` - upper window edge in y

    - #### setViewportInWorldCoordinates

          public static void setViewportInWorldCoordinates(double xawc,
                                           double xbwc,
                                           double yawc,
                                           double ybwc)

      Establishes a viewport in world coordiates. Remark: Unreasonable input values are replaced by values that are as reasonable as possible. E.g., if xawc == xbwc, then the method takes xbwc to be xawc + 1.
      Parameters:
        `xawc` - lower viewport edge in x
        `xbwc` - upper viewport edge in x
        `yawc` - lower viewport edge in y
        `ybwc` - upper viewport edge in y

    - #### chooseColor

          public static void chooseColor(int colorIndex)

      Chooses a color index, determining the color of all graphics elements created after this choice until it is changed.
      Parameters:
        `colorindex` - index in color table; has to be >=1, <=8 for method to be effective

    - #### drawContour

          public static void drawContour(double x0,
                         double y0,
                         double dx,
                         double dy,
                         int nx,
                         int ny,
                         double fcont,
                         DatanUserFunction cuf)

      Draws the contour line f(x,y) = c of a function f as a series of line segments in the x,y plane.
      Parameters:
        `x0,dx,nx` - initial value, interval width and number of intervals for dividing the x axis
        `y0,dy,ny` - same the y axis
        `fcont` - function value c of the contour line
        `cuf` - user function computing f(x,y) which must be an extension of DatanUserFunction

    - #### drawCaption

          public static void drawCaption(double scalef,
                         java.lang.String string)

      Draws a caption appearing just under the upper edge of the window in world coordinates.
      Parameters:
        `scalef` - scale factor; the typical length of a dash is 1% of the picture diagonal multiplied by this factor
        `string` - string containing the encoded text of the caption

    - #### drawText

          public static void drawText(double x,
                      double y,
                      double scalef,
                      java.lang.String string)

      Draws a text appearing at a desired position.
      Parameters:
        `x,y` - computing coordinate designating the lower left-hand corner of the rectangle surrounding the text
        `scalef` - scale factor; the typical length of a dash is 1% of the picture diagonal multiplied by this factor
        `string` - string containing the encoded text

    - #### drawHistogram

          public static void drawHistogram(Histogram histogram)

      Draws a histogram
      Parameters:
        `histogram` - the histogram to be drawn

    - #### drawDatapoint

          public static void drawDatapoint(int nmark,
                           double scalef,
                           double x,
                           double y,
                           double sigmax,
                           double sigmay,
                           double rho)

      Draws a data point with bars, and covariance ellipse
      Parameters:
        `nmark` - form of polymarker symbolizing the data point (1: open circle, 2: closed circle, 3: open sqare, 4: closed sqare, 5: open diamond, 6: closed diamond, 7: +, 8: x. 9: *)
        `scalef` - scale factor; the diameter of the polymarker is 1% of the picture diagonal multiplied by this factor
        `x` - x coordinate of data point
        `y` - y coordinate of data point
        `deltax` - error in x; error bar is drawn only if deltax > 0 and if its siye would exceed the radius if the polymarker
        `deltay` - error in y; error bar is drawn only if deltax > 0 and if its siye would exceed the radius if the polymarker
        `rho` - correlation between errors; covariance ellipse is not drawn if rho = 0 (drawing can be forced by giveng nmark a negative sign)

    - #### drawMark

          public static void drawMark(int nmark,
                      double scalef,
                      double xpm,
                      double ypm)

      Draws a polymarker
      Parameters:
        `nmark` - form of polymarker (1: open circle, 2: closed circle, 3: open sqare, 4: closed sqare, 5: open diamond, 6: closed diamond, 7: +, 8: x. 9: *)
        `scalef` - scale factor; the diameter of the polymarker is 1% of the picture diagonal multiplied by this factor
        `xpm` - x coordinate of polymarker
        `ypm` - y coordinate of polymarker

    - #### drawPolyline

          public static void drawPolyline(double[] xpl,
                          double[] ypl)

      Draws a polyline.
      Parameters:
        `xpl` - x-coordinates of polyline
        `ypl` - y-coordinates of polyline

    - #### drawBrokenPolyline

          public static void drawBrokenPolyline(int ntype,
                                double scalef,
                                double[] xpl,
                                double[] ypl)

      Draws a broken polyline.
      Parameters:
        `ntype` - line type (1: dashed, 2: dotted, 3 dot-dashed)
        `scalef` - scale factor; the typical length of a dash is 1% of the picture diagonal multiplied by this factor
        `xpl` - x-coordinates of polyline
        `ypl` - y-coordinates of polyline

    - #### drawBoundary

          public static void drawBoundary()

      Draws a frame around the computing coordinates window.

    - #### drawCoordinateCross

          public static void drawCoordinateCross()

      Draws the axes of the computing-coordinate system as dashed lines within the window of computing coordiates.

    - #### drawFrame

          public static void drawFrame()

      Draws a frame around the window in the world coordinate system.

    - #### setFormat

          public static void setFormat(double width,
                       double height)

      Determines the Format of the plot. Remarks: If plot too large for size of paper or screen frame, it is reduced in size to fit.
      Parameters:
        `width` - width of plot in centimetres; if height=0, then plot has landscape A format with width being A number, e.g. (widhth=5, height=0) stands for landscape A5
        `height` - height of plot in centimetres; if = width=0, then plot has portrait A format with height being A number, e.g. (widhth=0, height=5) stands for portrait A5. If both width=0 and height=0, then the format is set to landscape A5.

    - #### setSmallClippingWindow

          public static void setSmallClippingWindow()

      Sets the clipping window to be the window of the computing coordinates.

    - #### setBigClippingWindow

          public static void setBigClippingWindow()

      Sets the clipping window to be the frame of the entire plot.

    - #### drawScaleX

          public static void drawScaleX(java.lang.String string)

      Draws an axis in x-direction. Remark: Tick marks from the upper and lower edges of the computing-coordinate window are drawn inside the window. Below the lower edge, numbers are displayed which label some of these marks. It is recommended to first call the method drawBoundary() to display lines on the window edges. The ticks and numbers are created automatically based on the choice of world and computing coordinates; they can be determined explicitely by the user by calling setParametersForScale(...) before calling this method.
      Parameters:
        `string` - encoded text appearing at arrow tip accompanying the scale

    - #### drawScaleY

          public static void drawScaleY(java.lang.String string)

      Draws an axis in y-direction. Remark: Tick marks from the left and right edges of the computing-coordinate window are drawn inside the window. To the left of the left edge, numbers are displayed which label some of these marks. It is recommended to first call the method drawBoundary() to display lines on the window edges. The ticks and numbers are created automatically based on the choice of world and computing coordinates; they can be determined explicitely by the user by calling setParametersForScale(...) before calling this method.
      Parameters:
        `string` - encoded text appearing at arrow tip accompanying the scale

    - #### setParametersForScale

          public static void setParametersForScale(double fix,
                                   double del,
                                   int ntic,
                                   double ticscale,
                                   double numberscale,
                                   boolean lnum)

      Sets user defined properties for the scale drawn by the next call of drawScaleX or drawScaleY.
      Parameters:
        `fix` - value (in computing coordinates) which one wants to mark and label with a number on the axis
        `del` - distance between labeled tick marks
        `ntic` - number of intervals with smaller tic marks between two labeled tick marks
        `ticscale` - scale factor for tic length
        `numberscale` - scale factor for numbers
        `lnum` - defines wether the numbers on the axes are shown ind decimal (lnum=true) or exponential form (lnum=false)

    - #### setStandardPaperSizeAndBorders

          public static void setStandardPaperSizeAndBorders()

      Sets paper size to A4 format and all boders to 0.5 cm.

    - #### setPaperSizeAndBorders

          public static void setPaperSizeAndBorders(double paperwidth,
                                    double paperheight,
                                    double borderleft,
                                    double borderright,
                                    double borderbottom,
                                    double bordertop)

      Sets paper size and distances of used area from paper edge; if not called A4 format is assumed with 0.5 cm for all boders.
      Parameters:
        `paperwidth` - width of paper in cm
        `paperheight` - height of paper in cm
        `borderleft` - distance of used area from left edge in cm
        `borderright` - distance of used area from right edge in cm
        `bordertop` - distance of used area from top edge in cm
        `borderbottom` - distance of used area from bottom edge in cm

    - #### setStandardScreenColors

          public static void setStandardScreenColors()

      Assigns standard color and linewidth values to all color indices for screen plots; also assigns standard color to screen plot background.

      Background: Color(0.f, 0.f, .9f)

      color index 1: Color(1.f, 1.f, 0.f), line width 2.f

      color index 2: Color(1.f, 1.f, 1.f), line width 2.f

      color index 3: Color(0.f, 1.f, 1.f), line width 2.f

      color index 4: Color(1.f, 0.784f, 0.f), line width 2.f

      color index 5: Color(1.f, 0.f, 0.f), line width 2.f

      color index 6: Color(0.753f, 0.753f, 0.753f), line width 2.f

      color index 7: Color(0.f, 1.f, 0.f), line width 2.f

      color index 8: Color(1.f, 0.f, 1.f), line width 2.f

    - #### setScreenColor

          public static void setScreenColor(int index,
                            java.awt.Color color,
                            float linewidth)

      Assigns color and linewidth to a color indesx for screen plots.
      Parameters:
        `index` - color index (>=1, <=8)
        `color` - color to be assigned
        `linewidth` - line width (standard value is 2.f)

    - #### setScreenBackground

          public static void setScreenBackground(java.awt.Color color)

      Assigns a color to the background of screen plots.

    - #### setStandardPSColors

          public static void setStandardPSColors()

      Assigns standard color and linewidth values to all color indices for Postscript plots.

      Background: Color.white

      color index 1: Color(0.f, 0.f, 1.f), line width 2.f

      color index 2: Color(0.f, 0.f, 0.f), line width 2.f

      color index 3: Color(0.f, 1.f, 0.f), line width 2.f

      color index 4: Color(1.f, 0.f, 0.f), line width 2.f

      color index 5: Color(1.f, 0.f, 0.f), line width 2.f

      color index 6: Color(.70f, 0.f, 0.75f), line width 2.f

      color index 7: Color(0.f, 1.f, 0.f), line width 2.f

      color index 8: Color(1.f, 0.f, 1.f), line width 2.f

    - #### setPSColor

          public static void setPSColor(int index,
                        java.awt.Color color,
                        float linewidth)

      Assigns color and linewidth to a color indesx for Postscript plots plots.
      Parameters:
        `index` - color index (>=1, <=8)
        `color` - color to be assigned
        `linewidth` - line width (standard value is 2.f)

    - #### setStandardPSColorsBlackAndWhite

          public static void setStandardPSColorsBlackAndWhite()

      Assigns standard color and linewidth values to all color indices for Postscript plots in black-and-white.

      Background: Color.white

      color index 1 to 8: Color.black, line width 2.f

    - #### roundUp

          public static double roundUp(double x)

      Returns a number with the sign of x and somewhat larger than x with only few significant digits; method is used for automatic determination of window in computing coordinates by some classes in package datangraphics which yield a complete plot.

    - #### roundDown

          public static double roundDown(double x)

      Returns a number with the sign of x and somewhat smaller than x with only few significant digits; method is used for automatic determination of window in computing coordinates by some classes in package datangraphics which yield a complete plot.