pcmiler 0.1.8
pcmiler wrapper python package
License: MIT

[![PyPI Latest Release](https://img.shields.io/pypi/v/pcmiler)](https://pypi.org/project/pcmiler/)
![Python package](https://github.com/nfi-engineering/pcmiler/workflows/Python%20package/badge.svg)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
<a href="https://pepy.tech/project/pcmiler"><img alt="Downloads" src="https://pepy.tech/badge/pcmiler"></a>

# pcmiler

A python package for getting the most out of PCMiler products.

## Install

### `pip install pcmiler`

## BatchPro Configuration

Configuration is set up based on your input data format and the PCMiler BatchPro installation on your computer. `pcmiler` will search your `c:` drive for `batchw32.exe`. If found it will configure the setup according to its path. Otherwise the defualt setup would be set to the following:

```yml
exe: "C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/batchw32.exe"
infile: "C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/df.IN"
cfgfile: "C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/df.CFG"
outfile: "C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/df.OUT"
logfile: "C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/df.LOG"
origin:
    origin_city: "origin_city"
    origin_state: "origin_state"
    origin_street: "origin_street"
    origin_zipcode: "origin_zipcode"
    origin_country: "origin_country"
destination:
    dest_city: "dest_city"
    dest_state: "dest_state"
    dest_street: "dest_street"
    dest_zipcode: "dest_zipcode"
    dest_country: "dest_country"
strfmt: "1, omax, omax + 2, dmax + 2, max_city_len"
```

See [pcmiler.com/about](https://www.pcmiler.com/about/) for more on products available and licensing information. You must have PCMiler BatchPro installed on your machine to use `pcmiler`.

## BatchPro and `pandas`

```python
import pandas as pd
from pcmiler import batchpro

# dataframes formatted to follow default configuration
df = pd.DataFrame({
        "origin_city": [],
        "origin_state": [],
        "origin_zip": [],
        "origin_street": [],
        "origin_country": [],
        "dest_city": [],
        "dest_state": [],
        "dest_zip": [],
        "dest_street": [],
        "dest_country": [],
    }
))

df["miles"] = batchpro.miles_series(df=df)
```

You can update these settings using `pcmiler.batchpro.config` or `pcmiler.batchpro.update_config()`.

```python
from pcmiler import batchpro

# tweak default config
config = batchpro.config(origin={"city": "new col"})

# update config
config = batchpro.update_config(config, {"exe": ""})

df["miles"] = batchpro.miles_series(df=df, config=config)
```

Use your `config` for more control.

```python
config = batchpro.config(
    exe="", # path to .exe
    infile="", # path to .IN
    cfgfile="",  # path to .cfg
    origin={
        "city": "",
        "state": "",
        "street": "",
        "zipcode": "",
        "country": ""
    },
    destination={
        "city": "",
        "state": "",
        "street": "",
        "zipcode": "",
        "country": ""
    },

    # character positions for [ostart, oend, dstart, dend, max_city_len]
    # without config it defaults to [1, omax, omax + 2, omax + dmax + 2, city length]
    # NOTE: " " separates origin strings from destination strings
    strfmt=[],
)

df["miles"] = batchpro.miles_series(df=df, config=config)
```

Another approach would be

```python
from pcmiler import batchpro

origins = batchpro.locstr_series(
    df,
    zip_col="origin_zip",
    address_cols=["origin_city", "origin_state", "origin_street"]
)
dests = batchpro.locstr_series(
    df,
    zip_col="dest_zip",
    address_cols=["dest_city", "dest_state", "dest_street"]
)

df["miles"] = batchpro.miles_series(origins=origins, destinations=dests)
```

## Minimum input data

Minimum data BatchPro needs is *City-State* or *Zipcode*. It is reccommended to add *Country*.

## `pcmiler.batchpro.search_for_exe(_dir: str = "c:/")`

`pcmiler.batchpro.search_for_exe()` is used to search for the full `batchw32.exe` path. Default behavior is to perform the search in the `c:` drive if no config is provided. If it is not found then `C:/ALK Technologies/<PCMILER VERSION DIR>/Batchpro/batchw32.exe` is used.

## CLI for csv and excel files

Create a `pcmiler.yaml` in your current working directory. The full configuration ~~is~~ will (#18) be available through this method as well.

```yaml
exe: "path/to/batchw32.exe"
sheet: "sheet name if excel"
origin:
    zipcode: "zipcode column name"
    city: "city column name"
    state: "state column name"
    street: "street column name"
destination:
    zipcode: "zipcode column name"
    city: "city column name"
    state: "state column name"
    street: "street column name"
```

Run `pcmiler path/to/file`. You can also run `pcmiler-gui` to select a file manually.

### more cli

- `--create-yaml` to create a `pcmiler.yaml` in the current working directory.
- `--debug`

### .LOG summaries

See run statistics and settings from Batchpro's `.LOG` file.

```log

$ pcmiler batch.csv
11/14/2020 06:27:58 PM | found c:\ALK Technologies\PCMILER29\Batchpro\batchw32.exe
11/14/2020 06:27:58 PM | preparing batch.csv
11/14/2020 06:27:58 PM | running Batchpro
11/14/2020 06:28:02 PM |
--SUMMARY STATISTICS--

Chunk Size                       : 2000
Calculated Sort Size        : 80000
SortChunk on=1 off=0    : 1

Started Processing               : Sat Nov 14 18:28:01 2020
Finished Processing              : Sat Nov 14 18:28:02 2020
Total Processing Time            : 0:00:01

Total number of O/D pairs        : 2
Number of O/D pairs processed    : 2
Number of errors                 : 0
Number of routes successfully run: 2
Number of pairs/second           : 2.00

In File Format                   : PCMSave, 1, 34, 36, 70, 40

-----USER OPTIONS-----

Region             - NA

Route Type         - Practical
Reports            - Out
City/Zip Routing   - Use Local Streets
Additional Options - Borders Open
FavorOneWayDivided- Yes
Distance Units     - Miles

11/14/2020 06:28:02 PM | saving results to C:\Users\pryerc\github\pcmiler\tests\pcmiler-batch.csv
```