acgc.figstyle

  1#!/usr/bin/env python3
  2'''Style settings for matplotlib, for publication-ready figures
  3
  4Activate the style by importing this module:
  5
  6`from acgc import figstyle`
  7
  8Figures generated by Matplotlib will then use the new style.
  9The style includes grid lines (horizontal and vertical) by default.
 10Turn these off and on with `grid_off` and `grid_on`:
 11
 12`figstyle.grid_off()`
 13
 14`figstyle.grid_on()`
 15'''
 16
 17import os
 18import warnings
 19import matplotlib as mpl
 20import matplotlib.style as mstyle
 21import matplotlib.font_manager as mfonts
 22if 'inline' in mpl.get_backend():
 23    import matplotlib_inline
 24
 25# Path to this module
 26_PATH = os.path.dirname(__file__)
 27
 28def activate_style(grid=True,gridaxis='both',mathfont='regular'):
 29    '''Activate style sheet 
 30    
 31    Parameters
 32    ----------
 33    grid : bool, default=True
 34        turn grid lines on (True) or off (False)
 35    gridaxis : str, default='both'
 36        specifies which axes should have grid lines
 37    mathfont : str, default='regular'
 38        sets font used in mathtext, 'regular' uses same font as regular text.
 39        see `set_mathfont` for all options
 40    '''
 41    # Load settings from style file
 42    mstyle.use(os.path.join(_PATH,'acgc.mplstyle'))
 43
 44    # Set mathtext font
 45    set_mathfont(mathfont)
 46
 47    # Turn grid on or off
 48    if grid:
 49        grid_on(axis=gridaxis)
 50
 51    # Use high quality for inline images; Only use this if the inline backend is active
 52    # 'png' is default, 'svg' is also good
 53    if 'inline' in mpl.get_backend():
 54        matplotlib_inline.backend_inline.set_matplotlib_formats('retina')
 55
 56def deactivate_style():
 57    '''Restore rcParams prior to importing figstyle'''
 58    mpl.rcParams = rcParams_old
 59
 60def set_mathfont(fontname=None):
 61    '''Set the font used for typsetting math in Matplotlib
 62
 63    Parameters
 64    ----------
 65    fontname : str, default=None
 66        None         : Restore mathtext font to settings before importing figstyle
 67        'regular'    : Use same font as regular text in math expressions (default).
 68                       Same as using \mathregular or \mathdefault in math expressions.
 69                       Best for mixing regular and math text for superscripts and subscripts.
 70                       May lack or have poor positioning of some math symbols (e.g. integrals).
 71                       This will overwrite mathtext.bf, .bfit, .it, .rm in rcParams.
 72        'custom'     : Uses custom settings from rcParams (mathtext.bf, .bfit, .it, .rm)
 73        'cm'         : Computer Modern (i.e. LaTeX default)
 74        'stix'       : STIX serif
 75        'stixsans'   : STIX sans-serif; best for sans-serif math
 76        'dejavuserif': DejaVu Serif (not recommended)
 77        'dejavusans' : DejaVu Sans (not recommended)
 78    '''
 79
 80    # Check that input has an allowed value
 81    allowedvalues = ['None','regular','custom','cm','stix','stixsans','dejavusans','dejavuserif']
 82    if (fontname not in allowedvalues) and (fontname is not None):
 83        raise ValueError('Font name should be one of the allowed values: '+','.join(allowedvalues))
 84
 85    if fontname is None:
 86        # Restore old mathtext settings
 87        mpl.rcParams.update( {key:rcParams_old[key] for key in
 88                              ['mathtext.fontset','mathtext.bf','mathtext.bfit',
 89                               'mathtext.it','mathtext.rm']})
 90
 91    elif fontname == 'regular':
 92        # Set the math font to the font used for regular text
 93
 94        # Name of the text font
 95        textfont = mpl.rcParams[f'font.{mpl.rcParams["font.family"][0]:s}'][0]
 96        # Use the same font for math
 97        mpl.rcParams.update({'mathtext.fontset': 'custom',
 98                            'mathtext.bf'   : f'{textfont}:bold',
 99                            'mathtext.bfit' : f'{textfont}:italic:bold',
100                            'mathtext.it'   : f'{textfont}:italic',
101                            'mathtext.rm'   : f'{textfont}'})
102    else:
103        # Set the math font to the value provided
104        mpl.rcParams['mathtext.fontset'] = fontname
105
106def grid_off():
107    '''Turn off grid lines'''
108    mpl.rcParams['axes.grid'] = False
109
110def grid_on(axis='both'):
111    '''Turn on grid lines
112    
113    Parameters
114    ----------
115    axis : {'both', 'x', 'y'}
116        specifies which axes should have grid lines 
117    '''
118    mpl.rcParams['axes.grid'] = True
119    mpl.rcParams['axes.grid.axis'] = axis
120
121def load_fonts():
122    '''Load fonts contained in the acgc/fonts subdirectory'''
123
124    # User fonts
125    fonts_pylib = mfonts.findSystemFonts(os.path.join(_PATH,'fonts'))
126
127    # Cached fonts
128    fonts_cached = mfonts.fontManager.ttflist
129    fonts_cached_paths = [ font.fname for font in fonts_cached ]
130
131    # Add fonts that aren't already installed
132    rebuild = False
133    for font in fonts_pylib:
134        if font not in fonts_cached_paths:
135            if rebuild is False:
136                # Issue warning, first time only
137                warnings.warn('Rebuilding font cache. This can take time.')
138            rebuild = True
139            mfonts.fontManager.addfont(font)
140
141    # Save font cache
142    if rebuild:
143        cache = os.path.join(
144                        mpl.get_cachedir(),
145                        f'fontlist-v{mfonts.FontManager.__version__}.json'
146                    )
147        mfonts.json_dump(mfonts.fontManager, cache)
148
149###
150rcParams_old = mpl.rcParams.copy()
151load_fonts()
152activate_style()