deploy: 1fbb5fd

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 233a05fc6d348c0fbf35e0e6c1ecb2fe
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/Acknowledgements/acknowledgements.rst.txt

@@ -0,0 +1,11 @@
+Acknowledgements
+================
+
+We would like to thank the many collaborators who have helped us developing our methodologies. This work has been incorporated into numerous projects that have been supported by the following grants:
+
++ National Science Foundation Graduate Research Fellowship (grant no. DGE-1610403)
++ Future Investigators in NASA Earth and Space Science and Technology (NASA FINESST, grant no. 21-EARTH21-0264)
++ Planet Texas 2050, a research grand challenge at the University of Texas at Austin.
++ U.S. Department of Energy, Office of Science, Biological and Environmental Research Program’s South-East Texas Urban Integrated Field Laboratory under Award Number DE-SC0023216.
+
+

_sources/Background/paper.rst.txt

@@ -0,0 +1,35 @@
+Papers
+======
+
+This Package
+^^^^^^^^^^^^
+
+A paper accompanying this software package will be published in the Journal of Open Source Software. Once published, it will be linked here. 
+
+
+Projects Using This Work
+^^^^^^^^^^^^^^^^^^^^^^^^^
+You can also read the following papers that have explicitly used these methodologies:
+
+- Preisser, M., Passalacqua, P., Bixler, R. P., & Boyles, S. (2023). A network-based analysis of critical resource accessibility during floods. Frontiers in Water, 5, 1278205, `10.3389/frwa.2023.1278205 <https://doi.org/10.3389/frwa.2023.1278205>`_
+
+- Preisser, M., Passalacqua, P., Bixler, R. P., & Hofmann, J. (2022). Intersecting near-real time fluvial and pluvial inundation estimates with sociodemographic vulnerability to quantify a household flood impact index. Hydrology and Earth System Sciences, 26(15), 3941-3964, `10.5194/hess-26-3941-2022 <https://doi.org/10.5194/hess-26-3941-2022>`_
+
+- Bixler, R. P., Yang, E., Richter, S. M., & Coudert, M. (2021). Boundary crossing for urban community resilience: A social vulnerability and multi-hazard approach in Austin, Texas, USA. International Journal of Disaster Risk Reduction, 66, 102613, `10.1016/j.ijdrr.2021.102613 <https://doi.org/10.1016/j.ijdrr.2021.102613>`_
+
+
+Additional Literature
+^^^^^^^^^^^^^^^^^^^^^
+
+Additionally, there are a number of relevant peer-reviewed articles we recommend to users if they are interested in learning more about social vulnerability topics: 
+
+- Cutter, S. L., Boruff, B. J., & Shirley, W. L. (2012). Social vulnerability to environmental hazards. In Hazards vulnerability and environmental justice (pp. 143-160). Routledge.
+
+- Fatemi, F., Ardalan, A., Aguirre, B., Mansouri, N., & Mohammadfam, I. (2017). Social vulnerability indicators in disasters: Findings from a systematic review. International journal of disaster risk reduction, 22, 219-227, `10.1016/j.ijdrr.2016.09.006 <https://doi.org/10.1016/j.ijdrr.2016.09.006>`_
+
+- Flanagan, B. E., Gregory, E. W., Hallisey, E. J., Heitgerd, J. L., & Lewis, B. (2011). A social vulnerability index for disaster management. Journal of homeland security and emergency management, 8(1), 0000102202154773551792, `10.2202/1547-7355.1792 <https://doi.org/10.2202/1547-7355.1792>`_
+
+- Spielman, S. E., Tuccillo, J., Folch, D. C., Schweikert, A., Davies, R., Wood, N., & Tate, E. (2020). Evaluating social vulnerability indicators: criteria and their application to the Social Vulnerability Index. Natural hazards, 100, 417-436, `10.1007/s11069-019-03820-z <https://doi.org/10.1007/s11069-019-03820-z>`_
+
+
+

_sources/Background/understanding.rst.txt

@@ -0,0 +1,71 @@
+Understanding Iterative Factor Analysis Results
+===============================================
+
+One of the outputs of the SVI workflow is an excel file containing documentation describing the characteristics of the index. This file can be found in the Documentation project folder and has the following naming convention:
+
+- folder location: ``{file_path}/{project_name}/{Documentation}/`` 
+- file name: ``{project_name}_{year}_{boundary}_{config_file}.xlsx``
+
+Each tab of the excel sheet contains pertinent information regrading the iterative factor analysis SVI. The below subsections discusses what information is stored in each sheet and shows examples from an SVI run using the standard set of 27 variables (see :doc:`background <../Background/background>` for more information) for Travis County, Texas in 2017 at the block group level. 
+
+
+Significant Components
+----------------------
+This sheet shows what components are significantly contributing to each factor from the final factor analysis. The number of iterations can be determined based on the name of each factor. For example, in this run *'F2'* means that this went through three rounds of factor analysis (zero-based numbering rules). As can be seen, there are 5 factors in the final index. Information on which variables contribute to which factor is useful in determining "themes" for the factors (e.g., wealth theme, social characteristics theme, etc.). In this example, one could identify the first factor as Social Status, and the second factor as Economic Status. These are for description only and will be unique based on the study area and year being analyzed. They may or may not be easily definable into distinct themes, but do show what variables are correlated within a study area. 
+
+.. figure:: ../Background/sig_comp_.png
+   :alt: Table of significant components for 2017 Travis County, Texas Block Group SVI estimate
+
+*Table 1: Significant components for 2017 Travis County, Texas Block Group SVI estimate*
+
+
+
+Loading Factors
+---------------
+Based on the variables within the final index, each has a loading factor associated with it for each factor. This information is critical in determining the weights for each variable for each factor when calculating the final index. For every boundary in the study area and for every factor, the variable is multiplied by the loading factor and summed within each factor. This is how the factor scores are determined. 
+
+.. figure:: ../Background/loading_fac_.png
+   :alt: Table of loading factors for 2017 Travis County, Texas Block Group SVI estimate
+
+*Table 2: Loading factors for 2017 Travis County, Texas Block Group SVI estimate*
+
+
+
+All Refactor Variances
+----------------------
+This shows the four main variance statistics associated with a factor analysis for each iteration.
+
+- SS Loadings: The sum of the squared loadings for the factor. If a factor’s SS loading is greater than 1 it is worth keeping.
+- Proportion Variance: The proportion of the variance that a factor accounts for. The first factor will have the highest proportion, due to our rotation earlier, and subsequent factors will have a decreasing proportion of explained variance. **When calculating the final index, each factor is multiplied by its proportion of variance to weight the variables.**
+- Cumulative Variance: The cumulative sum of the variance that is explained with each factor. The overall cumulative variance is how much of the original system’s variables are explained with this new reduced dimensionality. **This is important because it shows us how much of the original data’s variance we are losing.** If we are losing too much, then we need to reconsider how many factors we have reduced down to. If it is too close to 100% then we can theoretically reduce down more.
+- Ratio Variance: Ratio of proportion of variance to cumulative variance.
+
+For most studies, especially exploratory analyses, it is acceptable to have a cumulative variance as low as 60%, and sometimes as low as 50% [1]_ [2]_ [3]_ . 
+
+
+Final Variances
+---------------
+An abbreviated version of All Refactor Variances, showing only the final table for the final iteration.
+
+.. figure:: ../Background/final_fac_.png
+   :alt: Table of Final factor analysis variance statistics for 2017 Travis County, Texas Block Group SVI estimate
+
+*Table 4: Final factor analysis variance statistics for 2017 Travis County, Texas Block Group SVI estimate*
+
+
+
+Included and Excluded
+---------------------
+contains the lists of what variables make the final index and which variables are excluded due to not significantly contributing to a any factors. This can be useful for double checking that the index is including variables you would likely expect to find given your study area. 
+
+
+
+References
+----------
+
+.. [1] Hair, J. S., Black, W. C., Babin, B. J., Anderson, R. E. & Tatham, R. L. (2006). Multivariate Data Analysis. New Jersey: Prentice-Hall.
+
+.. [2] Peterson, R. A. (2000). A Meta-Analysis of Variance Accounted for and Factor Loadings in Exploratory Factor Analysis. Marketing Letters, 11(3), 261–275. http://www.jstor.org/stable/40239882
+
+.. [3] Advice for Exploratory Factor Analyses: `Link <http://www.open-access.bcu.ac.uk/6076/1/__staff_shares_storage%20500mb_Library_ID112668_Stats%20Advisory_New%20Statistics%20Workshops_18ExploratoryFactorAnalysis_ExploratoryFactorAnalysis4.pdf>`_
+

_sources/Contributions/contributions.rst.txt

@@ -0,0 +1,15 @@
+Issues, Questions, and Contributions
+=====================================
+
+We welcome contributions to the dorado package in the form of pull requests and issues made in the source `repository <https://github.com/mdp0023/SVInsight>`_.
+
+Issues and Questions
+--------------------
+
+If you are having any problems using SVInsight we suggest opening an `issue <https://github.com/mdp0023/SVInsight/issues>`_.When you open an issue, please provide a clear description of what your scenario is, and what error message you are receiving. If possible, please include a minimal working example of some code that breaks, and the error output you receive. If there is some functionality you would like to see added to SVInsight you can also open an issue up to discuss that. This can be code you plan to write and contribute, or it can be something you would like to have available but are not comfortable coding yourself. Either way we are happy to help!
+
+
+Pull Requests
+-------------
+
+If you have a feature that you would like to propose be integrated into dorado, then you should open a `pull request <https://github.com/mdp0023/SVInsight/pulls>`_. To create a pull request, we recommend first `forking <https://guides.github.com/activities/forking/>`_ the repository, and then creating a separate branch to develop your feature (for reference see the `GitHub flow guide <https://guides.github.com/introduction/flow/>`_ and this `Git branching <https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging>`_ guide). Then you can commit and develop your feature in your branch. We ask that new features be accompanied by additional unit tests, to ensure that they operate as expected. For unit testing, we use `pytest <https://docs.pytest.org/en/latest/>`_. When you are satisfied with the code you have developed, you can open a pull request to the main branch of the project repository. Please write a concise and descriptive title for the pull request, and provide a clear description of what the feature does and why you are proposing its addition to the project.

_sources/Examples/examples.rst.txt

@@ -0,0 +1,13 @@
+Examples
+========
+
+Bellow you will find a Jupyter Notebook that computes an SVI for the Southeast Texas region. More example scripts can be found on the `GitHub page in the Examples folder <https://github.com/mdp0023/SVInsight/tree/main/examples>`_.
+
+
+
+Example Notebooks
+#################
+.. toctree::
+   :maxdepth: 2
+
+   SVInsight_example_SETx.ipynb

_sources/Getting_Started/install.rst.txt

@@ -0,0 +1,45 @@
+Install
+=======
+`SVInsight` has been tested with Python 3.9 through 3.12. It also requires the following dependencies: `census <https://pypi.org/project/census/>`_, `factor_analyzer <https://pypi.org/project/factor-analyzer/>`_, `geopandas <https://geopandas.org/en/stable/>`_,  `numpy <https://numpy.org/install/>`_, `pandas <https://pandas.pydata.org/docs/getting_started/overview.html#>`_, `pytest <https://docs.pytest.org/en/7.1.x/getting-started.html>`_, `PyYAML <https://pypi.org/project/PyYAML/>`_, `scikit_learn <https://scikit-learn.org/stable/>`_, `openpyxl <https://pypi.org/project/openpyxl/>`_, and `matplotlib <https://matplotlib.org/stable/users/installing/index.html>`_.
+
+Installation via *pip*
+----------------------
+
+To *pip*-install this package use the following command:
+
+.. code-block:: console
+
+   $ pip install SVInsight
+
+`SVInsight` can then be imported into python:
+
+.. code-block:: python
+
+    >>> from svinsight import SVInsight as svi
+
+SVInsight has dependencies that rely on gdal, which may require its own prior installation based on your operating system and coding environment. For example:
+
+* On macOS:
+
+  .. code-block:: console
+
+      brew install gdal
+
+* On Ubuntu:
+
+  .. code-block:: console
+
+      sudo apt-get install gdal-bin libgdal-dev
+
+* On Windows:
+
+  .. code-block:: console
+
+      pip install gdal==<version> --find-links https://www.lfd.uci.edu/~gohlke/pythonlibs/
+
+Installation via *conda*
+------------------------
+
+This package will be available from conda-forge soon.
+
+

_sources/Getting_Started/quickstart.rst.txt

@@ -0,0 +1,57 @@
+Getting Started
+===============
+
+Quickstart
+----------
+
+This is a quick guide to using SVInsight. In this demonstration, we show how to load and create the SVInsight object, determine an area of interest, set a boundary level (e.g., tract or block groups), download the necessary boundary and raw data, calculate input variables, and compute the social vulnerability estimate. 
+
+First we load the SVInsight package, set the necessary variables, and create the SVInsight object. 
+
+.. doctest::
+
+    >>> from svinsight import SVInsight as svi
+    >>> project_name = 'YOUR PROJECT NAME HERE'
+    >>> file_path = "YOUR PARENT FOLDER HERE"
+    >>> api_key = 'YOUR CENSUS API KEY HERE'
+    >>> geoids = ['48453']
+    >>> project = svi(project_name, file_path, api_key, geoids)
+
+These variables create the instance of a project. Each have the following purpose: 
+
+- ``project_name``: This is the name of your project. In this case, it's 'Travis_County_SVI'. The project name is used when saving files throughout the project.
+- ``file_path``: This is the path to the parent folder where your project files will be stored. Replace "YOUR PARENT FOLDER HERE" with the actual path. Creating the SVInsight object automatically creates the necessary file structure needed for your project based on the ``file_path`` and ``project_name``. 
+- ``api_key``: This is your Census API key. Replace 'YOUR CENSUS API KEY HERE' with your actual API key. You can obtain an API key from the `Census Bureau's developer page <https://www.census.gov/data/developers/data-sets.html>`_.
+- ``geoids``: This is a list of geographic identifiers for the areas you're interested in. In this case, it's ['48453'], which represents Travis County, Texas. The necessary geographic identifiers for your state or county of interest can be obtained from this `FCC page <https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt>`_.  
+
+
+Each instance of SVInsight can be seen as a standalone project for a constant study area. Within each project, the user can explore different vulnerability estimates based on different years or boundaries (e.g., block group versus tract). 
+
+In this quickstart, we will examine a vulnerability estimate for Travis County using 2019 data at the block group level. 
+
+.. doctest::
+
+    >>> boundary = 'bg'
+    >>> year = 2019
+    >>> config_file = 'config_file'
+
+The simplest workflow is as follows: 
+
+(1) Extract boundaries 
+(2) Extract Census data 
+(3) Configure variables  
+(4) Calculate vulnerability estimate 
+
+.. doctest::
+
+    >>> project.boundaries_data(boundary, year)
+    >>> project.census_data(boundary, year)
+    >>> project.configure_variables(config_file)
+    >>> project.calculate_svi(config_file, boundary, year)
+
+The output SVI .csv and .gpkg files built will be saved with the following file format: 
+
+- folder location: ``{file_path}/{project_name}/{SVIs}/`` 
+- file name: ``{project_name}_{year}_{boundadry}_{config_file}_svi``
+
+More detailed examples of the complete functionality of SVInsight can be found under :doc:`Examples <../Examples/examples>`.