screen3

  1# -*- coding: utf-8 -*-
  2"""
  3Python functions for using
  4[SCREEN3](https://www.epa.gov/scram/air-quality-dispersion-modeling-screening-models#screen3).
  5* `screen3.run` – wrapper to quickly create a run without needing to go through the prompt
  6* `screen3.read` – load the output into a pandas DataFrame
  7* `screen3.plot` – some plotting routines using the output DataFrame
  8
  9Most of the variables related to SCREEN3 are the same as the ones in the SCREEN3 input and output files,
 10including that they are in uppercase.
 11
 12`screen3` lives [on GitHub](https://github.com/zmoon/screen3).
 13
 14.. note::
 15   Python 3.6+ is required
 16"""
 17# TODO: type annotations for the main user-facing fns?
 18
 19import os
 20from pathlib import Path
 21import platform
 22import subprocess
 23import sys
 24import warnings
 25
 26import numpy as np
 27
 28__version__ = "0.1.2"
 29
 30__all__ = (
 31    "run",
 32    "read",
 33    "plot",
 34    "download",
 35    "build",
 36    "load_example",
 37    "SCREEN_OUT_COL_UNITS_DICT",
 38    "DEFAULT_SRC_DIR",
 39)
 40
 41
 42# Check for Python 3.6+
 43# Note: `sys.version_info` became a named tuple in 3.1
 44if not (sys.version_info.major >= 3 and sys.version_info.minor >= 6):
 45    raise Exception(f"Python version must be 3.6+.\nYours is {sys.version}")
 46
 47
 48_THIS_DIR = Path(__file__).parent
 49
 50
 51# DEFAULT_SRC_DIR = Path.home() / ".local/screen3/src"
 52DEFAULT_SRC_DIR = "./src"
 53"""Default directory in which to place the SCREEN3 source code from EPA."""
 54
 55_DEFAULT_EXE_PATH = f"{DEFAULT_SRC_DIR}/SCREEN3.exe"
 56
 57
 58def download(*, src=DEFAULT_SRC_DIR):
 59    """Download the SCREEN3 zip from EPA and extract to directory `src`.
 60
 61    If it fails, you can always download it yourself some other way.
 62
 63    <https://gaftp.epa.gov/Air/aqmg/SCRAM/models/screening/screen3/screen3.zip>
 64
 65    Parameters
 66    ----------
 67    src : path-like
 68        Where to extract the files to.
 69        .. note::
 70           As long as this isn't modified, the `src`/`exe` keyword doesn't need to be changed
 71           for `build`, `run`, or `load_example`.
 72    """
 73    import io
 74    import zipfile
 75    from pathlib import Path
 76
 77    import requests
 78
 79    url = "https://gaftp.epa.gov/Air/aqmg/SCRAM/models/screening/screen3/screen3.zip"
 80
 81    extract_to = Path(src)
 82    extract_to.mkdir(exist_ok=True, parents=True)
 83    
 84    r = requests.get(url, verify=False)  # TODO: get it working without having to disable certificate verification
 85    with zipfile.ZipFile(io.BytesIO(r.content)) as z:
 86        for info in z.infolist():
 87            with z.open(info) as zf, open(extract_to / info.filename, "wb") as f:
 88                f.write(zf.read())
 89
 90
 91_SCREEN3A_PATCH = """
 92386,397c386,401
 93< $IF DEFINED (LAHEY)
 94<       CALL DATE(RUNDAT)
 95<       CALL TIME(RUNTIM)
 96< $ELSE
 97<       CALL GETDAT(IPTYR, IPTMON, IPTDAY)
 98<       CALL GETTIM(IPTHR, IPTMIN, IPTSEC, IPTHUN)
 99< C     Convert Year to Two Digits
100<       IPTYR = IPTYR - 100*INT(IPTYR/100)
101< C     Write Date and Time to Character Variables, RUNDAT & RUNTIM
102<       WRITE(RUNDAT,'(2(I2.2,1H/),I2.2)') IPTMON, IPTDAY, IPTYR
103<       WRITE(RUNTIM,'(2(I2.2,1H:),I2.2)') IPTHR, IPTMIN, IPTSEC
104< $ENDIF
105---
106> !$IF DEFINED (LAHEY)
107> !      CALL DATE(RUNDAT)
108> !      CALL TIME(RUNTIM)
109> !$ELSE
110> !      CALL GETDAT(IPTYR, IPTMON, IPTDAY)
111> !      CALL GETTIM(IPTHR, IPTMIN, IPTSEC, IPTHUN)
112> !C     Convert Year to Two Digits
113> !      IPTYR = IPTYR - 100*INT(IPTYR/100)
114> !C     Write Date and Time to Character Variables, RUNDAT & RUNTIM
115> !      WRITE(RUNDAT,'(2(I2.2,1H/),I2.2)') IPTMON, IPTDAY, IPTYR
116> !      WRITE(RUNTIM,'(2(I2.2,1H:),I2.2)') IPTHR, IPTMIN, IPTSEC
117> !$ENDIF
118> 
119> ! here for GNU (zm)
120>       call DATE_AND_TIME(DATE=RUNDAT, TIME=RUNTIM)
121> 
122""".lstrip()
123
124
125_DEPVAR_PATCH = """
12635c35
127< 
128\ No newline at end of file
129---
130> 
131""".lstrip()
132
133
134def _dos2unix(fp):
135    """Convert CRLF line endings (if any) to LF."""
136    with open(fp, "r") as f:
137        s = f.read()
138    with open(fp, "w", newline="\n") as f:
139        f.write(s)
140
141
142def build(*, src=DEFAULT_SRC_DIR):
143    """Build the SCREEN3 executable by pre-processing the sources and compiling with GNU Fortran.
144    
145    .. note::
146       Requires `patch` and `gfortran` on PATH.
147
148    Parameters
149    ----------
150    src : path-like
151        Source directory, containing `SCREEN3A.FOR` etc., e.g., downloaded using `screen3.download`.
152    """
153    cwd = Path.cwd()
154    bld = Path(src)
155
156    os.chdir(bld)
157
158    srcs = ['SCREEN3A.FOR', 'SCREEN3B.FOR', 'SCREEN3C.FOR']
159
160    # Fix line endings
161    if platform.system() != "Windows":
162        # subprocess.run(['dos2unix'] + srcs)
163        for src in srcs:
164            _dos2unix(src)
165
166    # Patch code
167    with open("SCREEN3A.FOR.patch", "w") as f:
168        f.write(_SCREEN3A_PATCH)
169    with open("DEPVAR.INC.patch", "w") as f:
170        f.write(_DEPVAR_PATCH)
171    subprocess.run(['patch', 'SCREEN3A.FOR', 'SCREEN3A.FOR.patch'])
172    subprocess.run(['patch', 'DEPVAR.INC', 'DEPVAR.INC.patch'])
173
174    # Compile
175    subprocess.run(['gfortran', '-cpp'] + srcs + ['-o', 'SCREEN3.exe'])
176
177    os.chdir(cwd)
178
179
180# note that U10M becomes UHANE in non-regulatory mode
181SCREEN_OUT_COL_NAMES = 'DIST CONC STAB U10M USTK MIX_HT PLUME_HT SIGMA_Y SIGMA_Z DWASH'.split()
182SCREEN_OUT_COL_UNITS = ['m', 'μg/m$^3$', '', 'm/s', 'm/s', 'm', 'm', 'm', 'm', '']
183SCREEN_OUT_COL_UNITS_DICT = dict(zip(SCREEN_OUT_COL_NAMES, SCREEN_OUT_COL_UNITS))
184"""Dict of units for the outputs to be used in the plots. For example, `'DIST': 'm'`."""
185
186
187def read(
188    fp, 
189    *, 
190    t_run=None,
191    run_inputs=None,
192):
193    """Read and extract data from a SCREEN3 run (i.e., a `SCREEN.OUT` file).
194    
195    Parameters
196    ----------
197    fp : str, pathlib.Path
198        File path to the `SCREEN.OUT` file,
199        e.g., `'./screen3/SCREEN.OUT'`.
200    t_run : datetime.datetime
201        Time of the run.
202        If the output file (`SCREEN.OUT`) is older than this, the run did not complete successfully.
203    run_inputs : dict, optional
204        `run` passes this so that we can store what the inputs to the Python function were for this run,
205        though `SCREEN.OUT` should have much of the same info.
206
207    Returns
208    -------
209    df : pd.DataFrame
210        SCREEN3 output dataset.
211
212        If the pandas version has [`attrs`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.attrs.html),
213        `df.attrs` will include the following:
214        * `'units'`: (dict) *keys*: the variables names, *values*: unit strings (for use in plots)
215        * `'SCREEN_OUT'`: (str) the SCREEN3 output file as a string
216        * `'SCREEN_DAT'`: (str) the SCREEN3 DAT (copied inputs) file as a string
217        * `'run_inputs'`: (dict) copy of the inputs to the the `run` function used to generated this dataset (if applicable)
218    """
219    import datetime
220    
221    import pandas as pd
222
223    if run_inputs is None:
224        run_inputs = {}
225
226    # If we have `t_run`, first check that the file has indeed been modified
227    p = Path(fp)
228    t_out_modified = datetime.datetime.fromtimestamp(p.stat().st_mtime)
229    if t_run is not None and p.is_file():  # i.e., t_run has been specified
230        if (t_run - t_out_modified) > datetime.timedelta(seconds=1):  
231            raise ValueError(
232                "`SCREEN.OUT` is older than time of the run."
233                " This probably means that SCREEN failed to run because it didn't like the value of one or more inputs."
234                " Or some other reason.")
235
236    # Read lines
237    with open(fp, 'r') as f:
238        lines_raw = f.readlines()
239    lines_stripped = [line.strip() for line in lines_raw]
240
241    # TODO: could also read other info from the file like the run settings at the top
242
243    iheader = [i for i, s in enumerate(lines_stripped) if s.split()[:2] == ['DIST', 'CONC']]
244    if not iheader:
245        raise ValueError(
246            "Data table not found in output. "
247            "This probably means that SCREEN failed to complete the run because "
248            "it didn't like the value of one or more inputs. "
249            "Or some other reason."
250        )
251
252    if len(iheader) > 1:
253        print(f"Multiple sets of data found. Only loading the first one.")
254    iheader = iheader[0]
255
256    # Find first blank after iheader
257    iblankrel = lines_stripped[iheader:].index("")
258    iblank = iheader + iblankrel
259
260    # Could (technically) read these from file instead
261    col_names = SCREEN_OUT_COL_NAMES
262    col_units = SCREEN_OUT_COL_UNITS
263
264    # Load into pandas
265    # Note: at some point `pd.read_table` was deprecated but seems like that was undone?
266    n_X = iblank - iheader - 2
267    df = pd.read_table(fp, 
268        sep=None, skipinitialspace=True, engine='python',
269        keep_default_na=False,
270        skiprows=iheader+2, nrows=n_X)
271    df.columns = col_names
272    
273    units_dict = dict(zip(col_names, col_units))
274
275    p_dat = p.parents[0] / f'{p.stem}.DAT'
276    try:
277        with open(p_dat, 'r') as f:
278            s_screen_dat = f.read()
279    except FileNotFoundError:
280        s_screen_dat = None
281
282    # Assign attrs to df (pandas 1.0+)
283    if hasattr(df, "attrs"):
284        df.attrs.update({
285            'SCREEN_DAT': s_screen_dat,
286            'SCREEN_OUT': ''.join(lines_raw),
287            'units': units_dict,
288            'run_inputs': run_inputs
289        })
290    
291    return df
292
293
294def run(
295    *,
296    RUN_NAME='A point-source SCREEN3 run',
297    Q=100.0,
298    HS=30.0,
299    DS=10.0,
300    VS=2.0,
301    TS=310.0,
302    TA=293.0,
303    ZR=1.0,
304    #
305    X=np.append(np.r_[1.0], np.arange(50.0, 500.0+50.0, 50.0)),
306    #
307    IMETEO=3,
308    ISTAB=4,
309    WS=5.0,  # there is a max!
310    #
311    U_or_R='R',
312    #
313    DOWNWASH_YN='N',
314    HB=30.0,  # BUILDING HEIGHT (M)
315    HL=10.0,  # MINIMUM HORIZ. BUILDING DIMENSION (M)
316    HW=20.0,  # MAXIMUM HORIZ. BUILDING DIMENSION (M)
317    #
318    exe=_DEFAULT_EXE_PATH,
319):
320    """Create SCREEN3 input file, feed it to the executable, and load the result.
321
322    .. note::
323       Inputs must be specified as keyword arguments, but can be entered in any order (non-positional).
324
325    Parameters
326    ----------
327    Q : float 
328        Emission rate (g/s).
329    HS : float 
330        Stack height (m).
331    DS : float 
332        Stack inside diameter (m).
333    VS : float 
334        Stack gas exit velocity (m/s).
335    TS : float 
336        Stack gas temperature (K).
337    TA : float 
338        Ambient air temperature (K).
339    ZR : float 
340        Receptor height above ground (flagpole receptor) (M).
341    X : array_like
342        Array of downwind distances at which to compute the outputs (m).
343    IMETEO : int, {1, 2, 3}
344        1. Full (supplying stability class + WS for each grid point), 
345           or SCREEN runs for each STAB option??...
346        2. Single stability class
347        3. Stability class + WS
348    ISTAB : int
349        Stability class.
350        1 (= A) to 6 (= F).
351    WS : float
352        Mean wind speed at 10 m (m/s).
353        .. warning::
354           The run will fail if you exceed the maximum that SCREEN3 allows!
355    U_or_R : str {'U', 'R'}
356        Urban (U) or rural (R).
357    DOWNWASH_YN : str {'Y', 'N'}
358        whether to apply building downwash calculations
359        the building dimension parameters do nothing if it is 'N'
360    HB : float
361        Building height (m).
362    HL : float
363        Minimum horizontal building dimension (m).
364    HW : float
365        Maximum horizontal building dimension (m).
366    exe : path-like
367        Path to the executable to use, e.g., as a `str` or `pathlib.Path`.
368
369    Examples
370    --------
371    Change parameters.
372    ```python
373    screen3.run(TA=310, WS=2)
374    ```
375    Specify executable to use if yours isn't in the default place (`./src/SCREEN3.exe`).
376    ```python
377    screen3.run(exe="/path/to/executable")
378    ```
379
380    Returns
381    -------
382    df : pd.DataFrame
383        Results dataset, read from the `SCREEN.OUT` by `read`.
384
385    Notes
386    -----
387    The SCREEN3 program parses the inputs and makes a copy called `SCREEN.DAT`.
388    Upon running, it produces an output file called `SCREEN.OUT`.
389    Both of these will be in the source directory, where the executable resides.
390    """
391    inputs = locals()  # collect inputs for saving in the df
392
393    import datetime
394
395    # TODO: should validate wind speed?
396
397    # Check exe is file
398    exe = Path(exe)
399    if not exe.is_file():
400        raise ValueError(
401            f"{exe.absolute()!r} does not exist or is not a file. "
402            "Use the `exe` keyword argument of this function to specify the correct path."
403        )
404
405    # Check for H changes without downwad
406    H_defaults = (30.0, 10.0, 20.0)  # keep in sync with fn defaults
407    if any(x0 != x for x0, x in zip(H_defaults, [HB, HL, HW])) and DOWNWASH_YN == 'N':
408        print("Note: You have modified a building parameter, but downwash is not enabled.")
409
410    # Check x positions
411    X = np.asarray(X)
412    if X.size > 50:
413        raise ValueError('SCREEN3 does not support inputting more than 50 distance values')
414
415    # ------------------------------------------------------
416    # Other parameters
417    # For now the user cannot set these
418    # although they are required inputs to the model
419    
420    I_SOURCE_TYPE = 'P'  # point source
421
422    # Complex terrain also currently not used
423    # (assumed flat)
424    TERRAIN_1_YN = 'N'  # complex terrain screen above stack height
425    TERRAIN_2_YN = 'N'  # simple terrain above base
426    # HTER = 10.  # MAXIMUM TERRAIN HEIGHT ABOVE STACK BASE (M)
427    # ^ not needed if not using the terrain settings
428    # at least for simple terrain, seems to just run the x positions for different heights 
429
430    # Currently user input of distances is required
431    # i.e., automated option not used
432    AUTOMATED_DIST_YN = 'N'
433    DISCRETE_DIST_YN = 'Y'
434
435    # Final questions
436    FUMIG_YN = 'N'
437    PRINT_YN = 'N'
438
439    # ------------------------------------------------------
440    # Create the input file
441
442    def s_METEO():
443        if IMETEO == 1:  # A range (depending on U/R, type of source, etc.) of WS and STABs are examined to find maximum impact
444            # print(f"* Note that IMETEO={IMETEO!r} isn't really implemented presently..."
445            #     "\nExamine the WS and STAB in the model output to see what happened.")
446            return '1'
447        elif IMETEO == 2:
448            return f'{IMETEO}\n{ISTAB}'
449        elif IMETEO == 3:
450            return f'{IMETEO}\n{ISTAB}\n{WS}'
451        else:
452            raise ValueError(f'invalid `IMETEO` {IMETEO!r}. Must be in {{1, 2, 3}}')            
453
454    def s_X():
455        vals = X.astype(str).tolist()
456        return '\n'.join(vals + ['0.0'])
457
458    def s_building_props():
459        if DOWNWASH_YN == 'Y':
460            return f'{HB}\n{HL}\n{HW}'
461        else:
462            return ""
463
464    dat_text = f"""
465{RUN_NAME}
466{I_SOURCE_TYPE}
467{Q}
468{HS}
469{DS}
470{VS}
471{TS}
472{TA}
473{ZR}
474{U_or_R}
475{DOWNWASH_YN}
476{s_building_props()}
477{TERRAIN_1_YN}
478{TERRAIN_2_YN}
479{s_METEO()}
480{AUTOMATED_DIST_YN}
481{DISCRETE_DIST_YN}
482{s_X()}
483{FUMIG_YN}
484{PRINT_YN}
485    """.strip() + "\n"
486    # ^ need newline at end or Fortran complains when passing text on the cl
487
488    # TODO: optionally write the input text file to disk in cwd
489    # ifn = 'screen3_input.txt'  # input filename
490    # ifp = cwd / ifn
491    # with open(ifn, 'w') as f: 
492    #     f.write(dat_text)
493
494    # ------------------------------------------------------
495    # Run the SCREEN executable
496
497    t_utc_run = datetime.datetime.now()
498
499    s_exe = str(exe.absolute())
500    cwd = Path.cwd()
501    src_dir = exe.parent
502
503    # Move to src location so that the output file will be saved there
504    os.chdir(src_dir)
505
506    # Invoke executable
507    subprocess.run(
508        args=[s_exe],
509        input=dat_text,
510        universal_newlines=True,  # equivalent to `text=True`, but that was added in 3.7
511        check=True,
512        shell=True,
513        stdout=subprocess.DEVNULL,
514        stderr=subprocess.STDOUT,
515    )
516
517    # Return to cwd
518    os.chdir(cwd)
519
520    # Read and parse the output
521    df = read(src_dir/'SCREEN.OUT', t_run=t_utc_run, run_inputs=inputs)
522
523    return df
524
525
526def _add_units(x_units, y_units, *, ax=None):
527    """Add units and make room."""
528    import matplotlib.pyplot as plt
529
530    if ax is None:
531        ax = plt.gca()
532    xl = ax.get_xlabel()
533    yl = ax.get_ylabel()
534    sxu = f'({x_units})' if x_units else ''
535    syu = f'({y_units})' if y_units else ''
536    ax.set_xlabel(f'{xl} {sxu}' if xl else sxu)
537    ax.set_ylabel(f'{yl} {syu}' if xl else syu)
538
539
540def plot(
541    df, 
542    *, 
543    labels=None,
544    yvals=None,
545    yvar="",
546    yvar_units="",
547    plot_type='line', 
548    ax=None,
549    **pyplot_kwargs):
550    """Plot concentration.
551
552    The first argument (positional) can be one `df` or a list of `df`s. 
553    If you pass a list of `df`s, you can also pass `labels`. 
554
555    The default plot type is `'line'`, but 2-D plots `'pcolor'` and `'contourf'` are also options. 
556    Unless you additionally pass `yvals`, they will be plotted as if the labels were equally spaced. 
557
558    Parameters
559    ----------
560    df : pd.DataFrame or list of pd.DataFrame
561        Data extracted from the `SCREEN.OUT` of the run(s) using `read`.
562    labels : array_like
563        Labels for the separate cases.
564        Used if input `df` is a list instead of just one dataset.
565        Currently we assume that the first part of the label is the variable name that is being varied.
566    yvals : array_like
567        Optional positions of labels.
568    yvar : str
569        *y* variable name.
570        Only used if labels not provided.
571    yvar_units : str
572        Units to use when labeling `yvar`.
573        Only used if `labels` not provided.
574    plot_type : str {'line', 'pcolor', 'contourf'}
575        The type of plot to do.
576    ax : plt.Axes
577        If an existing ax is not passed, we create a new figure (and ax).
578        Else, we plot on the existing ax.
579    **pyplot_kwargs
580        Passed on to the relevant pyplot plotting function,
581        e.g., `ax.plot`.
582    """
583    import matplotlib as mpl
584    import matplotlib.pyplot as plt
585    import pandas as pd
586
587    if labels is None:
588        labels = []
589    if yvals is None:
590        yvals = []
591
592    units = SCREEN_OUT_COL_UNITS_DICT
593    # or `df.attrs['units']`
594
595    if not isinstance(df, (pd.DataFrame, list)):
596        raise TypeError(f"df is not a `pd.DataFrame` or `list`, it is type `{type(df).__name__}`")
597
598    if plot_type not in ['line', 'pcolor', 'contourf']:
599        raise ValueError(f"`plot_type` {plot_type!r} not allowed")
600
601    if ax is None or not isinstance(ax, plt.Axes):
602        fig, ax = plt.subplots()
603    else:
604        fig = plt.gcf()
605
606    # determine number of points
607    if isinstance(df, list):
608        n = df[0].index.size
609    else:
610        n = df.index.size
611    
612    # some line styling
613    if n > 20:
614        line_style = '.-'
615        ms = 6
616    else:
617        line_style = 'o-'
618        ms = 5
619    pyplot_kwargs.update({
620        'markersize': ms
621    })
622
623    if isinstance(df, list):
624        if not list(labels):
625            labels = list(range(1, len(df)+1))
626    
627        if plot_type == 'line':
628            with mpl.rc_context({'legend.fontsize': 'small'}):
629                for i, dfi in enumerate(df):
630                    dfi.plot(x='DIST', y='CONC', style=line_style, ax=ax, label=labels[i], **pyplot_kwargs) 
631        
632        else:  # 2-D plot options
633            ax.set_xlabel('DIST')
634            yvals = np.asarray(yvals)
635            if yvals.any():
636                Y = yvals
637
638                # yvar_guess = labels[0].split()[0]
639                # try:
640                #     yvar_units = units[yvar_guess]
641                # except KeyError:
642                #     raise ValueError(f"Y variable guess {yvar_guess!r} based on labels passed not found in allowed list."
643                #         " Make sure that the first part of each label is the variable, followed by a space.")
644                # ax.set_ylabel(yvar_guess)
645
646                if labels:
647                    ax.set_yticks(yvals)
648                    ax.set_yticklabels(labels)
649
650                ax.set_ylabel(yvar)
651                _add_units(units['DIST'], yvar_units, ax=ax)
652
653            else:
654                Y = labels
655                _add_units(units['DIST'], '', ax=ax)
656
657            X = df[0].DIST
658            # Y = yvals if yvals.any() else labels
659            Z = np.stack([dfi['CONC'] for dfi in df])
660
661            if plot_type == 'pcolor':
662                im = ax.pcolormesh(X, Y, Z, **pyplot_kwargs)
663
664            elif plot_type == 'contourf':
665                im = ax.contourf(X, Y, Z, **pyplot_kwargs)
666            
667            cb = fig.colorbar(im)
668
669            cb.set_label(f"CONC ({units['CONC']})")
670
671    else:  # just one to plot
672        if plot_type != 'line':
673            raise ValueError("With only one run, only `plot_type` 'line' can be used")
674        df.plot(x='DIST', y='CONC', style=line_style, ax=ax, **pyplot_kwargs)
675
676    if plot_type == 'line':
677        ax.set_ylabel('CONC')
678        _add_units(units['DIST'], units['CONC'], ax=ax)  # use the units dict to look up the units
679
680        # ax.set_xlim(xmin=0, xmax=)
681        ax.autoscale(axis='x', tight=True)
682
683    fig.tight_layout()
684
685    return fig
686
687
688def load_example(s, *, src=DEFAULT_SRC_DIR):
689    """Load one of the examples included with the `screen3.zip` download,
690    such as `'EXAMPLE.OUT'` from SCREEN3 source directory `src`.
691
692    Examples
693    --------
694    ```python
695    screen3.load_example("EXAMPLE.OUT")
696    ```
697    """
698    valid_examples = [
699        "EXAMPLE.OUT", "examplenew.out", "examplnrnew.out",
700        "EXAMPNR.OUT", "exampnrnew.out",
701    ]
702    if s not in valid_examples:
703        raise ValueError(f"invalid example file name. Valid options are: {valid_examples}")
704
705    return read(Path(src) / s)