Reference

def setup(cls, server: str, project: str, tab: int):
    '''
    Initialize the connection to the OptiPass server.  Connect to the
    server, get the barrier file and other data for the project, save
    it in read-only class variables.

    Raises an exception if the server is not accessible or if the project
    name is not known to the server.

    Arguments:
      server: the URL of an OptiPass REST server
      project: the name of a data set on the server
      tab: the tab to show when starting the app
    '''
    logging.info(f'Connecting to {server}')

    req = f'{server}/projects'
    logging.info(f'request: {req}')
    resp = requests.get(req)
    if resp.status_code == 502:
        raise requests.exceptions.ConnectionError()
    elif resp.status_code != 200:
        raise OPServerError(resp)
    elif project not in resp.json():
        raise ValueError(f'unknown project: {project}')
    cls._server_url = server
    cls._project_name = project

    req = f'{server}/targets/{project}'
    resp = requests.get(req)
    if resp.status_code != 200:
        raise OPServerError(resp)
    dct = resp.json()
    buf = StringIO(dct['targets'])
    cls._target_frame = pd.read_csv(buf).set_index('abbrev')
    cls._target_layout = dct['layout'].strip().split('\n')

    req = f'{server}/colnames/{project}'
    resp = requests.get(req)
    if resp.status_code != 200:
        raise OPServerError(resp)
    dct = resp.json()
    cls._mapping_name = dct['name']
    cls._target_columns = dct['files']

    req = f'{server}/mapinfo/{project}'
    resp = requests.get(req)
    if resp.status_code != 200:
        raise OPServerError(resp)
    cls._mapinfo = json.loads(resp.json()['mapinfo'])

    req = f'{server}/barriers/{project}'
    resp = requests.get(req)
    if resp.status_code != 200:
        raise OPServerError(resp)
    buf = StringIO(resp.json()['barriers'])
    cls._barrier_frame = pd.read_csv(buf).set_index('ID')

    total_cost = cls._barrier_frame[['region','cost']].groupby('region').sum()
    cls._region_names = sorted(list(total_cost.index))
    cls._total_cost = { r[0]: r[1].cost for r in total_cost.iterrows() }

    cls._initial_tab = tab

    logging.info('setup complete')

@staticmethod
def url_for_figure(fn: str) -> str:
    '''
    Return the URL to use to fetch an image from the server.

    Arguments:
      fn: the file name of the image

    Returns:
      the URL
    '''
    return f'{OP.server_url}/static/images/'

@staticmethod
def format_budgets(cols: list[int]) -> dict[int,str]:
    '''
    Create a dictionary that maps budget values to abbreviated
    dollar amounts.

    Arguments:
      cols: the list of budget amounts

    Returns:
      dictionary 
    '''
    return { n: OP.format_budget_amount(n) for n in cols }

@staticmethod
def format_budget_amount(n: int) -> str:
    '''
    Convert an integer dollar amount into an abbreviation, e.g.
    100000 becomes "$100K" and 2500000 becomes "$2.5M".

    Arguments:
      n: the amount to convert

    Returns:
      the abbreviation
    '''
    divisor, suffix = OP.dollar_format['mil'] if n >= 1000000 else OP.dollar_format['thou']
    s = '${:}'.format(n/divisor)
    if s.endswith('.0'):
        s = s[:-2]
    return s+suffix

@staticmethod
def fetch_html_file(fn: str) -> str:
    '''
    Fetch an HTML file from the server.

    Arguments:
      fn:  the name of the file

    Returns:
      the contents of the file, as a single string
    '''
    req = f'{OP.server_url}/html/{OP.project_name}/{fn}'
    resp = requests.get(req)
    if resp.status_code != 200:
        raise OPServerError(resp)
    return resp.json()

@staticmethod
def run_optimizer(
    regions: list[str],
    budgets: tuple[str,str],
    targets: list[str],
    weights: list[int],
    mapping: str | None,       
    ):
    '''
    Send a request to the op-server to run OptiPass using settings
    from the widgets.

    Args:
        regions: a list of geographic regions (river names) to use
        budgets: a tuple with budget settings (start, increment, count)
        targets: a list of IDs of targets
        weights: a list of target weights
        mapping: the name of a column mapping file for targets

    Returns:
        summary: data frame with one row per budget level
        matrix:  data frame with one row per barrier
    '''
    req = f'{OP.server_url}/optipass/{OP.project_name}'
    args = {
        'regions': regions,
        'budgets': budgets,
        'targets': targets,
        'weights': weights or None,
        'mapping': [OP.mapping_name,mapping],
    }
    if token := DevOP.results_dir():
        args['tempdir'] = token

    resp = requests.get(req, args)
    if resp.status_code != 200:
        raise OPServerError(resp)

    dct = resp.json()
    buf = StringIO(dct['summary'])
    summary = pd.read_csv(buf)
    buf = StringIO(dct['matrix'])
    matrix = pd.read_csv(buf).set_index('ID')

    return summary, matrix

def make_roi_curves(self):
    """
    Generate ROI plots based on computed benefits.
    """

    climate = None

    subtitle = 'Region: ' if len(self.regions) == 1 else 'Regions: '
    subtitle +=  ', '.join(self.regions)

    for i, t in enumerate(self.targets):
        target = OP.target_frame.loc[t]
        title = target.long
        if target.infra:
            title += f' ({self.mapping} {OP.mapping_name})'
        f = self.bokeh_figure(self.summary.budget, self.summary[target.name], title, subtitle, target.label)
        self.display_figures.append((target.short, f))
        f = self.pyplot_figure(self.summary.budget, self.summary[target.name], title, subtitle, target.label)
        self.download_figures.append((target.short, f))

    if len(self.targets) > 1:
        title = 'Combined Potential Benefit'
        if climate:
            title += f' ({OP.mapping} {OP.mapping_name})'
        if self.weights:
            subtitle += '\nTargets:'
            for i, t in enumerate(self.targets):
                target = OP.target_frame.loc[t]
                subtitle += f' {target.short} ⨉ {int(self.weights[i])}'
        f = self.bokeh_figure(self.summary.budget, self.summary.netgain, title, subtitle, 'Weighted Net Gain')
        self.display_figures.insert(0, ('Net', f))
        f = self.pyplot_figure(self.summary.budget, self.summary.netgain, title, subtitle, 'Weighted Net Gain')
        self.download_figures.insert(0, ('Net', f))

def budget_table(self):
    """
    Make a table that has one column for each budget level, showing
    which barriers were included in the solution for that level. 
    """
    df = self.summary[['budget', 'gates']]
    colnames = ['Budget', 'gates']
    df = pd.concat([
        df,
        pd.Series(self.summary.gates.apply(len))
    ], axis=1)
    colnames.append('# Barriers')
    for i, t in enumerate(self.targets):
        target = OP.target_frame.loc[t]
        if target.name in self.summary.columns:
            df = pd.concat([df, self.summary[target.name]], axis=1)
            col = target.short
            # if self.weights:
            #     col += f'⨉{self.weights[i]}'
            colnames.append(col)
    df = pd.concat([
        df,
        self.summary[['wph','netgain']]
    ], axis=1)
    colnames += ['WPH','Net Gain']
    df.columns = colnames
    return df

def gate_table(self):
    """
    Make a table that has one row per gate with columns that are relevant
    to the output display
    """
    filtered = OP.barrier_frame[OP.barrier_frame.region.isin(self.regions)]

    col1 = [c for c in ['region','cost','DSID','type'] if c in filtered.columns]
    budget_cols = [c for c in self.matrix.columns if c.isnumeric() and c > '0']
    target_cols = [c for c in self.matrix.columns if len(c) == 2]
    col2 = [c for c in ['primary','dominant','X','Y'] if c in filtered.columns]

    df = pd.concat([
        filtered[col1],
        self.matrix[budget_cols],
        self.matrix['count'],
        self.matrix[target_cols],
        filtered[col2]
    ], axis=1)

    df = df[df['count'] > 0].sort_values(by='count', ascending=False).fillna('-')
    df.columns = [s.capitalize() if s in ['region','cost','type','primary','dominant'] else s for s in df.columns]

    return df

@staticmethod
def default_list(varname):
    '''
    Split the value of an environment variable into a list
    '''
    if lst := os.getenv(varname):
        return lst.split(':')
    return []

@staticmethod
def default_regions():
    '''
    Return the value of OPREGIONS
    '''
    return DevOP.default_list('OPREGIONS')

@staticmethod
def default_budget():
    '''
    Return the value of OPBUDGET
    '''
    return int(os.getenv('OPBUDGET','0'))

@staticmethod
def default_targets():
    '''
    Return the value of OPTARGETS
    '''
    return DevOP.default_list('OPTARGETS')

@staticmethod
def results_dir():
    '''
    Return the value of OPTMPDIR
    '''
    return os.getenv('OPTMPDIR')