r2sfca

Name	r2sfca JSON
Version	1.1.3 JSON
	download
home_page	https://github.com/urbananalytics/r2sfca
Summary	Reconciled Two-Step Floating Catchment Area Model for spatial accessibility analysis
upload_time	2025-10-14 00:57:33
maintainer	None
docs_url	None
author	Lingbo Liu, Fahui Wang
requires_python	>=3.8
license	MIT License Copyright (c) 2025 Lingbo Liu, Fahui Wang Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	spatial analysis accessibility 2sfca i2sfca gis urban analytics
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # r2SFCA: Reconciled Two-Step Floating Catchment Area Model

A Python package for spatial accessibility analysis that reconciles 2SFCA and i2SFCA methods through distance decay parameterization and cross-entropy minimization.

**Authors:** Lingbo Liu (lingboliu@fas.harvard.edu), Fahui Wang (fwang@lsu.edu)

## Overview

The r2SFCA package implements a unified framework for spatial accessibility analysis that:

- Reconciles demand-side (2SFCA) and supply-side (i2SFCA) accessibility measures
- Optimizes distance decay parameters through cross-entropy minimization
- Supports multiple decay functions with configurable parameters
- Provides comprehensive evaluation metrics and visualization tools
- Enables grid search and Adam optimization for parameter estimation

## Installation

```bash
pip install r2sfca
```

## Quick Start

```python
import pandas as pd
from r2sfca import R2SFCA

# Load your spatial accessibility data
df = pd.read_csv('your_data.csv')

# Initialize the R2SFCA model
model = R2SFCA(
    df=df,
    demand_col='Demand',
    supply_col='Supply',
    travel_cost_col='TravelCost',
    demand_id_col='DemandID',
    supply_id_col='SupplyID',
    observed_flow_col='O_Fij',  # Optional, for validation
    decay_function='exponential'
)

# Calculate accessibility and crowdedness scores
accessibility = model.access_score(beta=2.5)
crowdedness = model.crowd_score(beta=2.5)

# Perform grid search to find optimal parameters
results = model.search_fij(
    beta_range=(0.0, 5.0, 0.1),
    # param2_range = (10, 20.0, 5.0),#optional for sigmoid and gaussian function
    # either parameter can be a fixed value
    metrics=['cross_entropy', 'correlation', 'rmse']
)

# Optimize parameters using Adam optimizer
optimization_result = model.solve_beta(
    metric='cross_entropy',
    # param2=20.0, #optional for sigmoid and gaussian function
    method='adam',
    num_epochs=400
)
```

## Data Requirements

Your input dataframe should contain the following columns:

- **Demand**: Demand values (e.g., population)
- **Supply**: Supply values (e.g., service capacity)
- **TravelCost**: Travel cost/distance between demand and supply locations
- **DemandID**: Unique identifiers for demand locations
- **SupplyID**: Unique identifiers for supply locations
- **O_Fij** (optional): Observed flow values for model validation

## Decay Functions

The package supports six distance decay functions:

### 1. Exponential Decay
```python
f(d) = exp(-β * d)
```

### 2. Power Decay
```python
f(d) = d^(-β)
```

### 3. Sigmoid Decay
```python
f(d) = 1 / (1 + exp(steepness * (d - β)))
```

### 4. Square Root Exponential Decay
```python
f(d) = exp(-β * sqrt(d))
```

### 5. Gaussian Decay
```python
f(d) = exp(-β * (d/d0)²)
```

### 6. Log-Squared Decay
```python
f(d) = exp(-β * log(d)²)
```

## API Reference

### R2SFCA Class

#### Constructor
```python
R2SFCA(df, demand_col, supply_col, travel_cost_col, demand_id_col, supply_id_col, 
       observed_flow_col=None, decay_function='exponential', epsilon=1e-15)
```

#### Methods

##### `dist_decay(beta, **kwargs)`
Calculate distance decay values using the specified decay function.

**Parameters:**
- `beta`: Primary decay parameter
- `**kwargs`: Additional parameters (steepness for sigmoid, d0 for gaussian)

**Note:** Uses the travel_cost data stored in the model during initialization.

**Returns:** Decay values

##### `fij(beta, **kwargs)`
Calculate Fij values (demand-side accessibility) using 2SFCA method.

**Parameters:**
- `beta`: Decay parameter
- `**kwargs`: Additional parameters for decay function

**Returns:** Fij values

##### `tij(beta, **kwargs)`
Calculate Tij values (supply-side accessibility) using i2SFCA method.

**Parameters:**
- `beta`: Decay parameter
- `**kwargs`: Additional parameters for decay function

**Returns:** Tij values

##### `search_fij(beta_range, param2_range=None, metrics=None, normalize=True)`
Perform grid search over parameter ranges to find optimal values.

**Parameters:**
- `beta_range`: (start, end, step) for beta parameter
- `param2_range`: (start, end, step) for second parameter
- `metrics`: List of evaluation metrics to calculate
- `normalize`: Whether to normalize Fij and Tij for cross-entropy calculation

**Returns:** DataFrame with grid search results

##### `solve_beta(metric='cross_entropy', param2=None, method='minimize', **kwargs)`
Solve for optimal beta parameter using optimization.

**Parameters:**
- `metric`: Metric to optimize
- `param2`: Second parameter value
- `method`: Optimization method ('minimize' or 'adam')
- `**kwargs`: Additional optimization parameters

**Returns:** Dictionary with optimization results

##### `access_score(beta, **kwargs)`
Calculate accessibility scores (Ai) for each demand location.

**Parameters:**
- `beta`: Decay parameter
- `**kwargs`: Additional parameters for decay function

**Returns:** Series with accessibility scores

##### `crowd_score(beta, **kwargs)`
Calculate crowdedness scores (Cj) for each supply location.

**Parameters:**
- `beta`: Decay parameter
- `**kwargs`: Additional parameters for decay function

**Returns:** Series with crowdedness scores

## Evaluation Metrics

The package provides several evaluation metrics:

- **Cross Entropy**: Measures the difference between Fij and Tij distributions
- **Correlation**: Pearson correlation coefficient between Fij and Tij
- **RMSE**: Root Mean Square Error
- **MSE**: Mean Square Error
- **MAE**: Mean Absolute Error
- **Fij-Flow Correlation**: Correlation between estimated Fij and observed flows
- **Tij-Flow Correlation**: Correlation between estimated Tij and observed flows

## Visualization

### Grid Search Results
```python
from r2sfca.utils import plot_grid_search_results

# Plot grid search results
fig = plot_grid_search_results(
    results_df=results,
    x_col='beta',
    y_cols=['cross_entropy', 'correlation'],
    title='Grid Search Results',
    save_path='grid_search.png'
)
```

### Model Comparison
```python
from r2sfca.utils import plot_model_comparison

# Compare multiple models
fig = plot_model_comparison(
    results_dfs=[results1, results2, results3],
    labels=['Gaussian', 'Exponential', 'Power'],
    y_col='fij_flow_correlation',
    title='Model Comparison',
    save_path='model_comparison.png'
)
```

### Summary Table
```python
from r2sfca.utils import create_summary_table

# Create summary table
summary = create_summary_table(
    results_dfs=[results1, results2, results3],
    labels=['Gaussian', 'Exponential', 'Power'],
    metric='cross_entropy',
    minimize=True
)
```

## Examples

### Example 1: Basic Usage
```python
import pandas as pd
import numpy as np
from r2sfca import R2SFCA

# Create sample data
np.random.seed(42)
n_demand = 100
n_supply = 50

data = []
for i in range(n_demand):
    for j in range(n_supply):
        data.append({
            'DemandID': i,
            'SupplyID': j,
            'Demand': np.random.poisson(1000),
            'Supply': np.random.poisson(100),
            'TravelCost': np.random.exponential(10),
            'O_Fij': np.random.poisson(50)
        })

df = pd.DataFrame(data)

# Initialize model
model = R2SFCA(
    df=df,
    demand_col='Demand',
    supply_col='Supply',
    travel_cost_col='TravelCost',
    demand_id_col='DemandID',
    supply_id_col='SupplyID',
    observed_flow_col='O_Fij',
    decay_function='gaussian'
)

# Calculate accessibility scores
accessibility = model.access_score(beta=2.0)
print(f"Accessibility scores: {accessibility.describe()}")
```

### Example 2: Parameter Optimization
```python
# Grid search
results = model.search_fij(
    beta_range=(0.0, 5.0, 0.2),
    metrics=['cross_entropy', 'correlation', 'rmse']
)

# Find optimal beta
optimal_idx = results['cross_entropy'].idxmin()
optimal_beta = results.loc[optimal_idx, 'beta']
print(f"Optimal beta: {optimal_beta}")

# Adam optimization
optimization_result = model.solve_beta(
    metric='cross_entropy',
    method='adam',
    num_epochs=200
)
print(f"Optimized beta: {optimization_result['optimal_beta']}")
```

### Example 3: Model Comparison
```python
# Compare different decay functions
decay_functions = ['exponential', 'power', 'gaussian', 'sigmoid']
results_list = []
labels = []

for decay_func in decay_functions:
    model_temp = R2SFCA(
        df=df,
        demand_col='Demand',
        supply_col='Supply',
        travel_cost_col='TravelCost',
        demand_id_col='DemandID',
        supply_id_col='SupplyID',
        observed_flow_col='O_Fij',
        decay_function=decay_func
    )
    
    results = model_temp.search_fij(
        beta_range=(0.0, 3.0, 0.1),
        metrics=['cross_entropy', 'fij_flow_correlation']
    )
    
    results_list.append(results)
    labels.append(decay_func.title())

# Plot comparison
from r2sfca.utils import plot_model_comparison

fig = plot_model_comparison(
    results_dfs=results_list,
    labels=labels,
    y_col='fij_flow_correlation',
    title='Decay Function Comparison'
)
```

## Advanced Usage

### Custom Decay Function Parameters
```python
# Gaussian decay with custom d0 parameter
model = R2SFCA(df, decay_function='gaussian')
fij = model.fij(beta=2.0, d0=30.0)  # Custom d0 value

# Sigmoid decay with custom steepness
model = R2SFCA(df, decay_function='sigmoid')
fij = model.fij(beta=1.5, steepness=5.0)  # Custom steepness
```

### Multiple Parameter Optimization
```python
# Grid search with second parameter
results = model.search_fij(
    beta_range=(0.0, 3.0, 0.1),
    param2_range=(1.0, 10.0, 0.5),  # For sigmoid steepness
    metrics=['cross_entropy', 'correlation']
)
```

### Custom Evaluation Metrics
```python
# Use custom metrics
results = model.search_fij(
    beta_range=(0.0, 3.0, 0.1),
    metrics=['cross_entropy', 'rmse', 'mae', 'fij_flow_correlation']
)
```

## Performance Considerations

- For large datasets, consider using the Adam optimizer instead of grid search
- The package uses vectorized operations for efficiency
- Memory usage scales with the number of demand-supply pairs
- Consider sampling for very large datasets during parameter optimization

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Citation

If you use this package in your research, please cite:

```
@article{r2sfca2025,
   author = {Liu, Lingbo and Wang, Fahui},
   title = {Reconciling 2SFCA and i2SFCA via distance decay parameterization},
   journal = {International Journal of Geographical Information Science},
   pages = {1-18},
   note = {doi: 10.1080/13658816.2025.2562255},
   ISSN = {1365-8816},
   DOI = {10.1080/13658816.2025.2562255},
   url = {https://doi.org/10.1080/13658816.2025.2562255},
   year = {2025},
   type = {Journal Article}
}
```

## Support

For questions and support, please open an issue on GitHub or contact the development team.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/urbananalytics/r2sfca",
    "name": "r2sfca",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Lingbo Liu <lingboliu@harvard.edu>, Fahui Wang <fwang@lsu.edu>",
    "keywords": "spatial analysis, accessibility, 2SFCA, i2SFCA, GIS, urban analytics",
    "author": "Lingbo Liu, Fahui Wang",
    "author_email": "Lingbo Liu <lingboliu@harvard.edu>, Fahui Wang <fwang@lsu.edu>",
    "download_url": "https://files.pythonhosted.org/packages/77/0d/2428323bf239e36c38d032a709275801c9fb6c30ef8e57ff813299d7d1d3/r2sfca-1.1.3.tar.gz",
    "platform": null,
    "description": "# r2SFCA: Reconciled Two-Step Floating Catchment Area Model\r\n\r\nA Python package for spatial accessibility analysis that reconciles 2SFCA and i2SFCA methods through distance decay parameterization and cross-entropy minimization.\r\n\r\n**Authors:** Lingbo Liu (lingboliu@fas.harvard.edu), Fahui Wang (fwang@lsu.edu)\r\n\r\n## Overview\r\n\r\nThe r2SFCA package implements a unified framework for spatial accessibility analysis that:\r\n\r\n- Reconciles demand-side (2SFCA) and supply-side (i2SFCA) accessibility measures\r\n- Optimizes distance decay parameters through cross-entropy minimization\r\n- Supports multiple decay functions with configurable parameters\r\n- Provides comprehensive evaluation metrics and visualization tools\r\n- Enables grid search and Adam optimization for parameter estimation\r\n\r\n## Installation\r\n\r\n```bash\r\npip install r2sfca\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport pandas as pd\r\nfrom r2sfca import R2SFCA\r\n\r\n# Load your spatial accessibility data\r\ndf = pd.read_csv('your_data.csv')\r\n\r\n# Initialize the R2SFCA model\r\nmodel = R2SFCA(\r\n    df=df,\r\n    demand_col='Demand',\r\n    supply_col='Supply',\r\n    travel_cost_col='TravelCost',\r\n    demand_id_col='DemandID',\r\n    supply_id_col='SupplyID',\r\n    observed_flow_col='O_Fij',  # Optional, for validation\r\n    decay_function='exponential'\r\n)\r\n\r\n# Calculate accessibility and crowdedness scores\r\naccessibility = model.access_score(beta=2.5)\r\ncrowdedness = model.crowd_score(beta=2.5)\r\n\r\n# Perform grid search to find optimal parameters\r\nresults = model.search_fij(\r\n    beta_range=(0.0, 5.0, 0.1),\r\n    # param2_range = (10, 20.0, 5.0),#optional for sigmoid and gaussian function\r\n    # either parameter can be a fixed value\r\n    metrics=['cross_entropy', 'correlation', 'rmse']\r\n)\r\n\r\n# Optimize parameters using Adam optimizer\r\noptimization_result = model.solve_beta(\r\n    metric='cross_entropy',\r\n    # param2=20.0, #optional for sigmoid and gaussian function\r\n    method='adam',\r\n    num_epochs=400\r\n)\r\n```\r\n\r\n## Data Requirements\r\n\r\nYour input dataframe should contain the following columns:\r\n\r\n- **Demand**: Demand values (e.g., population)\r\n- **Supply**: Supply values (e.g., service capacity)\r\n- **TravelCost**: Travel cost/distance between demand and supply locations\r\n- **DemandID**: Unique identifiers for demand locations\r\n- **SupplyID**: Unique identifiers for supply locations\r\n- **O_Fij** (optional): Observed flow values for model validation\r\n\r\n## Decay Functions\r\n\r\nThe package supports six distance decay functions:\r\n\r\n### 1. Exponential Decay\r\n```python\r\nf(d) = exp(-\u03b2 * d)\r\n```\r\n\r\n### 2. Power Decay\r\n```python\r\nf(d) = d^(-\u03b2)\r\n```\r\n\r\n### 3. Sigmoid Decay\r\n```python\r\nf(d) = 1 / (1 + exp(steepness * (d - \u03b2)))\r\n```\r\n\r\n### 4. Square Root Exponential Decay\r\n```python\r\nf(d) = exp(-\u03b2 * sqrt(d))\r\n```\r\n\r\n### 5. Gaussian Decay\r\n```python\r\nf(d) = exp(-\u03b2 * (d/d0)\u00b2)\r\n```\r\n\r\n### 6. Log-Squared Decay\r\n```python\r\nf(d) = exp(-\u03b2 * log(d)\u00b2)\r\n```\r\n\r\n## API Reference\r\n\r\n### R2SFCA Class\r\n\r\n#### Constructor\r\n```python\r\nR2SFCA(df, demand_col, supply_col, travel_cost_col, demand_id_col, supply_id_col, \r\n       observed_flow_col=None, decay_function='exponential', epsilon=1e-15)\r\n```\r\n\r\n#### Methods\r\n\r\n##### `dist_decay(beta, **kwargs)`\r\nCalculate distance decay values using the specified decay function.\r\n\r\n**Parameters:**\r\n- `beta`: Primary decay parameter\r\n- `**kwargs`: Additional parameters (steepness for sigmoid, d0 for gaussian)\r\n\r\n**Note:** Uses the travel_cost data stored in the model during initialization.\r\n\r\n**Returns:** Decay values\r\n\r\n##### `fij(beta, **kwargs)`\r\nCalculate Fij values (demand-side accessibility) using 2SFCA method.\r\n\r\n**Parameters:**\r\n- `beta`: Decay parameter\r\n- `**kwargs`: Additional parameters for decay function\r\n\r\n**Returns:** Fij values\r\n\r\n##### `tij(beta, **kwargs)`\r\nCalculate Tij values (supply-side accessibility) using i2SFCA method.\r\n\r\n**Parameters:**\r\n- `beta`: Decay parameter\r\n- `**kwargs`: Additional parameters for decay function\r\n\r\n**Returns:** Tij values\r\n\r\n##### `search_fij(beta_range, param2_range=None, metrics=None, normalize=True)`\r\nPerform grid search over parameter ranges to find optimal values.\r\n\r\n**Parameters:**\r\n- `beta_range`: (start, end, step) for beta parameter\r\n- `param2_range`: (start, end, step) for second parameter\r\n- `metrics`: List of evaluation metrics to calculate\r\n- `normalize`: Whether to normalize Fij and Tij for cross-entropy calculation\r\n\r\n**Returns:** DataFrame with grid search results\r\n\r\n##### `solve_beta(metric='cross_entropy', param2=None, method='minimize', **kwargs)`\r\nSolve for optimal beta parameter using optimization.\r\n\r\n**Parameters:**\r\n- `metric`: Metric to optimize\r\n- `param2`: Second parameter value\r\n- `method`: Optimization method ('minimize' or 'adam')\r\n- `**kwargs`: Additional optimization parameters\r\n\r\n**Returns:** Dictionary with optimization results\r\n\r\n##### `access_score(beta, **kwargs)`\r\nCalculate accessibility scores (Ai) for each demand location.\r\n\r\n**Parameters:**\r\n- `beta`: Decay parameter\r\n- `**kwargs`: Additional parameters for decay function\r\n\r\n**Returns:** Series with accessibility scores\r\n\r\n##### `crowd_score(beta, **kwargs)`\r\nCalculate crowdedness scores (Cj) for each supply location.\r\n\r\n**Parameters:**\r\n- `beta`: Decay parameter\r\n- `**kwargs`: Additional parameters for decay function\r\n\r\n**Returns:** Series with crowdedness scores\r\n\r\n## Evaluation Metrics\r\n\r\nThe package provides several evaluation metrics:\r\n\r\n- **Cross Entropy**: Measures the difference between Fij and Tij distributions\r\n- **Correlation**: Pearson correlation coefficient between Fij and Tij\r\n- **RMSE**: Root Mean Square Error\r\n- **MSE**: Mean Square Error\r\n- **MAE**: Mean Absolute Error\r\n- **Fij-Flow Correlation**: Correlation between estimated Fij and observed flows\r\n- **Tij-Flow Correlation**: Correlation between estimated Tij and observed flows\r\n\r\n## Visualization\r\n\r\n### Grid Search Results\r\n```python\r\nfrom r2sfca.utils import plot_grid_search_results\r\n\r\n# Plot grid search results\r\nfig = plot_grid_search_results(\r\n    results_df=results,\r\n    x_col='beta',\r\n    y_cols=['cross_entropy', 'correlation'],\r\n    title='Grid Search Results',\r\n    save_path='grid_search.png'\r\n)\r\n```\r\n\r\n### Model Comparison\r\n```python\r\nfrom r2sfca.utils import plot_model_comparison\r\n\r\n# Compare multiple models\r\nfig = plot_model_comparison(\r\n    results_dfs=[results1, results2, results3],\r\n    labels=['Gaussian', 'Exponential', 'Power'],\r\n    y_col='fij_flow_correlation',\r\n    title='Model Comparison',\r\n    save_path='model_comparison.png'\r\n)\r\n```\r\n\r\n### Summary Table\r\n```python\r\nfrom r2sfca.utils import create_summary_table\r\n\r\n# Create summary table\r\nsummary = create_summary_table(\r\n    results_dfs=[results1, results2, results3],\r\n    labels=['Gaussian', 'Exponential', 'Power'],\r\n    metric='cross_entropy',\r\n    minimize=True\r\n)\r\n```\r\n\r\n## Examples\r\n\r\n### Example 1: Basic Usage\r\n```python\r\nimport pandas as pd\r\nimport numpy as np\r\nfrom r2sfca import R2SFCA\r\n\r\n# Create sample data\r\nnp.random.seed(42)\r\nn_demand = 100\r\nn_supply = 50\r\n\r\ndata = []\r\nfor i in range(n_demand):\r\n    for j in range(n_supply):\r\n        data.append({\r\n            'DemandID': i,\r\n            'SupplyID': j,\r\n            'Demand': np.random.poisson(1000),\r\n            'Supply': np.random.poisson(100),\r\n            'TravelCost': np.random.exponential(10),\r\n            'O_Fij': np.random.poisson(50)\r\n        })\r\n\r\ndf = pd.DataFrame(data)\r\n\r\n# Initialize model\r\nmodel = R2SFCA(\r\n    df=df,\r\n    demand_col='Demand',\r\n    supply_col='Supply',\r\n    travel_cost_col='TravelCost',\r\n    demand_id_col='DemandID',\r\n    supply_id_col='SupplyID',\r\n    observed_flow_col='O_Fij',\r\n    decay_function='gaussian'\r\n)\r\n\r\n# Calculate accessibility scores\r\naccessibility = model.access_score(beta=2.0)\r\nprint(f\"Accessibility scores: {accessibility.describe()}\")\r\n```\r\n\r\n### Example 2: Parameter Optimization\r\n```python\r\n# Grid search\r\nresults = model.search_fij(\r\n    beta_range=(0.0, 5.0, 0.2),\r\n    metrics=['cross_entropy', 'correlation', 'rmse']\r\n)\r\n\r\n# Find optimal beta\r\noptimal_idx = results['cross_entropy'].idxmin()\r\noptimal_beta = results.loc[optimal_idx, 'beta']\r\nprint(f\"Optimal beta: {optimal_beta}\")\r\n\r\n# Adam optimization\r\noptimization_result = model.solve_beta(\r\n    metric='cross_entropy',\r\n    method='adam',\r\n    num_epochs=200\r\n)\r\nprint(f\"Optimized beta: {optimization_result['optimal_beta']}\")\r\n```\r\n\r\n### Example 3: Model Comparison\r\n```python\r\n# Compare different decay functions\r\ndecay_functions = ['exponential', 'power', 'gaussian', 'sigmoid']\r\nresults_list = []\r\nlabels = []\r\n\r\nfor decay_func in decay_functions:\r\n    model_temp = R2SFCA(\r\n        df=df,\r\n        demand_col='Demand',\r\n        supply_col='Supply',\r\n        travel_cost_col='TravelCost',\r\n        demand_id_col='DemandID',\r\n        supply_id_col='SupplyID',\r\n        observed_flow_col='O_Fij',\r\n        decay_function=decay_func\r\n    )\r\n    \r\n    results = model_temp.search_fij(\r\n        beta_range=(0.0, 3.0, 0.1),\r\n        metrics=['cross_entropy', 'fij_flow_correlation']\r\n    )\r\n    \r\n    results_list.append(results)\r\n    labels.append(decay_func.title())\r\n\r\n# Plot comparison\r\nfrom r2sfca.utils import plot_model_comparison\r\n\r\nfig = plot_model_comparison(\r\n    results_dfs=results_list,\r\n    labels=labels,\r\n    y_col='fij_flow_correlation',\r\n    title='Decay Function Comparison'\r\n)\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Custom Decay Function Parameters\r\n```python\r\n# Gaussian decay with custom d0 parameter\r\nmodel = R2SFCA(df, decay_function='gaussian')\r\nfij = model.fij(beta=2.0, d0=30.0)  # Custom d0 value\r\n\r\n# Sigmoid decay with custom steepness\r\nmodel = R2SFCA(df, decay_function='sigmoid')\r\nfij = model.fij(beta=1.5, steepness=5.0)  # Custom steepness\r\n```\r\n\r\n### Multiple Parameter Optimization\r\n```python\r\n# Grid search with second parameter\r\nresults = model.search_fij(\r\n    beta_range=(0.0, 3.0, 0.1),\r\n    param2_range=(1.0, 10.0, 0.5),  # For sigmoid steepness\r\n    metrics=['cross_entropy', 'correlation']\r\n)\r\n```\r\n\r\n### Custom Evaluation Metrics\r\n```python\r\n# Use custom metrics\r\nresults = model.search_fij(\r\n    beta_range=(0.0, 3.0, 0.1),\r\n    metrics=['cross_entropy', 'rmse', 'mae', 'fij_flow_correlation']\r\n)\r\n```\r\n\r\n## Performance Considerations\r\n\r\n- For large datasets, consider using the Adam optimizer instead of grid search\r\n- The package uses vectorized operations for efficiency\r\n- Memory usage scales with the number of demand-supply pairs\r\n- Consider sampling for very large datasets during parameter optimization\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Citation\r\n\r\nIf you use this package in your research, please cite:\r\n\r\n```\r\n@article{r2sfca2025,\r\n   author = {Liu, Lingbo and Wang, Fahui},\r\n   title = {Reconciling 2SFCA and i2SFCA via distance decay parameterization},\r\n   journal = {International Journal of Geographical Information Science},\r\n   pages = {1-18},\r\n   note = {doi: 10.1080/13658816.2025.2562255},\r\n   ISSN = {1365-8816},\r\n   DOI = {10.1080/13658816.2025.2562255},\r\n   url = {https://doi.org/10.1080/13658816.2025.2562255},\r\n   year = {2025},\r\n   type = {Journal Article}\r\n}\r\n```\r\n\r\n## Support\r\n\r\nFor questions and support, please open an issue on GitHub or contact the development team.\r\n",
    "bugtrack_url": null,
    "license": "MIT License\r\n        \r\n        Copyright (c) 2025 Lingbo Liu, Fahui Wang\r\n        \r\n        Permission is hereby granted, free of charge, to any person obtaining a copy\r\n        of this software and associated documentation files (the \"Software\"), to deal\r\n        in the Software without restriction, including without limitation the rights\r\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n        copies of the Software, and to permit persons to whom the Software is\r\n        furnished to do so, subject to the following conditions:\r\n        \r\n        The above copyright notice and this permission notice shall be included in all\r\n        copies or substantial portions of the Software.\r\n        \r\n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n        SOFTWARE.\r\n        ",
    "summary": "Reconciled Two-Step Floating Catchment Area Model for spatial accessibility analysis",
    "version": "1.1.3",
    "project_urls": {
        "Documentation": "https://r2sfca.readthedocs.io",
        "Homepage": "https://github.com/urbananalytics/r2sfca",
        "Issues": "https://github.com/urbananalytics/r2sfca/issues",
        "Repository": "https://github.com/urbananalytics/r2sfca"
    },
    "split_keywords": [
        "spatial analysis",
        " accessibility",
        " 2sfca",
        " i2sfca",
        " gis",
        " urban analytics"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "56681e0aaed3e71a7d102d19772133a9593e0448a2b9b752908636f1906f8ecc",
                "md5": "4c50c57fbfe29d511689609f1c7fa843",
                "sha256": "f5ce2fec1e04e34f2ff288a53df25026185aa5b9fb60571d23756070ea603c0b"
            },
            "downloads": -1,
            "filename": "r2sfca-1.1.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4c50c57fbfe29d511689609f1c7fa843",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 15886,
            "upload_time": "2025-10-14T00:57:32",
            "upload_time_iso_8601": "2025-10-14T00:57:32.266427Z",
            "url": "https://files.pythonhosted.org/packages/56/68/1e0aaed3e71a7d102d19772133a9593e0448a2b9b752908636f1906f8ecc/r2sfca-1.1.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "770d2428323bf239e36c38d032a709275801c9fb6c30ef8e57ff813299d7d1d3",
                "md5": "937873f15d89b9fe8bf9deb612c2c012",
                "sha256": "281b11f2e2420577b53c136e1f8455f16065ba855d2e396fcf2d93349086a6b2"
            },
            "downloads": -1,
            "filename": "r2sfca-1.1.3.tar.gz",
            "has_sig": false,
            "md5_digest": "937873f15d89b9fe8bf9deb612c2c012",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 19236,
            "upload_time": "2025-10-14T00:57:33",
            "upload_time_iso_8601": "2025-10-14T00:57:33.361063Z",
            "url": "https://files.pythonhosted.org/packages/77/0d/2428323bf239e36c38d032a709275801c9fb6c30ef8e57ff813299d7d1d3/r2sfca-1.1.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-14 00:57:33",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "urbananalytics",
    "github_project": "r2sfca",
    "github_not_found": true,
    "lcname": "r2sfca"
}