diff --git a/src/checklist.jl b/src/checklist.jl index da3aa27..665e58a 100644 --- a/src/checklist.jl +++ b/src/checklist.jl @@ -1,7 +1,21 @@ -include("checklist_docstrings.jl") - """ -$docstring_checklist_df + PRISMA.checklist_df()::DataFrame + +returns a template PRISMA checklist as a `DataFrame` + +## Returns + +- `DataFrame`: the template dataframe + +## Example + +```jldoctest +julia> using PRISMA + +julia> isa(checklist_df(), DataFrame) +true +``` + """ function checklist_df()::DataFrame cols::Vector{String} = [ @@ -425,7 +439,47 @@ function complete_dataframe(paper::AbstractString)::DataFrame end """ -$docstring_checklist + PRISMA.checklist(paper::AbstractString)::Checklist + PRISMA.checklist(bytes::Vector{UInt8})::Checklist + +Returns a completed PRISMA checklist as the type `Checklist`. The `Checklist` +type includes a completed checklist as a `DataFrame` and the metadata of the +paper as a `OrderedDict`. The `paper` argument can be a path to a pdf file or +an array of bytes. This function uses the C++ library `Poppler` via `Poppler_jll` +to parse the pdf and the natural language processing functionality in Julia via +[`Transformers.jl`](https://github.com/chengchingwen/Transformers.jl) to +find items from the checklist in the paper and populate the +`Comments or location in manuscript` and `Yes/No/NA` columns in the `DataFrame` +from `checklist_df()`. + +The following metadata is parsed from the pdf file and stored in the `OrderedDict` as: + +- `"title"`: the title of the paper +- `"subject"`: the subject of the paper +- `"author"`: the author of the paper +- `"creator"`: the creator of the paper +- `"producer"`: the producer of the paper +- `"creation date"`: the date the paper was created +- `"modification date"`: the date the paper was last modified +- `"pages"`: the number of pages in the paper +- `"paper size"`: the size of the paper +- `"paper rotation"`: the rotation of the paper +- `"file size"`: the size of the pdf file +- `"optimized"`: whether the pdf was optimized +- `"pdf version"`: the version of the pdf + +All keys and values in the dictionary ar eof type `String`. +If the parsing fails the value will be an empty string. + +## Arguments + +- `paper::AbstractString`: a path to a pdf file as a string +- `bytes::Vector{UInt8}`: the pdf data as an array of bytes + +## Returns + +- `Checklist`: a completed checklist with the paper's metadata + """ function checklist(paper::AbstractString)::Checklist return Checklist( @@ -477,22 +531,75 @@ function Base.show(io::IO, ::MIME"text/csv", cl::Checklist)::Nothing end """ -$docstring_checklist_read + checklist_read(fn::AbstractString)::DataFrame + +reads the template data to a `DataFrame` + +## Arguments + +- `fn::AbstractString`: the name of the file to read + +## Returns + +- `DataFrame`: the template dataframe + +## Example + +```jldoctest +julia> using PRISMA + +julia> checklist_template() +"checklist.csv" + +julia> isa(checklist_read("checklist.csv"), DataFrame) +true +``` + """ function checklist_read(fn::AbstractString="checklist.csv")::DataFrame return CSV.read(fn, DataFrame) end """ -$docstring_checklist_save + checklist_save(out::Any, cl::Checklist) + checklist_save(out::Any, df::DataFrame) + +saves a `Checklist` as a CSV. + +## Arguments + +- `out::Any`: Accepts the same types as [`CSV.write`](https://csv.juliadata.org/stable/writing.html#CSV.write) +- `cl::Checklist`: the checklist to save +- `df::DataFrame`: the dataframe to save + """ -function checklist_save(fn::AbstractString, cl::Checklist) - return CSV.write(fn, cl.dataframe) +function checklist_save(out::Any, cl::Checklist) + return CSV.write(out, cl.dataframe) +end + +function checklist_save(out::Any, df::DataFrame) + return CSV.write(out, df) end """ -$docstring_checklist_template + checklist_template(out::Any="checklist.csv") + +saves a template checklist `DataFrame` as a CSV. + +## Arguments + +- `out::Any`: Accepts the same types as [`CSV.write`](https://csv.juliadata.org/stable/writing.html#CSV.write) + +## Example + +```jldoctest +julia> using PRISMA + +julia> checklist_template() +"checklist.csv" +``` + """ -function checklist_template(fn::AbstractString="checklist.csv") - return CSV.write(fn, checklist_df()) +function checklist_template(out::Any="checklist.csv") + return CSV.write(out, checklist_df()) end diff --git a/src/checklist_docstrings.jl b/src/checklist_docstrings.jl deleted file mode 100644 index 980004a..0000000 --- a/src/checklist_docstrings.jl +++ /dev/null @@ -1,127 +0,0 @@ -const docstring_checklist::String = -""" - PRISMA.checklist(paper::AbstractString)::Checklist - PRISMA.checklist(bytes::Vector{UInt8})::Checklist - -Returns a completed PRISMA checklist as the type `Checklist`. The `Checklist` -type includes a completed checklist as a `DataFrame` and the metadata of the -paper as a `OrderedDict`. The `paper` argument can be a path to a pdf file or -an array of bytes. This function uses the C++ library `Poppler` via `Poppler_jll` -to parse the pdf and the natural language processing functionality in Julia via -[`Transformers.jl`](https://github.com/chengchingwen/Transformers.jl) to -find items from the checklist in the paper and populate the -`Comments or location in manuscript` and `Yes/No/NA` columns in the `DataFrame` -from `checklist_df()`. - -The following metadata is parsed from the pdf file and stored in the `OrderedDict` as: - -- `"title"`: the title of the paper -- `"subject"`: the subject of the paper -- `"author"`: the author of the paper -- `"creator"`: the creator of the paper -- `"producer"`: the producer of the paper -- `"creation date"`: the date the paper was created -- `"modification date"`: the date the paper was last modified -- `"pages"`: the number of pages in the paper -- `"paper size"`: the size of the paper -- `"paper rotation"`: the rotation of the paper -- `"file size"`: the size of the pdf file -- `"optimized"`: whether the pdf was optimized -- `"pdf version"`: the version of the pdf - -All keys and values in the dictionary ar eof type `String`. -If the parsing fails the value will be an empty string. - -## Arguments - -- `paper::AbstractString`: a path to a pdf file as a string -- `bytes::Vector{UInt8}`: the pdf data as an array of bytes - -## Returns - -- `Checklist`: a completed checklist with the paper's metadata - -""" - -const docstring_checklist_df::String = -""" - PRISMA.checklist_df()::DataFrame - -returns a template PRISMA checklist as a `DataFrame` - -## Returns - -- `DataFrame`: the template dataframe - -## Example - -```jldoctest -julia> using PRISMA - -julia> isa(checklist_df(), DataFrame) -true -``` - -""" - -const docstring_checklist_read::String = -""" - checklist_read(fn::AbstractString)::DataFrame - -reads the template data to a `DataFrame` - -## Arguments - -- `fn::AbstractString`: the name of the file to read - -## Returns - -- `DataFrame`: the template dataframe - -## Example - -```jldoctest -julia> using PRISMA - -julia> checklist_template() -"checklist.csv" - -julia> isa(checklist_read("checklist.csv"), DataFrame) -true -``` - -""" - -const docstring_checklist_template::String = -""" - checklist_template(fn::AbstractString="checklist.csv") - -saves a template checklist `DataFrame` as a CSV. - -## Arguments - -- `fn::AbstractString`: the name of the file to save - -## Example - -```jldoctest -julia> using PRISMA - -julia> checklist_template() -"checklist.csv" -``` - -""" - -const docstring_checklist_save::String = -""" - checklist_save(fn::AbstractString, cl::Checklist) - -saves a `Checklist` as a CSV. - -## Arguments - -- `fn::AbstractString`: the name of the file to save -- `cl::Checklist`: the checklist to save - -""" diff --git a/src/flow_diagram.jl b/src/flow_diagram.jl index 32d652f..3b63425 100644 --- a/src/flow_diagram.jl +++ b/src/flow_diagram.jl @@ -1,7 +1,21 @@ -include("flow_diagram_docstrings.jl") - """ -$docstring_flow_diagram_df + flow_diagram_df()::DataFrame + +returns the template that is used to create the flow diagram as a `DataFrame`. + +## Returns + +- `DataFrame`: the template dataframe + +## Example + +```jldoctest +julia> using PRISMA + +julia> isa(flow_diagram_df(), DataFrame) +true +``` + """ function flow_diagram_df()::DataFrame cols::Vector{String} = ["box_num", "box_text", "result"] @@ -53,17 +67,58 @@ function flow_diagram_df()::DataFrame end """ -$docstring_flow_diagram_read + flow_diagram_read(fn::AbstractString="flow_diagram.csv")::DataFrame + +reads the template data from a `CSV` file + +## Arguments + +- `fn::AbstractString`: the name of the file to read + +## Returns + +- `DataFrame`: the template dataframe + +## Example + +```jldoctest +julia> using PRISMA + +julia> flow_diagram_template() +"flow_diagram.csv" + +julia> isa(flow_diagram_read("flow_diagram.csv"), DataFrame) +true +``` + """ function flow_diagram_read(fn::AbstractString="flow_diagram.csv")::DataFrame return CSV.read(fn, DataFrame) end """ -$docstring_flow_diagram_template + PRISMA.flow_diagram_template(out::Any="flow_diagram.csv") + +saves the template data to create a flow diagram as a CSV file. + +## Arguments + +- `out::Any`: Accepts the same types as [`CSV.write`](https://csv.juliadata.org/stable/writing.html#CSV.write) + +## Example + +calling the function will create a CSV file called `flow_diagram.csv`: + +```jldoctest +julia> using PRISMA + +julia> flow_diagram_template() +"flow_diagram.csv" +``` + """ -function flow_diagram_template(fn::AbstractString="flow_diagram.csv") - return CSV.write(fn, flow_diagram_df()) +function flow_diagram_template(out::Any="flow_diagram.csv") + return CSV.write(out, flow_diagram_df()) end """ @@ -437,7 +492,81 @@ const FLOW_DIAGRAM_ARROW_POSITIONS::Dict{String,LittleDict{Symbol,LittleDict}} = ) """ -$docstring_flow_diagram + flow_diagram( + data::DataFrame=flow_diagram_df(), + background_color::AbstractString="white", + boxes_color::AbstractString="white", + grayboxes::Bool=true, + grayboxes_color::AbstractString="#f0f0f0", + top_boxes::Bool=true, + top_boxes_borders::Bool=false, + top_boxes_color::AbstractString="#ffc000", + side_boxes::Bool=true, + side_boxes_borders::Bool=false, + side_boxes_color::AbstractString="#95cbff", + previous_studies::Bool=true, + other_methods::Bool=true, + borders::Bool=true, + border_width::Union{AbstractString,Number}=1, + border_color::AbstractString="black", + font::AbstractString="Helvetica", + font_color::AbstractString="black", + font_size::Union{AbstractString,Number}=1, + arrow_head::AbstractString="normal", + arrow_size::Union{AbstractString,Number}=1, + arrow_color::AbstractString="black", + arrow_width::Union{AbstractString,Number}=1)::FlowDiagram + +generates the flow diagram figure from the flow diagram dataframe. + +## Argument + +- `data::DataFrame`: The flow diagram dataframe. Use the data from `flow_diagram_df()` if no data is provided. + +## Keyword Arguments + +- `background_color::String`: The background color of the flow diagram. +- `boxes_color::String`: The color of the boxes. +- `grayboxes::Bool`: Whether to show gray boxes. +- `grayboxes_color::String`: The color of the gray boxes. +- `top_boxes::Bool`: Whether to show top boxes. +- `top_boxes_border::Bool`: Whether to show top boxes border. +- `top_boxes_color::String`: The color of the top boxes. +- `side_boxes::Bool`: Whether to show side boxes. +- `side_boxes_border::Bool`: Whether to show side boxes border. +- `side_boxes_color::String`: The color of the side boxes. +- `previous_studies::Bool`: Whether to show previous studies. +- `other_methods::Bool`: Whether to show other methods. +- `box_border_width::Number`: The border width of the boxes. +- `box_border_color::String`: The border color of the boxes. +- `font::String`: The font of the text. +- `font_color::String`: The color of the text. +- `font_size::Number`: The font size of the text. +- `arrow_color::String`: The color of the arrows. +- `arrow_width::Number`: The width of the arrows. + +## Returns + +- `PRISMA.FlowDiagram`: The flow diagram figure. + +## Example + +```julia +using PRISMA + +# create a template to edit the data in a csv +PRISMA.flow_diagram_template("flow_diagram.csv") + +# create a `DataFrame` from the csv +df::DataFrame = PRISMA.flow_diagram_read("flow_diagram.csv") + +# generate the flow diagram with the `DataFrame` +fd::PRISMA.FlowDiagram = PRISMA.flow_diagram(df) + +# save the flow diagram +PRISMA.flow_diagram_save("flow_diagram.svg", fd) +``` + """ function flow_diagram( data::DataFrame=flow_diagram_df(); diff --git a/src/flow_diagram_docstrings.jl b/src/flow_diagram_docstrings.jl deleted file mode 100644 index ef79b15..0000000 --- a/src/flow_diagram_docstrings.jl +++ /dev/null @@ -1,179 +0,0 @@ -const docstring_flow_diagram::String = -""" - PRISMA.flow_diagram( - data::DataFrame=flow_diagram_df(), - background_color::AbstractString="white", - boxes_color::AbstractString="white", - grayboxes::Bool=true, - grayboxes_color::AbstractString="#f0f0f0", - top_boxes::Bool=true, - top_boxes_borders::Bool=false, - top_boxes_color::AbstractString="#ffc000", - side_boxes::Bool=true, - side_boxes_borders::Bool=false, - side_boxes_color::AbstractString="#95cbff", - previous_studies::Bool=true, - other_methods::Bool=true, - borders::Bool=true, - border_width::Union{AbstractString,Number}=1, - border_color::AbstractString="black", - font::AbstractString="Helvetica", - font_color::AbstractString="black", - font_size::Union{AbstractString,Number}=1, - arrow_head::AbstractString="normal", - arrow_size::Union{AbstractString,Number}=1, - arrow_color::AbstractString="black", - arrow_width::Union{AbstractString,Number}=1)::FlowDiagram - -generates the flow diagram figure from the flow diagram dataframe. - -## Argument - -- `data::DataFrame`: The flow diagram dataframe. Default is `flow_diagram_df()`. - -## Keyword Arguments - -- `background_color::String`: The background color of the flow diagram. Default is `white`. -- `boxes_color::String`: The color of the boxes. Default is `white`. -- `grayboxes::Bool`: Whether to show gray boxes. Default is `true`. -- `grayboxes_color::String`: The color of the gray boxes. Default is `#f0f0f0`. -- `top_boxes::Bool`: Whether to show top boxes. Default is `true`. -- `top_boxes_border::Bool`: Whether to show top boxes border. Default is `false`. -- `top_boxes_color::String`: The color of the top boxes. Default is `#ffc000`. -- `side_boxes::Bool`: Whether to show side boxes. Default is `true`. -- `side_boxes_border::Bool`: Whether to show side boxes border. Default is `false`. -- `side_boxes_color::String`: The color of the side boxes. Default is `#95cbff`. -- `previous_studies::Bool`: Whether to show previous studies. Default is `true`. -- `other_methods::Bool`: Whether to show other methods. Default is ` -- `box_border_width::Number`: The border width of the boxes. Default is `1`. -- `box_border_color::String`: The border color of the boxes. Default is `black`. -- `font::String`: The font of the text. Default is `Helvetica`. -- `font_color::String`: The color of the text. Default is `black`. -- `font_size::Number`: The font size of the text. Default is `10`. -- `arrow_color::String`: The color of the arrows. Default is `black`. -- `arrow_width::Number`: The width of the arrows. Default is `1`. - -## Returns - -- `PRISMA.FlowDiagram`: The flow diagram figure. - -## Example - -```julia -using PRISMA - -# create a template to edit the data in a csv -PRISMA.flow_diagram_template("flow_diagram.csv") - -# create a `DataFrame` from the csv -df::DataFrame = PRISMA.flow_diagram_read("flow_diagram.csv") - -# generate the flow diagram with the `DataFrame` -fd::PRISMA.FlowDiagram = PRISMA.flow_diagram(df) - -# save the flow diagram -PRISMA.flow_diagram_save("flow_diagram.svg", fd) -``` - -""" - -const docstring_flow_diagram_df::String = -""" - PRISMA.flow_diagram_df()::DataFrame - -returns the template that is used to create the flow diagram as a `DataFrame`. - -## Returns - -- `DataFrame`: the template dataframe - -## Example - -```jldoctest -julia> using PRISMA - -julia> isa(flow_diagram_df(), DataFrame) -true -``` - -""" - -const docstring_flow_diagram_read::String = -""" - flow_diagram_read(fn::AbstractString)::DataFrame - -reads the template data from a `CSV` file - -## Arguments - -- `fn::AbstractString`: the name of the file to read - -## Returns - -- `DataFrame`: the template dataframe - -## Example - -```jldoctest -julia> using PRISMA - -julia> flow_diagram_template() -"flow_diagram.csv" - -julia> isa(flow_diagram_read("flow_diagram.csv"), DataFrame) -true -``` - -""" - -const docstring_flow_diagram_save::String = -""" - PRISMA.flow_diagram_save(fn::AbstractString, fd::FlowDiagram) - -writes a `FlowDiagram` as either a file (i.e., any Graphviz supported format) - -## Arguments - -- `fn::AbstractString`: The name of the file to be saved. -- `fd::FlowDiagram`: The flow diagram to be saved. - -## Returns - -- `String`: The path to the saved file. - -## Examples - -```julia -using PRISMA - -fd = PRISMA.flow_diagram() - -PRISMA.flow_diagram_save("flow_diagram.pdf", fd) -PRISMA.flow_diagram_save("flow_diagram.png", fd) -PRISMA.flow_diagram_save("flow_diagram.svg", fd) -``` - -""" - -const docstring_flow_diagram_template::String = -""" - PRISMA.flow_diagram_template(fn::AbstractString="flow_diagram.csv") - -saves the template data to create a flow diagram as a CSV file. - -## Arguments - -- `fn::AbstractString`: the name of the file to saved - -## Example - -calling the function will create a CSV file called `flow_diagram.csv`: - -```jldoctest -julia> using PRISMA - -julia> flow_diagram_template() -"flow_diagram.csv" -``` - -""" \ No newline at end of file