Metadata-Version: 2.1
Name: crossfire
Version: 0.2.0.2
Summary: crossfire: Download spatial data sets from crossfire project
Home-page: https://fogocruzado.org.br/
Author: Felipe Barros
Author-email: felipe.b4rros@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: DateTime (>=4.3,<5.0)
Requires-Dist: geopandas (>=0.10.1,<0.11.0)
Requires-Dist: pandas (>=1.3.3,<2.0.0)
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: requests (>=2.26.0,<3.0.0)
Project-URL: Repository, https://github.com/voltdatalab/crossfire
Description-Content-Type: text/markdown


<img src="https://raw.githubusercontent.com/voltdatalab/crossfire/master/crossfire_hexagono.png" width="130px" alt="hexagon crossfire"/>


# crossfire

`crossfire` is a package created to give easier access to the datasets of the project [Fogo Cruzado](https://fogocruzado.org.br/), which is a digital collaboration platform to register gun shootings in the metropolitan areas of Rio de Janeiro and Recife.

The package facilitates data extraction from the [project open-data API](https://api.fogocruzado.org.br/), developed by [Volt Data Lab](https://www.voltdata.info/en-lg).

## Installing and loading the package

Currently, the `crossfire` package can be installed directly from pip:

```
pip install crossfire
```

## Functions

`crossfire` has 3 functions: `fogocruzado_signin`, `get_fogocruzado` and `get_cities`.

* `fogocruzado_signin` is used to give access to Fogo Cruzado's API. To access Fogo Cruzado's API, [users should be registered](https://api.fogocruzado.org.br/register) and insert their e-mail and password for authentication. Thus, the function registers these information on the current R session, so that it can be used to obtain the Bearer token to extract data using the API. 


```
>>> from crossfire import fogocruzado_signin
>>> fogocruzado_signin('user@host.com', 'password')
```

* `get_fogocruzado` extracts slices or the whole dataset of shootings registered by Fogo Cruzado. The function returns a data frame, in which each line corresponds to a shooting registered and its information. It can also filter the data according to some parameters,  city/state - `city` and `state` -, initial and final date - `initial_date` and `final_date` -, and the presence of security forces - `security_agent`. One should note that each request using the `crossfire` package needs to be under a 210 days (roughly 7 months) time interval, from any portion of the full dataset.

```
>>> from crossfire import get_fogocruzado
>>> fogocruzado = get_fogocruzado(state=['RJ'])
```

## Other examples

```
from datetime import date
from crossfire import fogocruzado_signin, get_fogocruzado

# Extract data for all registered shootings
fogocruzado = get_fogocruzado(()

# Extract data for shootings in the cities of Rio de Janeiro and Recife in 2018
fogocruzado_rj_recife = get_fogocruzado(
    city = ["Rio de Janeiro, "Recife"],
    initial_date = date(2018, 07, 01),
    final_date = date(2018, 12, 31))

# Extract data from occurents reported by the police and in which security agents were present
fogocruzado_security = get_fogocruzado(security_agent = [1])
```

* `get_cities()` returns a `data.frame` with information about all cities from the Rio de Janeiro and Recife metropolitan areas covered by the Fogo Cruzado initiative.

## More information

For more information on how the package works and for exemples on using the module, see the [tutorial](https://github.com/FelipeSBarros/crossfire_tutorial) repository.

## Python module authors

[Felipe Sodré Mendes Barros](https://github.com/FelipeSBarros)
> Funding: This implementation was funded by CYTED project number 520RT0010. redGeoLIBERO

## API Authors

[Lucas Gelape](https://github.com/lgelape), for [Volt Data Lab](https://www.voltdata.info/en-lg).

## Contributors

[Sérgio Spagnuolo](https://github.com/voltdatalab), [Denisson Silva](https://github.com/silvadenisson) and [Felipe Sodré Mendes Barros](https://github.com/FelipeSBarros).

